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    ///
116    /// **This changes the secret that opens this file from now on; anyone who
117    /// had the file and the old secret can still read it and later writes.**
118    /// The data key stays the same, so an earlier copy of the file (or of
119    /// just its header) and the old passphrase still unlock it. The old wrap
120    /// is scrubbed from this file (the previous WAL region is zeroed, and any
121    /// stale copy of the old header's key wrap is overwritten); that's
122    /// hygiene, not revocation. **To revoke, rotate:** rekey, then
123    /// [`Mnemo::compact_file`] (`mnemo rekey --rotate`), which rewrites the
124    /// file under a fresh data key. Rotation can't erase old ciphertext the storage hardware still holds: flash keeps rewritten blocks until it reuses them, and that's out of the engine's hands.
125    ///
126    /// **An error means the old secret is still in force,** for this handle
127    /// and for the file, including after later writes and a close (REKEY-1).
128    /// The one exception is when the new header's write fails and putting
129    /// the old one back fails too: the error then says so, and the file may
130    /// open with either secret.
131    ///
132    /// `Ok` means the new secret is in force. Scrubbing the old wrap
133    /// afterwards is hygiene; if part of it fails, the rekey still succeeds
134    /// and [`Mnemo::rekey_cleanup_error`] says what was left.
135    pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
136        self.rekey_secret(new_passphrase.as_bytes(), kdf)
137    }
138
139    /// PERF-1 step 7: switch to (or rotate) a raw 256-bit key, recording
140    /// [`KdfParams::raw_key`] in the header. Like [`Mnemo::rekey`], only the
141    /// wrapped DEK changes; pages aren't rewritten, and it doesn't revoke
142    /// the old key (see [`Mnemo::rekey`]).
143    ///
144    /// Errors and the cleanup report work as in [`Mnemo::rekey`].
145    pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
146        self.rekey_secret(new_key, KdfParams::raw_key())
147    }
148
149    pub(super) fn rekey_secret(&mut self, secret: &[u8], kdf: KdfParams) -> Result<()> {
150        if self.read_only {
151            return Err(MnemoError::ReadOnly);
152        }
153        self.rekey_cleanup = None;
154        self.flush()?;
155        let new_salt = crypto::random_salt();
156        let new_kek = crypto::derive_kek(secret, &new_salt, kdf)?;
157        let new_nonce = crypto::random_nonce();
158        let wrapped = crypto::wrap_dek(&new_kek, &new_nonce, self.pager.dek())?;
159        if wrapped.len() != WRAPPED_DEK_LEN {
160            return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
161        }
162        let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
163        wrapped_dek.copy_from_slice(&wrapped);
164
165        // SEC-2: the old header's key wrap (salt, DEK nonce, wrapped DEK, as
166        // laid out at header bytes 86..162), to scrub once the new header
167        // is committed.
168        let mut old_wrap =
169            Vec::with_capacity(crypto::SALT_LEN + crypto::NONCE_LEN + WRAPPED_DEK_LEN);
170        old_wrap.extend_from_slice(&self.header.salt);
171        old_wrap.extend_from_slice(&self.header.dek_nonce);
172        old_wrap.extend_from_slice(&self.header.wrapped_dek);
173
174        // REKEY-1 (RB-004.2): until the new page 0 is on disk, a failure puts
175        // these back, so an `Err` means "still the old secret".
176        let before = self.header.clone();
177        let before_kdf = self.kdf;
178
179        self.header.salt = new_salt;
180        self.header.dek_nonce = new_nonce;
181        self.header.wrapped_dek = wrapped_dek;
182        self.header.m_cost = kdf.m_cost;
183        self.header.t_cost = kdf.t_cost;
184        self.header.p_cost = kdf.p_cost;
185        self.kdf = kdf;
186
187        // DUR-1 (R-002.1): WAL-log the new page 0 before touching it.
188        // Allocate a fresh WAL region at the tail so that a crash during
189        // the rekey leaves either the old region (old passphrase works)
190        // or the new region (new passphrase works) fully committed —
191        // overwriting the existing region would risk destroying both.
192        let old_wal_start = self.header.wal_start;
193        let new_pages = self.header.wal_pages;
194        let new_start = self.header.next_page;
195        self.header.next_page += new_pages;
196        self.header.wal_start = new_start;
197        self.header.wal_pages = new_pages;
198        self.header.wal_seq += 1;
199
200        // The steps of `relocate_header_through_wal`, apart, so a failure
201        // can be told from one before page 0 and one after it.
202        self.header.write_counter = self.pager.write_counter;
203        let mut page = self.header.to_page();
204        if let Err(e) = self.header.apply_seal(&mut page, self.pager.dek()) {
205            return Err(self.undo_rekey(before, before_kdf, None, false, e));
206        }
207        let frames = vec![(0u64, page.to_vec())];
208        let txn_id = self.header.wal_seq;
209        if let Err(e) = wal::commit(self.pager.file_mut(), new_start, new_pages, txn_id, &frames) {
210            let region = Some((new_start, new_pages));
211            return Err(self.undo_rekey(before, before_kdf, region, false, e));
212        }
213        if let Err(e) = self
214            .pager
215            .write_raw(0, &page)
216            .and_then(|_| self.pager.sync())
217        {
218            let region = Some((new_start, new_pages));
219            return Err(self.undo_rekey(before, before_kdf, region, true, e));
220        }
221
222        // The new page 0 is on disk: the new secret is in force, and nothing
223        // below fails the rekey. SEC-2 (RB-001.30): zero the old region's
224        // first frame header (so no scan reads it as a WAL), then all of it
225        // (its frames hold page-0 images with the old wrap), then any other
226        // stale copy of the old wrap in the file (an earlier, grown or
227        // relocated region). Each step runs even if the one before failed.
228        // Hygiene only: a copy of the file taken before the rekey still
229        // opens with the old secret (see `rekey`).
230        let mut left = Vec::new();
231        if let Err(e) = wal::invalidate_region(self.pager.file_mut(), old_wal_start) {
232            left.push(format!("clearing the old WAL region's first frame: {e}"));
233        }
234        if let Err(e) = wal::scrub_region(self.pager.file_mut(), old_wal_start, new_pages) {
235            left.push(format!("zeroing the old WAL region: {e}"));
236        }
237        if let Err(e) = scrub_bytes(self.pager.file_mut(), &old_wrap) {
238            left.push(format!("overwriting other copies of the old key wrap: {e}"));
239        }
240        self.rekey_cleanup = (!left.is_empty()).then(|| left.join("; "));
241        // FMT-9 (a): the old region is freed by the next commit (see
242        // `ensure_wal_capacity`).
243        self.release_pages(old_wal_start, new_pages);
244        Ok(())
245    }
246
247    /// REKEY-1: a rekey failed before its new page 0 was on disk. Put the
248    /// header and the KDF back, so the handle (and every later write) uses
249    /// the old secret. Then, best effort: zero the new WAL region, whose
250    /// commit wraps the data key under the new secret, so a later
251    /// torn-header scan can't find it; and, if page 0 may have been
252    /// written, write the old one back.
253    fn undo_rekey(
254        &mut self,
255        before: crate::format::Header,
256        before_kdf: KdfParams,
257        new_region: Option<(u64, u64)>,
258        page0_written: bool,
259        err: MnemoError,
260    ) -> MnemoError {
261        self.header = before;
262        self.kdf = before_kdf;
263        if let Some((start, pages)) = new_region {
264            let _ = wal::scrub_region(self.pager.file_mut(), start, pages);
265        }
266        if !page0_written {
267            return err;
268        }
269        self.header.write_counter = self.pager.write_counter;
270        let mut page = self.header.to_page();
271        let put_back = self
272            .header
273            .apply_seal(&mut page, self.pager.dek())
274            .and_then(|_| self.pager.write_raw(0, &page))
275            .and_then(|_| self.pager.sync());
276        match put_back {
277            Ok(()) => err,
278            // `mnemo rekey` looks for "may open with either secret" to leave
279            // out its "the passphrase was not changed": keep the phrase.
280            Err(again) => MnemoError::Io(std::io::Error::other(format!(
281                "rekey failed writing the new header ({err}), and the old header \
282                 couldn't be written back ({again}): the file may open with either \
283                 secret; close it without writing and try both"
284            ))),
285        }
286    }
287
288    /// REKEY-1 (RB-004.2): after a successful [`Mnemo::rekey`] or
289    /// [`Mnemo::rekey_with_key`], what couldn't be scrubbed of the old key
290    /// wrap, or `None` if it all was. The rekey took effect either way; what
291    /// is left is plaintext key-wrap bytes the old secret could still use, so
292    /// to be sure, rotate (`compact_file`) as [`Mnemo::rekey`] describes.
293    /// Each rekey resets it.
294    pub fn rekey_cleanup_error(&self) -> Option<&str> {
295        self.rekey_cleanup.as_deref()
296    }
297
298    /// SEC-2 (RB-001.30): write a copy of this database at `dest` under a
299    /// **fresh data key**, protected by `passphrase` through `kdf`. It goes
300    /// through the compaction path (live memories, the result cache and
301    /// the index, no history), so the copy shares no key material with
302    /// this file: neither this file's passphrase nor its data key opens
303    /// it, and its passphrase opens nothing here. This file is flushed
304    /// first (unless read-only) and is otherwise unchanged; `dest` must not
305    /// exist. The copy is v9.
306    pub fn export_rekeyed(
307        &mut self,
308        dest: impl AsRef<Path>,
309        passphrase: &str,
310        kdf: KdfParams,
311    ) -> Result<CompactReport> {
312        self.export_rekeyed_secret(dest.as_ref(), passphrase.as_bytes(), kdf)
313    }
314
315    /// [`Mnemo::export_rekeyed`] protected by a raw 256-bit key (no KDF).
316    pub fn export_rekeyed_with_key(
317        &mut self,
318        dest: impl AsRef<Path>,
319        key: &[u8; crypto::KEY_LEN],
320    ) -> Result<CompactReport> {
321        self.export_rekeyed_secret(dest.as_ref(), key, KdfParams::raw_key())
322    }
323
324    pub(super) fn export_rekeyed_secret(
325        &mut self,
326        dest: &Path,
327        secret: &[u8],
328        kdf: KdfParams,
329    ) -> Result<CompactReport> {
330        if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
331            return Err(MnemoError::Invalid(format!(
332                "export_rekeyed refuses to overwrite the open database at {}",
333                dest.display()
334            )));
335        }
336        if dest.exists() {
337            return Err(MnemoError::Invalid(format!(
338                "{} already exists",
339                dest.display()
340            )));
341        }
342        if !self.read_only {
343            self.flush()?;
344        }
345        let mut name = dest.file_name().unwrap_or_default().to_os_string();
346        name.push(".export-tmp");
347        let tmp = dest.with_file_name(name);
348        let _ = std::fs::remove_file(&tmp);
349        let result = (|| {
350            let mut new = Mnemo::create_secret(
351                &tmp,
352                secret,
353                MnemoConfig {
354                    dimensions: self.dimensions,
355                    kdf,
356                    store_float_vectors: self.float_vectors(),
357                    ..Default::default()
358                },
359            )?;
360            let report = self.copy_live_into(&mut new)?;
361            new.flush()?;
362            drop(new);
363            std::fs::rename(&tmp, dest)?;
364            Ok(report)
365        })();
366        if result.is_err() {
367            let _ = std::fs::remove_file(&tmp);
368        }
369        result
370    }
371
372    /// The compaction copy: every live, unexpired memory and cache entry of
373    /// `self` into `new` (a freshly created file), and the index if `self`
374    /// has one. Counts as [`CompactReport`].
375    pub(super) fn copy_live_into(&mut self, new: &mut Mnemo) -> Result<CompactReport> {
376        // FMT-9e: compaction rewrites everything, so it compresses every
377        // thread turn, recent or not.
378        new.turn_compress_after = 0;
379        // ANN-1.1: compaction is "re-tune for the current size" by
380        // default. Pass IndexConfig::default() so partitions,
381        // subspaces, n_probe and n_rerank are all re-derived from the
382        // compacted vector count. Previously we froze the pre-compact
383        // (n_probe, n_rerank), which left the new index on stale
384        // numbers for the smaller post-compact corpus.
385        let want_index = self.has_index();
386        let now = memory::now_secs();
387        let all = self.memories()?;
388        let before = all.len();
389        let mut after = 0;
390        let mut zero_vector_manifests = 0;
391        let mut zero_vector_memories = 0;
392        for mut m in all {
393            if m.is_expired(now) {
394                continue;
395            }
396            // A file from before the zero-vector rule (Phase 3 PR 10a) can
397            // hold all-zero vectors. A legacy onboarding or manifest memory
398            // gets the sentinel unit vector a current manifest has, so it
399            // behaves like a new one; any other is carried unchanged.
400            if embed::is_zero_vector(&m.vector) {
401                if crud::is_onboarding(&m) || is_manifest(&m) {
402                    m.vector = Memory::scaffold_manifest(self.dimensions).vector;
403                    zero_vector_manifests += 1;
404                } else {
405                    zero_vector_memories += 1;
406                }
407            }
408            // The engine's own copy: `_mnemo.*` keys come through as they
409            // are, and the write-time zero-vector check doesn't apply.
410            new.put_existing(m)?;
411            after += 1;
412        }
413        if want_index && after > 0 {
414            new.build_index_with(IndexConfig::default())?;
415        }
416
417        // Count + copy cache entries. We walk `self.cache_dir` by index
418        // so each hop reads the directory's live `accessed_at` /
419        // `access_count` directly rather than going through
420        // `cache_get` (which would also treat read-only semantics,
421        // tombstones, etc. — we want the raw, authoritative values).
422        let mut cache_before = 0usize;
423        let mut cache_after = 0usize;
424        let positions: Vec<usize> = (0..self.cache_dir.len()).collect();
425        for pos in positions {
426            let (keep, reserved) = {
427                let e = &self.cache_dir[pos];
428                (
429                    !e.deleted && !e.is_expired(now),
430                    embed::is_reserved_namespace(&e.namespace),
431                )
432            };
433            if keep {
434                // EMBED-ID-1: the engine's own entries (the embedder
435                // identity) are copied but not counted.
436                new.copy_cache_entry_from(self, pos)?;
437                if !reserved {
438                    cache_before += 1;
439                    cache_after += 1;
440                }
441            }
442        }
443        Ok(CompactReport {
444            before,
445            after,
446            cache_before,
447            cache_after,
448            zero_vector_manifests,
449            zero_vector_memories,
450        })
451    }
452
453    /// Decrypt and validate every live record. Returns the count verified
454    /// across memories **and** cache entries (FIX-1 R-001.1: now that the
455    /// cache survives compaction, `verify()` has to walk it too — the
456    /// pre-FIX-1 implementation only checked `self.catalog`, so a
457    /// corrupted cache record went unnoticed).
458    pub fn verify(&mut self) -> Result<usize> {
459        Ok(self.verify_report()?.records)
460    }
461
462    /// [`Mnemo::verify`], also counting the memories whose vector is all
463    /// zeros. A file written before the zero-vector rule (Phase 3 PR 10a)
464    /// can hold them; they decode fine but score 0.0 on every vector query.
465    /// `mnemo verify` warns about them, and compaction carries them
466    /// (giving a legacy manifest the sentinel vector).
467    pub fn verify_report(&mut self) -> Result<VerifyReport> {
468        let entries: Vec<CatalogEntry> = self
469            .catalog
470            .iter()
471            .filter(|e| !e.deleted)
472            .cloned()
473            .collect();
474        let mut n = entries.len();
475        let mut zero_vector_memories = 0;
476        for e in &entries {
477            let bytes = self.read_record(e)?;
478            let m: Memory = self.decode_memory(&bytes)?;
479            // FMT-9b: and the row's vector column entry.
480            let zero = if e.v9.is_some() {
481                let (h, _) = self.column_entry(e)?;
482                if h.len() != self.dimensions {
483                    return Err(MnemoError::Invalid(
484                        "vector entry has the wrong width".into(),
485                    ));
486                }
487                // fp16 +0.0 and -0.0.
488                !h.is_empty() && h.iter().all(|b| b & 0x7fff == 0)
489            } else {
490                embed::is_zero_vector(&m.vector)
491            };
492            if zero {
493                zero_vector_memories += 1;
494            }
495        }
496
497        // Also decode every live cache entry. Tombstoned entries are
498        // skipped — their pages are orphan ciphertext awaiting
499        // `compact_file`, same as deleted memories. Expired entries
500        // are *still* on disk until compaction, so we verify them too.
501        let cache_positions: Vec<(u64, u32, u32, u64, bool)> = self
502            .cache_dir
503            .iter()
504            .filter(|e| !e.deleted)
505            .map(|e| {
506                let reserved = embed::is_reserved_namespace(&e.namespace);
507                (e.start_page, e.page_count, e.len, e.gen, reserved)
508            })
509            .collect();
510        for (start_page, page_count, len, gen, reserved) in cache_positions {
511            let buf = self.read_record_run(start_page, page_count, len, gen)?;
512            let _c: CacheEntry = rmp_serde::from_slice(&buf)
513                .map_err(|err| MnemoError::Serialize(err.to_string()))?;
514            // EMBED-ID-1: the engine's own entries are checked, not counted.
515            if !reserved {
516                n += 1;
517            }
518        }
519        // FMT-9 (a): no free run may overlap a page the committed state
520        // references (records, cache entries, control runs, the WAL).
521        if self.is_v9() {
522            self.check_free_list_disjoint()?;
523        }
524        Ok(VerifyReport {
525            records: n,
526            zero_vector_memories,
527        })
528    }
529
530    /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
531    /// page the current state references.
532    pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
533        let h = &self.header;
534        let mut live: Vec<(u64, u64, &str)> = vec![
535            (h.wal_start, h.wal_pages, "WAL region"),
536            (h.catalog_start, h.catalog_pages, "catalog run"),
537            (h.index_start, h.index_pages, "index run"),
538            (h.manifest_start, h.manifest_pages, "manifest run"),
539            (h.cache_start, h.cache_pages, "cache directory run"),
540            (h.free.start, h.free.pages, "free-list run"),
541            (h.keys.start, h.keys.pages, "key-slot run"),
542        ];
543        live.extend(
544            self.catalog
545                .iter()
546                .filter(|e| !e.deleted)
547                .map(|e| (e.start_page, e.page_count as u64, "record")),
548        );
549        live.extend(
550            self.cache_dir
551                .iter()
552                .filter(|e| !e.deleted)
553                .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
554        );
555        live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
556        live.extend(
557            self.delta_chain
558                .iter()
559                .map(|r| (r.start, r.pages, "catalog delta run")),
560        );
561        live.extend(
562            self.index_chain
563                .iter()
564                .map(|r| (r.start, r.pages, "index delta run")),
565        );
566        live.push((
567            self.header.bm25.start,
568            self.header.bm25.pages,
569            "BM25 manifest",
570        ));
571        live.extend(
572            self.bm25
573                .manifest
574                .segments
575                .iter()
576                .map(|t| (t.0, t.1, "BM25 segment")),
577        );
578        for (p, c, what) in live {
579            if c == 0 {
580                continue;
581            }
582            if self.free.overlaps(p, c) {
583                return Err(MnemoError::Invalid(format!(
584                    "free list overlaps a live {what} at page {p} (+{c})"
585                )));
586            }
587            if self
588                .pending_free
589                .iter()
590                .any(|&(q, n)| q < p + c && p < q + n)
591            {
592                return Err(MnemoError::Invalid(format!(
593                    "a pending free overlaps a live {what} at page {p} (+{c})"
594                )));
595            }
596        }
597        Ok(())
598    }
599
600    /// The statistics that need no record decrypts and no index load
601    /// (v0.12.2, RB-002.3): counts, sizes, the format, whether an index
602    /// exists, the recall mode and the bytes the vector column needs. The
603    /// first [`Mnemo::stats`] on a handle decrypts every record (for its
604    /// agent list) and loads a persisted index; this is what a phone app
605    /// polling the recall mode should call.
606    pub fn stats_summary(&self) -> StatsSummary {
607        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
608        let v9 = self.is_v9();
609        let column = if v9 {
610            (self.scored_rows() * crate::veccol::entry_len(self.dimensions)) as u64
611        } else {
612            0
613        };
614        let recall_mode = if self.has_index() {
615            RecallMode::Indexed
616        } else if v9 && column <= self.vector_cache_budget as u64 {
617            RecallMode::ExactResident
618        } else {
619            RecallMode::ExactPaged
620        };
621        let rp = self.restore_points();
622        StatsSummary {
623            memories: self.len(),
624            deleted,
625            dimensions: self.dimensions,
626            file_bytes: self.header.next_page * PAGE_SIZE as u64,
627            format_version: self.header.version,
628            wal_pages: self.header.wal_pages,
629            has_index: self.has_index(),
630            recall_mode,
631            vector_column_bytes: column,
632            snapshots_retained: rp.retained,
633            oldest_restorable_at: rp.oldest_at,
634            snapshot_pinned_bytes: rp.pinned_bytes,
635        }
636    }
637
638    /// Summary statistics for the open database. The first call on a
639    /// handle decrypts every record (to list the agents) and loads a
640    /// persisted index; [`Mnemo::stats_summary`] does neither.
641    pub fn stats(&mut self) -> Result<Stats> {
642        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
643        // FIX-1 R-001.8 part 2: build the agent set lazily on first
644        // call per handle, then maintain in `put` / invalidate in
645        // `delete`. Pre-FIX-1 every `stats()` call decrypted every
646        // live memory (O(N) AES-GCM decrypts just to list a usually-
647        // tiny set of distinct agent IDs). On a 1M-memory database
648        // this was in the multi-second range on hardware AES.
649        if self.agent_set.is_none() {
650            let built: std::collections::BTreeSet<String> =
651                self.memories()?.into_iter().map(|m| m.agent_id).collect();
652            self.agent_set = Some(built);
653        }
654        let agents: Vec<String> = self
655            .agent_set
656            .as_ref()
657            .expect("agent_set just filled above")
658            .iter()
659            .cloned()
660            .collect();
661        let file_bytes = self.header.next_page * PAGE_SIZE as u64;
662        let recall_mode = self.recall_mode()?;
663        let rp = self.restore_points();
664        Ok(Stats {
665            memories: self.len(),
666            deleted,
667            dimensions: self.dimensions,
668            file_bytes,
669            agents,
670            encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
671            created_at: self.header.created_at,
672            index: {
673                self.ensure_ann()?;
674                self.ann.as_ref().map(|a| a.info())
675            },
676            wal_pages: self.header.wal_pages,
677            fsyncs_last_flush: self.fsyncs_last_flush,
678            format_version: self.header.version,
679            recall_mode,
680            snapshots_retained: rp.retained,
681            oldest_restorable_at: rp.oldest_at,
682            snapshot_pinned_bytes: rp.pinned_bytes,
683        })
684    }
685
686    /// Rewrite the file, dropping tombstoned and expired memories and
687    /// reclaiming stale pages left by updates. Done out-of-place via a temp
688    /// file and an atomic rename.
689    ///
690    /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
691    /// compaction. Every live, non-expired directory entry is copied
692    /// into the new file verbatim — `created_at`, `ttl_secs`,
693    /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
694    /// `vector` and `model` come from the record body; `accessed_at`
695    /// and `access_count` come from the *directory* (the record body
696    /// only holds the insert-time snapshot — the directory is the
697    /// source of truth for the live counts, as of v5's recall trick).
698    /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
699    /// compaction kept only the memory catalog and silently emptied
700    /// the cache; the Planner's interim README caveat (c417d2e) called
701    /// that out — this PR removes the surprise.
702    ///
703    /// The output is always v9, so this is also how a v4–v8 file is
704    /// converted: the only read-write open that accepts one (the v8
705    /// sunset, v0.13). It keeps every live memory.
706    pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
707        Self::compact_file_secret(path, passphrase.as_bytes(), 0)
708    }
709
710    /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
711    pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
712        Self::compact_file_secret(path, key, 0)
713    }
714
715    pub(super) fn compact_file_secret(
716        path: &str,
717        secret: &[u8],
718        format_version: u16,
719    ) -> Result<CompactReport> {
720        // The one read-write open that takes a v4–v8 file (the v8 sunset).
721        let mut old = Mnemo::open_secret_with(path, secret, true)?;
722        let dims = old.dimensions;
723        let kdf = old.kdf;
724        let tmp = format!("{path}.compact-tmp");
725
726        let mut new = Mnemo::create_secret(
727            &tmp,
728            secret,
729            MnemoConfig {
730                dimensions: dims,
731                kdf,
732                // FMT-9f: compaction writes v9 (upgrading a v8 file),
733                // unless `compact_file_to` asked for v8. A v9 file that
734                // keeps float vectors keeps them.
735                format_version,
736                store_float_vectors: old.float_vectors(),
737                ..Default::default()
738            },
739        )?;
740        let report = old.copy_live_into(&mut new)?;
741
742        new.flush()?;
743        drop(new);
744        drop(old);
745
746        std::fs::rename(&tmp, path)?;
747        Ok(report)
748    }
749
750    /// Copy one live cache entry from `old` at directory position
751    /// `pos` into `self` (a freshly-created compaction target).
752    /// Decrypts the old record body, substitutes the old *directory*'s
753    /// `accessed_at` + `access_count` (the record body's copies are
754    /// stale as of v5's directory-only hit path), re-encodes, writes
755    /// a fresh record run, and pushes a matching directory entry.
756    ///
757    /// Caller is expected to have already filtered out tombstoned /
758    /// expired entries and to call this on a read-write handle.
759    pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
760        if self.read_only {
761            return Err(MnemoError::ReadOnly);
762        }
763        // Snapshot the directory fields we need, so the borrow on
764        // `old.cache_dir` ends before we touch `old.pager`.
765        let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
766            let e = &old.cache_dir[pos];
767            (
768                e.start_page,
769                e.page_count,
770                e.len,
771                e.accessed_at,
772                e.access_count,
773                e.gen,
774            )
775        };
776
777        // Read + decrypt the old record body.
778        let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
779        let mut entry: CacheEntry =
780            rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
781
782        // Overwrite the stale body copies with the directory's live
783        // values before persisting. Everything else — `created_at`,
784        // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
785        // `content_type`, `value`, `vector`, `model` — stays as the
786        // body already recorded it.
787        entry.accessed_at = dir_accessed_at;
788        entry.access_count = dir_access_count;
789
790        let bytes =
791            rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
792        let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
793
794        let dir_entry = CacheDirectoryEntry {
795            namespace: entry.namespace.clone(),
796            key_hash: entry.key_hash,
797            start_page: new_start_page,
798            page_count: new_page_count,
799            len: bytes.len() as u32,
800            deleted: false,
801            accessed_at: dir_accessed_at,
802            access_count: dir_access_count,
803            size_bytes: entry.size_bytes,
804            ttl_secs: entry.ttl_secs,
805            created_at: entry.created_at,
806            vector: entry.vector.clone(),
807            model: entry.model.clone(),
808            gen,
809        };
810        let new_pos = self.cache_dir.len();
811        self.cache_idx
812            .insert(&entry.namespace, entry.key_hash, new_pos);
813        self.cache_dir.push(dir_entry);
814        self.dirty_cache = true;
815        Ok(())
816    }
817}
818
819/// SEC-2 (RB-001.30): overwrite every occurrence of `needle` in the file
820/// with zeros, then sync. Rekey uses it for stale copies of the old header's
821/// key wrap: they're plaintext (page 0 is sealed, not encrypted) and can sit
822/// in WAL regions that were grown, relocated or freed. Every other page is
823/// AES-GCM ciphertext, where a 76-byte random match doesn't happen.
824pub(super) fn scrub_bytes(file: &mut std::fs::File, needle: &[u8]) -> Result<usize> {
825    if needle.is_empty() {
826        return Ok(0);
827    }
828    let len = file.seek(SeekFrom::End(0))?;
829    let chunk = 1 << 20;
830    let overlap = needle.len() - 1;
831    let mut hits: Vec<u64> = Vec::new();
832    let mut buf = vec![0u8; chunk + overlap];
833    let mut pos: u64 = 0;
834    while pos < len {
835        let want = (chunk as u64 + overlap as u64).min(len - pos) as usize;
836        file.seek(SeekFrom::Start(pos))?;
837        file.read_exact(&mut buf[..want])?;
838        let mut i = 0;
839        while i + needle.len() <= want {
840            if buf[i..i + needle.len()] == *needle {
841                hits.push(pos + i as u64);
842                i += needle.len();
843            } else {
844                i += 1;
845            }
846        }
847        pos += chunk as u64;
848    }
849    hits.dedup();
850    let zeros = vec![0u8; needle.len()];
851    for off in &hits {
852        file.seek(SeekFrom::Start(*off))?;
853        file.write_all(&zeros)?;
854    }
855    if !hits.is_empty() {
856        file.sync_all()?;
857        crate::bump_fsync();
858    }
859    Ok(hits.len())
860}