Skip to main content

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}