mnemo_engine/store/maintenance.rs
1//! Maintenance: export, rekey, verify, stats, and compaction (which also upgrades v8 files to v9).
2
3use super::*;
4
5impl Mnemo {
6 /// Return the KDF (Argon2id) parameters this file currently uses to
7 /// wrap its DEK. Needed by callers that want to [`rekey`] while
8 /// keeping the file's original protection level (e.g. the Python
9 /// binding's `rekey(fast=False)`, whose docstring promises exactly
10 /// that). FIX-1 R-001.5.
11 pub fn kdf_params(&self) -> KdfParams {
12 self.kdf
13 }
14
15 /// Flush any pending writes, then stream the (encrypted) file to
16 /// `dest` atomically: writes to a sibling temp file in `dest`'s
17 /// parent directory, `sync_all`s it, renames onto `dest`, and
18 /// fsyncs the parent directory on Unix so a crash never leaves a
19 /// partial export.
20 ///
21 /// Refuses when `dest` resolves to the file this handle has open
22 /// — that case would otherwise `File::create`-truncate the live
23 /// database to 0 bytes (`fs::copy` on Unix reads *after* the
24 /// `O_TRUNC`, so a naive export-to-self destroys the source).
25 /// Unix: compares `(dev, ino)` of both paths via `MetadataExt`,
26 /// catching symlinks and hard links. Windows: compares
27 /// canonicalized paths; a rename onto an open file also fails on
28 /// Windows because of the mandatory lock the handle holds, so the
29 /// rename step is a second line of defense.
30 ///
31 /// Reads the bytes from the already-open file handle, not by
32 /// `fs::copy`. On Windows that matters: `LockFileEx` locks are
33 /// mandatory, so a second handle opened by `fs::copy` would fail
34 /// while this writer still holds the lock.
35 ///
36 /// FIX-1 R-001.5 + R-002.2 part 3.
37 pub fn export_encrypted(&mut self, dest: impl AsRef<Path>) -> Result<()> {
38 let dest = dest.as_ref();
39
40 // Step 1 — refuse export to the open file itself. We compare
41 // by identity, not string, so symlinks and hard links to
42 // `self.path` are caught too. The check runs before any flush
43 // so a self-targeted export is a pure no-op.
44 if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
45 return Err(MnemoError::Invalid(format!(
46 "export_encrypted refuses to overwrite the open database at {}",
47 dest.display()
48 )));
49 }
50
51 // Step 2 — flush, so on-disk bytes match the live state.
52 if !self.read_only {
53 self.flush()?;
54 }
55
56 // Step 3 — stream from the open handle into a sibling temp.
57 // Using the open handle (instead of a second open on `self.path`)
58 // means a Windows mandatory lock can't block the copy.
59 let parent = dest.parent().ok_or_else(|| {
60 MnemoError::Invalid(format!(
61 "export_encrypted: dest {} has no parent directory",
62 dest.display()
63 ))
64 })?;
65 let tmp = temp_sibling(dest);
66 // Scope the temp handle so it closes before the rename on
67 // Windows (which refuses to rename over an open file).
68 {
69 let src = self.pager.file_mut();
70 src.seek(SeekFrom::Start(0))?;
71 let mut out = OpenOptions::new()
72 .write(true)
73 .create(true)
74 .truncate(true)
75 .open(&tmp)?;
76 let mut buf = vec![0u8; 1 << 20]; // 1 MiB
77 loop {
78 let n = src.read(&mut buf)?;
79 if n == 0 {
80 break;
81 }
82 out.write_all(&buf[..n])?;
83 }
84 out.sync_all()?;
85 crate::bump_fsync();
86 }
87
88 // Step 4 — atomic rename onto `dest`.
89 if let Err(e) = std::fs::rename(&tmp, dest) {
90 // Best-effort cleanup; propagate the rename error.
91 let _ = std::fs::remove_file(&tmp);
92 return Err(MnemoError::Io(e));
93 }
94
95 // Step 5 — fsync the parent directory on Unix so the rename
96 // itself is durable. On Windows directory syncs aren't
97 // supported; the rename above is atomic enough on NTFS.
98 #[cfg(unix)]
99 {
100 if let Ok(dir) = File::open(parent) {
101 let _ = dir.sync_all();
102 crate::bump_fsync();
103 }
104 }
105 #[cfg(not(unix))]
106 {
107 let _ = parent;
108 }
109
110 Ok(())
111 }
112
113 /// Change the passphrase. Cheap: re-derives the KEK and re-wraps the DEK;
114 /// the encrypted pages are never rewritten.
115 pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
116 self.rekey_secret(new_passphrase.as_bytes(), kdf)
117 }
118
119 /// PERF-1 step 7: switch to (or rotate) a raw 256-bit key, recording
120 /// [`KdfParams::raw_key`] in the header. Like [`Mnemo::rekey`], only the
121 /// wrapped DEK changes; pages aren't rewritten.
122 pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
123 self.rekey_secret(new_key, KdfParams::raw_key())
124 }
125
126 pub(super) fn rekey_secret(&mut self, secret: &[u8], kdf: KdfParams) -> Result<()> {
127 if self.read_only {
128 return Err(MnemoError::ReadOnly);
129 }
130 self.flush()?;
131 let new_salt = crypto::random_salt();
132 let new_kek = crypto::derive_kek(secret, &new_salt, kdf)?;
133 let new_nonce = crypto::random_nonce();
134 let wrapped = crypto::wrap_dek(&new_kek, &new_nonce, self.pager.dek())?;
135 if wrapped.len() != WRAPPED_DEK_LEN {
136 return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
137 }
138 let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
139 wrapped_dek.copy_from_slice(&wrapped);
140
141 self.header.salt = new_salt;
142 self.header.dek_nonce = new_nonce;
143 self.header.wrapped_dek = wrapped_dek;
144 self.header.m_cost = kdf.m_cost;
145 self.header.t_cost = kdf.t_cost;
146 self.header.p_cost = kdf.p_cost;
147 self.kdf = kdf;
148
149 // DUR-1 (R-002.1): WAL-log the new page 0 before touching it.
150 // Allocate a fresh WAL region at the tail so that a crash during
151 // the rekey leaves either the old region (old passphrase works)
152 // or the new region (new passphrase works) fully committed —
153 // overwriting the existing region would risk destroying both.
154 let old_wal_start = self.header.wal_start;
155 let new_pages = self.header.wal_pages;
156 let new_start = self.header.next_page;
157 self.header.next_page += new_pages;
158 self.header.wal_start = new_start;
159 self.header.wal_pages = new_pages;
160 self.header.wal_seq += 1;
161 self.relocate_header_through_wal(old_wal_start)?;
162 // FMT-9 (a): the old region is freed by the next commit (see
163 // `ensure_wal_capacity`).
164 self.release_pages(old_wal_start, new_pages);
165 Ok(())
166 }
167
168 /// Decrypt and validate every live record. Returns the count verified
169 /// across memories **and** cache entries (FIX-1 R-001.1: now that the
170 /// cache survives compaction, `verify()` has to walk it too — the
171 /// pre-FIX-1 implementation only checked `self.catalog`, so a
172 /// corrupted cache record went unnoticed).
173 pub fn verify(&mut self) -> Result<usize> {
174 let entries: Vec<CatalogEntry> = self
175 .catalog
176 .iter()
177 .filter(|e| !e.deleted)
178 .cloned()
179 .collect();
180 let mut n = entries.len();
181 for e in &entries {
182 let bytes = self.read_record(e)?;
183 let _m: Memory = self.decode_memory(&bytes)?;
184 // FMT-9b: and the row's vector column entry.
185 if e.v9.is_some() {
186 let (h, _) = self.column_entry(e)?;
187 if h.len() != self.dimensions {
188 return Err(MnemoError::Invalid(
189 "vector entry has the wrong width".into(),
190 ));
191 }
192 }
193 }
194
195 // Also decode every live cache entry. Tombstoned entries are
196 // skipped — their pages are orphan ciphertext awaiting
197 // `compact_file`, same as deleted memories. Expired entries
198 // are *still* on disk until compaction, so we verify them too.
199 let cache_positions: Vec<(u64, u32, u32, u64)> = self
200 .cache_dir
201 .iter()
202 .filter(|e| !e.deleted)
203 .map(|e| (e.start_page, e.page_count, e.len, e.gen))
204 .collect();
205 for (start_page, page_count, len, gen) in cache_positions {
206 let buf = self.read_record_run(start_page, page_count, len, gen)?;
207 let _c: CacheEntry = rmp_serde::from_slice(&buf)
208 .map_err(|err| MnemoError::Serialize(err.to_string()))?;
209 n += 1;
210 }
211 // FMT-9 (a): no free run may overlap a page the committed state
212 // references (records, cache entries, control runs, the WAL).
213 if self.is_v9() {
214 self.check_free_list_disjoint()?;
215 }
216 Ok(n)
217 }
218
219 /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
220 /// page the current state references.
221 pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
222 let h = &self.header;
223 let mut live: Vec<(u64, u64, &str)> = vec![
224 (h.wal_start, h.wal_pages, "WAL region"),
225 (h.catalog_start, h.catalog_pages, "catalog run"),
226 (h.index_start, h.index_pages, "index run"),
227 (h.manifest_start, h.manifest_pages, "manifest run"),
228 (h.cache_start, h.cache_pages, "cache directory run"),
229 (h.free.start, h.free.pages, "free-list run"),
230 (h.keys.start, h.keys.pages, "key-slot run"),
231 ];
232 live.extend(
233 self.catalog
234 .iter()
235 .filter(|e| !e.deleted)
236 .map(|e| (e.start_page, e.page_count as u64, "record")),
237 );
238 live.extend(
239 self.cache_dir
240 .iter()
241 .filter(|e| !e.deleted)
242 .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
243 );
244 live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
245 live.extend(
246 self.delta_chain
247 .iter()
248 .map(|r| (r.start, r.pages, "catalog delta run")),
249 );
250 live.extend(
251 self.index_chain
252 .iter()
253 .map(|r| (r.start, r.pages, "index delta run")),
254 );
255 live.push((
256 self.header.bm25.start,
257 self.header.bm25.pages,
258 "BM25 manifest",
259 ));
260 live.extend(
261 self.bm25
262 .manifest
263 .segments
264 .iter()
265 .map(|t| (t.0, t.1, "BM25 segment")),
266 );
267 for (p, c, what) in live {
268 if c == 0 {
269 continue;
270 }
271 if self.free.overlaps(p, c) {
272 return Err(MnemoError::Invalid(format!(
273 "free list overlaps a live {what} at page {p} (+{c})"
274 )));
275 }
276 if self
277 .pending_free
278 .iter()
279 .any(|&(q, n)| q < p + c && p < q + n)
280 {
281 return Err(MnemoError::Invalid(format!(
282 "a pending free overlaps a live {what} at page {p} (+{c})"
283 )));
284 }
285 }
286 Ok(())
287 }
288
289 /// Summary statistics for the open database.
290 pub fn stats(&mut self) -> Result<Stats> {
291 let deleted = self.catalog.iter().filter(|e| e.deleted).count();
292 // FIX-1 R-001.8 part 2: build the agent set lazily on first
293 // call per handle, then maintain in `put` / invalidate in
294 // `delete`. Pre-FIX-1 every `stats()` call decrypted every
295 // live memory (O(N) AES-GCM decrypts just to list a usually-
296 // tiny set of distinct agent IDs). On a 1M-memory database
297 // this was in the multi-second range on hardware AES.
298 if self.agent_set.is_none() {
299 let built: std::collections::BTreeSet<String> =
300 self.memories()?.into_iter().map(|m| m.agent_id).collect();
301 self.agent_set = Some(built);
302 }
303 let agents: Vec<String> = self
304 .agent_set
305 .as_ref()
306 .expect("agent_set just filled above")
307 .iter()
308 .cloned()
309 .collect();
310 let file_bytes = self.header.next_page * PAGE_SIZE as u64;
311 Ok(Stats {
312 memories: self.len(),
313 deleted,
314 dimensions: self.dimensions,
315 file_bytes,
316 agents,
317 encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
318 created_at: self.header.created_at,
319 index: {
320 self.ensure_ann()?;
321 self.ann.as_ref().map(|a| a.info())
322 },
323 wal_pages: self.header.wal_pages,
324 fsyncs_last_flush: self.fsyncs_last_flush,
325 format_version: self.header.version,
326 })
327 }
328
329 /// Rewrite the file, dropping tombstoned and expired memories and
330 /// reclaiming stale pages left by updates. Done out-of-place via a temp
331 /// file and an atomic rename.
332 ///
333 /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
334 /// compaction. Every live, non-expired directory entry is copied
335 /// into the new file verbatim — `created_at`, `ttl_secs`,
336 /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
337 /// `vector` and `model` come from the record body; `accessed_at`
338 /// and `access_count` come from the *directory* (the record body
339 /// only holds the insert-time snapshot — the directory is the
340 /// source of truth for the live counts, as of v5's recall trick).
341 /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
342 /// compaction kept only the memory catalog and silently emptied
343 /// the cache; the Planner's interim README caveat (c417d2e) called
344 /// that out — this PR removes the surprise.
345 pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
346 Self::compact_file_secret(path, passphrase.as_bytes(), 0)
347 }
348
349 /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
350 pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
351 Self::compact_file_secret(path, key, 0)
352 }
353
354 /// FMT-9f: [`Mnemo::compact_file`] into an explicit format: `9` (what
355 /// `compact_file` does) or `8`, which keeps a v8 file readable by
356 /// v0.10 and earlier. The v8 target is kept for one release.
357 pub fn compact_file_to(
358 path: &str,
359 passphrase: &str,
360 format_version: u16,
361 ) -> Result<CompactReport> {
362 if format_version != VERSION && format_version != VERSION_V9 {
363 return Err(MnemoError::Invalid(format!(
364 "compact target format {format_version} isn't supported (use 8 or 9)"
365 )));
366 }
367 Self::compact_file_secret(path, passphrase.as_bytes(), format_version)
368 }
369
370 pub(super) fn compact_file_secret(
371 path: &str,
372 secret: &[u8],
373 format_version: u16,
374 ) -> Result<CompactReport> {
375 let mut old = Mnemo::open_secret(path, secret)?;
376 let dims = old.dimensions;
377 let kdf = old.kdf;
378 let tmp = format!("{path}.compact-tmp");
379
380 let mut new = Mnemo::create_secret(
381 &tmp,
382 secret,
383 MnemoConfig {
384 dimensions: dims,
385 kdf,
386 // FMT-9f: compaction writes v9 (upgrading a v8 file),
387 // unless `compact_file_to` asked for v8. A v9 file that
388 // keeps float vectors keeps them.
389 format_version,
390 store_float_vectors: old.float_vectors(),
391 ..Default::default()
392 },
393 )?;
394 // FMT-9e: compaction rewrites everything, so it compresses every
395 // thread turn, recent or not.
396 new.turn_compress_after = 0;
397 // ANN-1.1: compaction is "re-tune for the current size" by
398 // default. Pass IndexConfig::default() so partitions,
399 // subspaces, n_probe and n_rerank are all re-derived from the
400 // compacted vector count. Previously we froze the pre-compact
401 // (n_probe, n_rerank), which left the new index on stale
402 // numbers for the smaller post-compact corpus.
403 let want_index = old.has_index();
404 let now = memory::now_secs();
405 let all = old.memories()?;
406 let before = all.len();
407 let mut after = 0;
408 for m in all {
409 if m.is_expired(now) {
410 continue;
411 }
412 new.remember(m)?;
413 after += 1;
414 }
415 if want_index && after > 0 {
416 new.build_index_with(IndexConfig::default())?;
417 }
418
419 // Count + copy cache entries. We walk `old.cache_dir` by index
420 // so each hop reads the directory's live `accessed_at` /
421 // `access_count` directly rather than going through
422 // `cache_get` (which would also treat read-only semantics,
423 // tombstones, etc. — we want the raw, authoritative values).
424 let mut cache_before = 0usize;
425 let mut cache_after = 0usize;
426 let positions: Vec<usize> = (0..old.cache_dir.len()).collect();
427 for pos in positions {
428 let keep = {
429 let e = &old.cache_dir[pos];
430 !e.deleted && !e.is_expired(now)
431 };
432 if keep {
433 cache_before += 1;
434 new.copy_cache_entry_from(&mut old, pos)?;
435 cache_after += 1;
436 }
437 }
438
439 new.flush()?;
440 drop(new);
441 drop(old);
442
443 std::fs::rename(&tmp, path)?;
444 Ok(CompactReport {
445 before,
446 after,
447 cache_before,
448 cache_after,
449 })
450 }
451
452 /// Copy one live cache entry from `old` at directory position
453 /// `pos` into `self` (a freshly-created compaction target).
454 /// Decrypts the old record body, substitutes the old *directory*'s
455 /// `accessed_at` + `access_count` (the record body's copies are
456 /// stale as of v5's directory-only hit path), re-encodes, writes
457 /// a fresh record run, and pushes a matching directory entry.
458 ///
459 /// Caller is expected to have already filtered out tombstoned /
460 /// expired entries and to call this on a read-write handle.
461 pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
462 if self.read_only {
463 return Err(MnemoError::ReadOnly);
464 }
465 // Snapshot the directory fields we need, so the borrow on
466 // `old.cache_dir` ends before we touch `old.pager`.
467 let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
468 let e = &old.cache_dir[pos];
469 (
470 e.start_page,
471 e.page_count,
472 e.len,
473 e.accessed_at,
474 e.access_count,
475 e.gen,
476 )
477 };
478
479 // Read + decrypt the old record body.
480 let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
481 let mut entry: CacheEntry =
482 rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
483
484 // Overwrite the stale body copies with the directory's live
485 // values before persisting. Everything else — `created_at`,
486 // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
487 // `content_type`, `value`, `vector`, `model` — stays as the
488 // body already recorded it.
489 entry.accessed_at = dir_accessed_at;
490 entry.access_count = dir_access_count;
491
492 let bytes =
493 rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
494 let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
495
496 let dir_entry = CacheDirectoryEntry {
497 namespace: entry.namespace.clone(),
498 key_hash: entry.key_hash,
499 start_page: new_start_page,
500 page_count: new_page_count,
501 len: bytes.len() as u32,
502 deleted: false,
503 accessed_at: dir_accessed_at,
504 access_count: dir_access_count,
505 size_bytes: entry.size_bytes,
506 ttl_secs: entry.ttl_secs,
507 created_at: entry.created_at,
508 vector: entry.vector.clone(),
509 model: entry.model.clone(),
510 gen,
511 };
512 let new_pos = self.cache_dir.len();
513 self.cache_idx
514 .insert(&entry.namespace, entry.key_hash, new_pos);
515 self.cache_dir.push(dir_entry);
516 self.dirty_cache = true;
517 Ok(())
518 }
519}