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. (The rename is no second line of defense:
28    /// renaming over a file another handle holds open and locked
29    /// succeeds on Windows too, as a 2026-11-13 CI probe showed.)
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        // A new file under a fresh name: `create_new` refuses anything
66        // already there, a symlink included, and a taken name gets another.
67        let (tmp, mut out) = {
68            let mut attempt = 0;
69            loop {
70                let tmp = temp_sibling(dest, "export");
71                match owner_only(OpenOptions::new().write(true).create_new(true)).open(&tmp) {
72                    Ok(out) => break (tmp, out),
73                    Err(e)
74                        if e.kind() == std::io::ErrorKind::AlreadyExists
75                            && attempt + 1 < TEMP_NAME_ATTEMPTS =>
76                    {
77                        attempt += 1;
78                    }
79                    Err(e) => return Err(MnemoError::Io(e)),
80                }
81            }
82        };
83        // Scope the temp handle so it closes before the rename on
84        // Windows (which refuses to rename a file this process has open).
85        {
86            let src = self.pager.file_mut();
87            src.seek(SeekFrom::Start(0))?;
88            let mut buf = vec![0u8; 1 << 20]; // 1 MiB
89            loop {
90                let n = src.read(&mut buf)?;
91                if n == 0 {
92                    break;
93                }
94                out.write_all(&buf[..n])?;
95            }
96            out.sync_all()?;
97            crate::bump_fsync();
98            drop(out);
99        }
100
101        // Step 4 — atomic rename onto `dest`.
102        if let Err(e) = std::fs::rename(&tmp, dest) {
103            // Best-effort cleanup; propagate the rename error.
104            let _ = std::fs::remove_file(&tmp);
105            return Err(MnemoError::Io(e));
106        }
107
108        // Step 5 — fsync the parent directory on Unix so the rename
109        // itself is durable. On Windows directory syncs aren't
110        // supported; the rename above is atomic enough on NTFS.
111        #[cfg(unix)]
112        {
113            if let Ok(dir) = File::open(parent) {
114                let _ = dir.sync_all();
115                crate::bump_fsync();
116            }
117        }
118        #[cfg(not(unix))]
119        {
120            let _ = parent;
121        }
122
123        Ok(())
124    }
125
126    /// Change the passphrase. Cheap: re-derives the KEK and re-wraps the DEK;
127    /// the encrypted pages are never rewritten.
128    ///
129    /// **This changes the secret that opens this file from now on; anyone who
130    /// had the file and the old secret can still read it and later writes.**
131    /// The data key stays the same, so an earlier copy of the file (or of
132    /// just its header) and the old passphrase still unlock it. The old wrap
133    /// is scrubbed from this file (the previous WAL region is zeroed, and any
134    /// stale copy of the old header's key wrap is overwritten); that's
135    /// hygiene, not revocation. **To revoke, rotate:** rekey, then
136    /// [`Mnemo::compact_file`] (`mnemo rekey --rotate`), which rewrites the
137    /// 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.
138    ///
139    /// **An error means the old secret is still in force,** for this handle
140    /// and for the file, including after later writes and a close (REKEY-1).
141    /// The one exception is when the new header's write fails and putting
142    /// the old one back fails too: the error then says so, and the file may
143    /// open with either secret.
144    ///
145    /// `Ok` means the new secret is in force. Scrubbing the old wrap
146    /// afterwards is hygiene; if part of it fails, the rekey still succeeds
147    /// and [`Mnemo::rekey_cleanup_error`] says what was left.
148    pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
149        self.rekey_secret(new_passphrase.as_bytes(), kdf)
150    }
151
152    /// PERF-1 step 7: switch to (or rotate) a raw 256-bit key, recording
153    /// [`KdfParams::raw_key`] in the header. Like [`Mnemo::rekey`], only the
154    /// wrapped DEK changes; pages aren't rewritten, and it doesn't revoke
155    /// the old key (see [`Mnemo::rekey`]).
156    ///
157    /// Errors and the cleanup report work as in [`Mnemo::rekey`].
158    pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
159        self.rekey_secret(new_key, KdfParams::raw_key())
160    }
161
162    pub(super) fn rekey_secret(&mut self, secret: &[u8], kdf: KdfParams) -> Result<()> {
163        if self.shared {
164            // RB-007.2: the shared handle would keep the old secret, and
165            // fail at the next compaction or recovery.
166            return Err(MnemoError::Unsupported(
167                "inside a shared-mode window, change the passphrase with SharedMnemo::rekey, \
168                 which also updates the secret the handle keeps. Nothing was changed"
169                    .into(),
170            ));
171        }
172        self.rekey_unchecked(secret, kdf)
173    }
174
175    /// The rekey itself; [`SharedMnemo::rekey`] calls it in its window.
176    pub(super) fn rekey_unchecked(&mut self, secret: &[u8], kdf: KdfParams) -> Result<()> {
177        if self.read_only {
178            return Err(MnemoError::ReadOnly);
179        }
180        self.rekey_cleanup = None;
181        self.flush()?;
182        // v0.14.0 step 1: `flush` checks only when it has something to
183        // write; the rekey writes either way.
184        self.ensure_not_replaced()?;
185        let new_salt = crypto::random_salt();
186        let new_kek = crypto::derive_kek(secret, &new_salt, kdf)?;
187        let new_nonce = crypto::random_nonce();
188        let wrapped = crypto::wrap_dek(&new_kek, &new_nonce, self.pager.dek())?;
189        if wrapped.len() != WRAPPED_DEK_LEN {
190            return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
191        }
192        let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
193        wrapped_dek.copy_from_slice(&wrapped);
194
195        // SEC-2: the old header's key wrap (salt, DEK nonce, wrapped DEK, as
196        // laid out at header bytes 86..162), to scrub once the new header
197        // is committed.
198        let mut old_wrap =
199            Vec::with_capacity(crypto::SALT_LEN + crypto::NONCE_LEN + WRAPPED_DEK_LEN);
200        old_wrap.extend_from_slice(&self.header.salt);
201        old_wrap.extend_from_slice(&self.header.dek_nonce);
202        old_wrap.extend_from_slice(&self.header.wrapped_dek);
203
204        // REKEY-1 (RB-004.2): until the new page 0 is on disk, a failure puts
205        // these back, so an `Err` means "still the old secret".
206        let before = self.header.clone();
207        let before_kdf = self.kdf;
208
209        self.header.salt = new_salt;
210        self.header.dek_nonce = new_nonce;
211        self.header.wrapped_dek = wrapped_dek;
212        self.header.m_cost = kdf.m_cost;
213        self.header.t_cost = kdf.t_cost;
214        self.header.p_cost = kdf.p_cost;
215        self.kdf = kdf;
216
217        // DUR-1 (R-002.1): WAL-log the new page 0 before touching it.
218        // Allocate a fresh WAL region at the tail so that a crash during
219        // the rekey leaves either the old region (old passphrase works)
220        // or the new region (new passphrase works) fully committed —
221        // overwriting the existing region would risk destroying both.
222        let old_wal_start = self.header.wal_start;
223        let new_pages = self.header.wal_pages;
224        let new_start = self.header.next_page;
225        self.header.next_page += new_pages;
226        self.header.wal_start = new_start;
227        self.header.wal_pages = new_pages;
228        self.header.wal_seq += 1;
229
230        // The steps of `relocate_header_through_wal`, apart, so a failure
231        // can be told from one before page 0 and one after it.
232        self.header.write_counter = self.pager.write_counter;
233        let mut page = self.header.to_page();
234        if let Err(e) = self.header.apply_seal(&mut page, self.pager.dek()) {
235            return Err(self.undo_rekey(before, before_kdf, None, false, e));
236        }
237        let frames = vec![(0u64, page.to_vec())];
238        let txn_id = self.header.wal_seq;
239        if let Err(e) = wal::commit(self.pager.file_mut(), new_start, new_pages, txn_id, &frames) {
240            let region = Some((new_start, new_pages));
241            return Err(self.undo_rekey(before, before_kdf, region, false, e));
242        }
243        if let Err(e) = self
244            .pager
245            .write_raw(0, &page)
246            .and_then(|_| self.pager.sync())
247        {
248            let region = Some((new_start, new_pages));
249            return Err(self.undo_rekey(before, before_kdf, region, true, e));
250        }
251
252        // The new page 0 is on disk: the new secret is in force, and nothing
253        // below fails the rekey. SEC-2 (RB-001.30): zero the old region's
254        // first frame header (so no scan reads it as a WAL), then all of it
255        // (its frames hold page-0 images with the old wrap), then any other
256        // stale copy of the old wrap in the file (an earlier, grown or
257        // relocated region). Each step runs even if the one before failed.
258        // Hygiene only: a copy of the file taken before the rekey still
259        // opens with the old secret (see `rekey`).
260        let mut left = Vec::new();
261        if let Err(e) = wal::invalidate_region(self.pager.file_mut(), old_wal_start) {
262            left.push(format!("clearing the old WAL region's first frame: {e}"));
263        }
264        if let Err(e) = wal::scrub_region(self.pager.file_mut(), old_wal_start, new_pages) {
265            left.push(format!("zeroing the old WAL region: {e}"));
266        }
267        if let Err(e) = scrub_bytes(self.pager.file_mut(), &old_wrap) {
268            left.push(format!("overwriting other copies of the old key wrap: {e}"));
269        }
270        self.rekey_cleanup = (!left.is_empty()).then(|| left.join("; "));
271        // FMT-9 (a): the old region is freed by the next commit (see
272        // `ensure_wal_capacity`).
273        self.release_pages(old_wal_start, new_pages);
274        Ok(())
275    }
276
277    /// REKEY-1: a rekey failed before its new page 0 was on disk. Put the
278    /// header and the KDF back, so the handle (and every later write) uses
279    /// the old secret. Then, best effort: zero the new WAL region, whose
280    /// commit wraps the data key under the new secret, so a later
281    /// torn-header scan can't find it; and, if page 0 may have been
282    /// written, write the old one back.
283    fn undo_rekey(
284        &mut self,
285        before: crate::format::Header,
286        before_kdf: KdfParams,
287        new_region: Option<(u64, u64)>,
288        page0_written: bool,
289        err: MnemoError,
290    ) -> MnemoError {
291        self.header = before;
292        self.kdf = before_kdf;
293        // RB-005.2: a failed zeroing is reported, not dropped. The old
294        // secret is still in force either way; what's left is a committed
295        // copy of the new key wrap in the region past the file's end,
296        // which a torn-header scan could use with the new secret until a
297        // compaction clears it (a later write over those pages also does).
298        let scrub_failed = new_region.and_then(|(start, pages)| {
299            wal::scrub_region(self.pager.file_mut(), start, pages).err()
300        });
301        let with_scrub_note = |err: MnemoError| match &scrub_failed {
302            None => err,
303            Some(e) => MnemoError::Io(std::io::Error::other(format!(
304                "{err}; the old secret is still in force, but zeroing the new key wrap's \
305                 copy failed ({e}), so a copy may be left in the file until `mnemo compact` \
306                 clears it (a later write over those pages also does)"
307            ))),
308        };
309        if !page0_written {
310            return with_scrub_note(err);
311        }
312        self.header.write_counter = self.pager.write_counter;
313        let mut page = self.header.to_page();
314        let put_back = self
315            .header
316            .apply_seal(&mut page, self.pager.dek())
317            .and_then(|_| self.pager.write_raw(0, &page))
318            .and_then(|_| self.pager.sync());
319        match put_back {
320            Ok(()) => with_scrub_note(err),
321            // `mnemo rekey` looks for "may open with either secret" to leave
322            // out its "the passphrase was not changed": keep the phrase.
323            Err(again) => MnemoError::Io(std::io::Error::other(format!(
324                "rekey failed writing the new header ({err}), and the old header \
325                 couldn't be written back ({again}): the file may open with either \
326                 secret; close it without writing and try both"
327            ))),
328        }
329    }
330
331    /// REKEY-1 (RB-004.2): after a successful [`Mnemo::rekey`] or
332    /// [`Mnemo::rekey_with_key`], what couldn't be scrubbed of the old key
333    /// wrap, or `None` if it all was. The rekey took effect either way; what
334    /// is left is plaintext key-wrap bytes the old secret could still use, so
335    /// to be sure, rotate (`compact_file`) as [`Mnemo::rekey`] describes.
336    /// Each rekey resets it.
337    pub fn rekey_cleanup_error(&self) -> Option<&str> {
338        self.rekey_cleanup.as_deref()
339    }
340
341    /// SEC-2 (RB-001.30): write a copy of this database at `dest` under a
342    /// **fresh data key**, protected by `passphrase` through `kdf`. It goes
343    /// through the compaction path (live memories, the result cache and
344    /// the index, no history), so the copy shares no key material with
345    /// this file: neither this file's passphrase nor its data key opens
346    /// it, and its passphrase opens nothing here. This file is flushed
347    /// first (unless read-only) and is otherwise unchanged; `dest` must not
348    /// exist. The copy is v9.
349    pub fn export_rekeyed(
350        &mut self,
351        dest: impl AsRef<Path>,
352        passphrase: &str,
353        kdf: KdfParams,
354    ) -> Result<CompactReport> {
355        self.export_rekeyed_secret(dest.as_ref(), passphrase.as_bytes(), kdf)
356    }
357
358    /// [`Mnemo::export_rekeyed`] protected by a raw 256-bit key (no KDF).
359    pub fn export_rekeyed_with_key(
360        &mut self,
361        dest: impl AsRef<Path>,
362        key: &[u8; crypto::KEY_LEN],
363    ) -> Result<CompactReport> {
364        self.export_rekeyed_secret(dest.as_ref(), key, KdfParams::raw_key())
365    }
366
367    pub(super) fn export_rekeyed_secret(
368        &mut self,
369        dest: &Path,
370        secret: &[u8],
371        kdf: KdfParams,
372    ) -> Result<CompactReport> {
373        if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
374            return Err(MnemoError::Invalid(format!(
375                "export_rekeyed refuses to overwrite the open database at {}",
376                dest.display()
377            )));
378        }
379        if dest.exists() {
380            return Err(MnemoError::Invalid(format!(
381                "{} already exists",
382                dest.display()
383            )));
384        }
385        if !self.read_only {
386            self.flush()?;
387        }
388        let config = MnemoConfig {
389            dimensions: self.dimensions,
390            kdf,
391            store_float_vectors: self.float_vectors(),
392            ..Default::default()
393        };
394        let (tmp, mut new) = create_temp(dest, "export", secret, config)?;
395        let result = (|| {
396            let report = self.copy_live_into(&mut new)?;
397            new.flush()?;
398            drop(new);
399            std::fs::rename(&tmp, dest)?;
400            Ok(report)
401        })();
402        if result.is_err() {
403            let _ = std::fs::remove_file(&tmp);
404        }
405        result
406    }
407
408    /// The compaction copy: every live, unexpired memory and cache entry of
409    /// `self` into `new` (a freshly created file), and the index if `self`
410    /// has one. Counts as [`CompactReport`].
411    pub(super) fn copy_live_into(&mut self, new: &mut Mnemo) -> Result<CompactReport> {
412        // FMT-9e: compaction rewrites everything, so it compresses every
413        // thread turn, recent or not.
414        new.turn_compress_after = 0;
415        // ANN-1.1: compaction is "re-tune for the current size" by
416        // default. Pass IndexConfig::default() so partitions,
417        // subspaces, n_probe and n_rerank are all re-derived from the
418        // compacted vector count. Previously we froze the pre-compact
419        // (n_probe, n_rerank), which left the new index on stale
420        // numbers for the smaller post-compact corpus.
421        let want_index = self.has_index();
422        let now = memory::now_secs();
423        let all = self.memories()?;
424        let before = all.len();
425        let mut after = 0;
426        let mut zero_vector_manifests = 0;
427        let mut zero_vector_memories = 0;
428        for mut m in all {
429            if m.is_expired(now) {
430                continue;
431            }
432            // A file from before the zero-vector rule (Phase 3 PR 10a) can
433            // hold all-zero vectors. A legacy onboarding or manifest memory
434            // gets the sentinel unit vector a current manifest has, so it
435            // behaves like a new one; any other is carried unchanged.
436            if embed::is_zero_vector(&m.vector) {
437                if crud::is_onboarding(&m) || is_manifest(&m) {
438                    m.vector = Memory::scaffold_manifest(self.dimensions).vector;
439                    zero_vector_manifests += 1;
440                } else {
441                    zero_vector_memories += 1;
442                }
443            }
444            // The engine's own copy: `_mnemo.*` keys come through as they
445            // are, and the write-time zero-vector check doesn't apply.
446            new.put_existing(m)?;
447            after += 1;
448        }
449        if want_index && after > 0 {
450            new.build_index_with(IndexConfig::default())?;
451        }
452
453        // Count + copy cache entries. We walk `self.cache_dir` by index
454        // so each hop reads the directory's live `accessed_at` /
455        // `access_count` directly rather than going through
456        // `cache_get` (which would also treat read-only semantics,
457        // tombstones, etc. — we want the raw, authoritative values).
458        let mut cache_before = 0usize;
459        let mut cache_after = 0usize;
460        let positions: Vec<usize> = (0..self.cache_dir.len()).collect();
461        for pos in positions {
462            let (keep, reserved) = {
463                let e = &self.cache_dir[pos];
464                (
465                    !e.deleted && !e.is_expired(now),
466                    embed::is_reserved_namespace(&e.namespace),
467                )
468            };
469            if keep {
470                // EMBED-ID-1: the engine's own entries (the embedder
471                // identity) are copied but not counted.
472                new.copy_cache_entry_from(self, pos)?;
473                if !reserved {
474                    cache_before += 1;
475                    cache_after += 1;
476                }
477            }
478        }
479        Ok(CompactReport {
480            before,
481            after,
482            cache_before,
483            cache_after,
484            zero_vector_manifests,
485            zero_vector_memories,
486        })
487    }
488
489    /// Decrypt and validate every live record. Returns the count verified
490    /// across memories **and** cache entries (FIX-1 R-001.1: now that the
491    /// cache survives compaction, `verify()` has to walk it too — the
492    /// pre-FIX-1 implementation only checked `self.catalog`, so a
493    /// corrupted cache record went unnoticed).
494    pub fn verify(&mut self) -> Result<usize> {
495        Ok(self.verify_report()?.records)
496    }
497
498    /// [`Mnemo::verify`], also counting the memories whose vector is all
499    /// zeros. A file written before the zero-vector rule (Phase 3 PR 10a)
500    /// can hold them; they decode fine but score 0.0 on every vector query.
501    /// `mnemo verify` warns about them, and compaction carries them
502    /// (giving a legacy manifest the sentinel vector).
503    pub fn verify_report(&mut self) -> Result<VerifyReport> {
504        let entries: Vec<CatalogEntry> = self
505            .catalog
506            .iter()
507            .filter(|e| !e.deleted)
508            .cloned()
509            .collect();
510        let mut n = entries.len();
511        let mut zero_vector_memories = 0;
512        for e in &entries {
513            let bytes = self.read_record(e)?;
514            let m: Memory = self.decode_memory(&bytes)?;
515            // FMT-9b: and the row's vector column entry.
516            let zero = if e.v9.is_some() {
517                let (h, _) = self.column_entry(e)?;
518                if h.len() != self.dimensions {
519                    return Err(MnemoError::Invalid(
520                        "vector entry has the wrong width".into(),
521                    ));
522                }
523                // fp16 +0.0 and -0.0.
524                !h.is_empty() && h.iter().all(|b| b & 0x7fff == 0)
525            } else {
526                embed::is_zero_vector(&m.vector)
527            };
528            if zero {
529                zero_vector_memories += 1;
530            }
531        }
532
533        // Also decode every live cache entry. Tombstoned entries are
534        // skipped — their pages are orphan ciphertext awaiting
535        // `compact_file`, same as deleted memories. Expired entries
536        // are *still* on disk until compaction, so we verify them too.
537        let cache_positions: Vec<(u64, u32, u32, u64, bool)> = self
538            .cache_dir
539            .iter()
540            .filter(|e| !e.deleted)
541            .map(|e| {
542                let reserved = embed::is_reserved_namespace(&e.namespace);
543                (e.start_page, e.page_count, e.len, e.gen, reserved)
544            })
545            .collect();
546        for (start_page, page_count, len, gen, reserved) in cache_positions {
547            let buf = self.read_record_run(start_page, page_count, len, gen)?;
548            let _c: CacheEntry = rmp_serde::from_slice(&buf)
549                .map_err(|err| MnemoError::Serialize(err.to_string()))?;
550            // EMBED-ID-1: the engine's own entries are checked, not counted.
551            if !reserved {
552                n += 1;
553            }
554        }
555        // FMT-9 (a): no free run may overlap a page the committed state
556        // references (records, cache entries, control runs, the WAL).
557        if self.is_v9() {
558            self.check_free_list_disjoint()?;
559        }
560        Ok(VerifyReport {
561            records: n,
562            zero_vector_memories,
563        })
564    }
565
566    /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
567    /// page the current state references.
568    pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
569        let h = &self.header;
570        let mut live: Vec<(u64, u64, &str)> = vec![
571            (h.wal_start, h.wal_pages, "WAL region"),
572            (h.catalog_start, h.catalog_pages, "catalog run"),
573            (h.index_start, h.index_pages, "index run"),
574            (h.manifest_start, h.manifest_pages, "manifest run"),
575            (h.cache_start, h.cache_pages, "cache directory run"),
576            (h.free.start, h.free.pages, "free-list run"),
577            (h.keys.start, h.keys.pages, "key-slot run"),
578        ];
579        live.extend(
580            self.catalog
581                .iter()
582                .filter(|e| !e.deleted)
583                .map(|e| (e.start_page, e.page_count as u64, "record")),
584        );
585        live.extend(
586            self.cache_dir
587                .iter()
588                .filter(|e| !e.deleted)
589                .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
590        );
591        live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
592        live.extend(
593            self.delta_chain
594                .iter()
595                .map(|r| (r.start, r.pages, "catalog delta run")),
596        );
597        live.extend(
598            self.index_chain
599                .iter()
600                .map(|r| (r.start, r.pages, "index delta run")),
601        );
602        live.push((
603            self.header.bm25.start,
604            self.header.bm25.pages,
605            "BM25 manifest",
606        ));
607        live.extend(
608            self.bm25
609                .manifest
610                .segments
611                .iter()
612                .map(|t| (t.0, t.1, "BM25 segment")),
613        );
614        for (p, c, what) in live {
615            if c == 0 {
616                continue;
617            }
618            if self.free.overlaps(p, c) {
619                return Err(MnemoError::Invalid(format!(
620                    "free list overlaps a live {what} at page {p} (+{c})"
621                )));
622            }
623            if self
624                .pending_free
625                .iter()
626                .any(|&(q, n)| q < p + c && p < q + n)
627            {
628                return Err(MnemoError::Invalid(format!(
629                    "a pending free overlaps a live {what} at page {p} (+{c})"
630                )));
631            }
632        }
633        Ok(())
634    }
635
636    /// The statistics that need no record decrypts and no index load
637    /// (v0.12.2, RB-002.3): counts, sizes, the format, whether an index
638    /// exists, the recall mode and the bytes the vector column needs. The
639    /// first [`Mnemo::stats`] on a handle decrypts every record (for its
640    /// agent list) and loads a persisted index; this is what a phone app
641    /// polling the recall mode should call.
642    pub fn stats_summary(&self) -> StatsSummary {
643        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
644        let v9 = self.is_v9();
645        let column = if v9 {
646            (self.scored_rows() * crate::veccol::entry_len(self.dimensions)) as u64
647        } else {
648            0
649        };
650        let recall_mode = if self.has_index() {
651            RecallMode::Indexed
652        } else if v9 && column <= self.vector_cache_budget as u64 {
653            RecallMode::ExactResident
654        } else {
655            RecallMode::ExactPaged
656        };
657        let rp = self.restore_points();
658        StatsSummary {
659            memories: self.len(),
660            deleted,
661            dimensions: self.dimensions,
662            file_bytes: self.header.next_page * PAGE_SIZE as u64,
663            format_version: self.header.version,
664            wal_pages: self.header.wal_pages,
665            has_index: self.has_index(),
666            recall_mode,
667            vector_column_bytes: column,
668            snapshots_retained: rp.retained,
669            oldest_restorable_at: rp.oldest_at,
670            snapshot_pinned_bytes: rp.pinned_bytes,
671        }
672    }
673
674    /// Summary statistics for the open database. The first call on a
675    /// handle decrypts every record (to list the agents) and loads a
676    /// persisted index; [`Mnemo::stats_summary`] does neither.
677    pub fn stats(&mut self) -> Result<Stats> {
678        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
679        // FIX-1 R-001.8 part 2: build the agent set lazily on first
680        // call per handle, then maintain in `put` / invalidate in
681        // `delete`. Pre-FIX-1 every `stats()` call decrypted every
682        // live memory (O(N) AES-GCM decrypts just to list a usually-
683        // tiny set of distinct agent IDs). On a 1M-memory database
684        // this was in the multi-second range on hardware AES.
685        if self.agent_set.is_none() {
686            let built: std::collections::BTreeSet<String> =
687                self.memories()?.into_iter().map(|m| m.agent_id).collect();
688            self.agent_set = Some(built);
689        }
690        let agents: Vec<String> = self
691            .agent_set
692            .as_ref()
693            .expect("agent_set just filled above")
694            .iter()
695            .cloned()
696            .collect();
697        let file_bytes = self.header.next_page * PAGE_SIZE as u64;
698        let recall_mode = self.recall_mode()?;
699        let rp = self.restore_points();
700        Ok(Stats {
701            memories: self.len(),
702            deleted,
703            dimensions: self.dimensions,
704            file_bytes,
705            agents,
706            encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
707            created_at: self.header.created_at,
708            index: {
709                self.ensure_ann()?;
710                self.ann.as_ref().map(|a| a.info())
711            },
712            wal_pages: self.header.wal_pages,
713            fsyncs_last_flush: self.fsyncs_last_flush,
714            format_version: self.header.version,
715            recall_mode,
716            snapshots_retained: rp.retained,
717            oldest_restorable_at: rp.oldest_at,
718            snapshot_pinned_bytes: rp.pinned_bytes,
719        })
720    }
721
722    /// Rewrite the file, dropping tombstoned and expired memories and
723    /// reclaiming stale pages left by updates. Done out-of-place via a temp
724    /// file and an atomic rename.
725    ///
726    /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
727    /// compaction. Every live, non-expired directory entry is copied
728    /// into the new file verbatim — `created_at`, `ttl_secs`,
729    /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
730    /// `vector` and `model` come from the record body; `accessed_at`
731    /// and `access_count` come from the *directory* (the record body
732    /// only holds the insert-time snapshot — the directory is the
733    /// source of truth for the live counts, as of v5's recall trick).
734    /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
735    /// compaction kept only the memory catalog and silently emptied
736    /// the cache; the Planner's interim README caveat (c417d2e) called
737    /// that out — this PR removes the surprise.
738    ///
739    /// The output is always v9, so this is also how a v4–v8 file is
740    /// converted: the only read-write open that accepts one (the v8
741    /// sunset, v0.13). It keeps every live memory.
742    pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
743        Self::compact_file_secret(
744            path,
745            passphrase.as_bytes(),
746            0,
747            &crate::SharedOptions::default(),
748        )
749    }
750
751    /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
752    pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
753        Self::compact_file_secret(path, key, 0, &crate::SharedOptions::default())
754    }
755
756    /// [`Mnemo::compact_file`] with the lock layer's options: how long to
757    /// wait for the file's lock (`opts.deadline`; `compact_file` waits 10 s),
758    /// a cancel, and `allow_network_fs`. `mnemo compact --wait` uses it.
759    pub fn compact_file_waiting(
760        path: &str,
761        passphrase: &str,
762        opts: crate::SharedOptions,
763    ) -> Result<CompactReport> {
764        Self::compact_file_secret(path, passphrase.as_bytes(), 0, &opts)
765    }
766
767    /// [`Mnemo::compact_file_waiting`] for a raw-key database.
768    pub fn compact_file_waiting_with_key(
769        path: &str,
770        key: &[u8; crypto::KEY_LEN],
771        opts: crate::SharedOptions,
772    ) -> Result<CompactReport> {
773        Self::compact_file_secret(path, key, 0, &opts)
774    }
775
776    pub(super) fn compact_file_secret(
777        path: &str,
778        secret: &[u8],
779        format_version: u16,
780        opts: &crate::SharedOptions,
781    ) -> Result<CompactReport> {
782        // RB-007.3: compact the file the path names, through any symlink,
783        // and rename over that file, so a link stays a link and every path
784        // to the brain names the new file.
785        let real = std::fs::canonicalize(path)?;
786        // The one read-write open that takes a v4–v8 file (the v8 sunset).
787        // RB-007.4: through the lock layer, so shared handles' busy reads
788        // can't keep it out, and a shared caller that times out reads
789        // "compact" in the lock-info note.
790        let old = Mnemo::open_exclusive_secret(&real, secret, "compact", opts, true)?;
791        // RB-007.8 item 8: with the exclusive lock held no compaction of
792        // this file is running, so temp files left by dead ones can go.
793        remove_dead_compaction_temps(&real);
794        let dims = old.dimensions;
795        let kdf = old.kdf;
796        let config = MnemoConfig {
797            dimensions: dims,
798            kdf,
799            // FMT-9f: compaction writes v9 (upgrading a v8 file),
800            // unless `compact_file_to` asked for v8. A v9 file that
801            // keeps float vectors keeps them.
802            format_version,
803            store_float_vectors: old.float_vectors(),
804            ..Default::default()
805        };
806        // v0.14.0 step 1: a new file under a name no other compaction shares.
807        let (tmp, new) = create_temp(&real, "compact", secret, config)?;
808        // Created owner-only; it keeps the old file's mode.
809        if let Err(e) = copy_mode(old.pager.file(), new.pager.file()) {
810            drop(new);
811            let _ = std::fs::remove_file(&tmp);
812            return Err(e);
813        }
814        // `compact_into` releases the old file's lock only after the rename.
815        let result = Self::compact_into(old, new, &real, &tmp);
816        if result.is_err() {
817            let _ = std::fs::remove_file(&tmp);
818        }
819        result
820    }
821
822    /// Write the compacted copy of `old` to `tmp`, then rename it over
823    /// `path`, all while `old` holds the old file's exclusive lock.
824    ///
825    /// v0.14.0 step 1 (12.4's design note, "Gaps in today's code"): the lock
826    /// used to be released before the rename. A process that opened the
827    /// path in that window locked the old file and wrote to it, and the
828    /// rename then replaced it, losing those writes. Holding the lock
829    /// through the rename and the directory sync means a process either
830    /// waits on the old file's lock (and then finds, by `open_with_lock`'s
831    /// identity check, that the path names the new file) or opens the new
832    /// file.
833    ///
834    /// **Windows and the toolchain.** Renaming over a file another handle
835    /// holds open and locked works on Linux and macOS with every toolchain,
836    /// and on Windows when the engine is built with Rust 1.85 or later,
837    /// whose `std::fs::rename` uses POSIX semantics. Built with 1.75 to 1.84
838    /// (the MSRV is 1.75), Windows refuses it with "Access is denied" (os
839    /// error 5) while the old file is open, so the rename is retried once
840    /// after the old handle is closed, as before v0.14.0. That leaves the
841    /// old window open for those builds; each commit's identity check
842    /// (`ensure_not_replaced`) then turns nearly every write that would have
843    /// been lost into `Replaced`. (Probed on CI, 2026-11-13: 1.75 to 1.84
844    /// refuse, 1.85 to 1.100 succeed; the released binaries are built with
845    /// stable.)
846    fn compact_into(
847        mut old: Mnemo,
848        mut new: Mnemo,
849        path: &Path,
850        tmp: &Path,
851    ) -> Result<CompactReport> {
852        let report = old.copy_live_into(&mut new)?;
853
854        new.flush()?;
855        // The new file is closed before the rename: Windows won't rename a
856        // file this process still has open.
857        drop(new);
858
859        match std::fs::rename(tmp, path) {
860            Ok(()) => {}
861            #[cfg(windows)]
862            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
863                // A toolchain before 1.85: see above.
864                drop(old);
865                std::fs::rename(tmp, path)?;
866                return Ok(report);
867            }
868            Err(e) => return Err(MnemoError::Io(e)),
869        }
870        // Make the rename durable before the old file's lock goes.
871        #[cfg(unix)]
872        if let Some(parent) = path.parent() {
873            let parent = if parent.as_os_str().is_empty() {
874                Path::new(".")
875            } else {
876                parent
877            };
878            if let Ok(dir) = File::open(parent) {
879                let _ = dir.sync_all();
880                crate::bump_fsync();
881            }
882        }
883        // Only now does the old file's lock go.
884        drop(old);
885        Ok(report)
886    }
887
888    /// Copy one live cache entry from `old` at directory position
889    /// `pos` into `self` (a freshly-created compaction target).
890    /// Decrypts the old record body, substitutes the old *directory*'s
891    /// `accessed_at` + `access_count` (the record body's copies are
892    /// stale as of v5's directory-only hit path), re-encodes, writes
893    /// a fresh record run, and pushes a matching directory entry.
894    ///
895    /// Caller is expected to have already filtered out tombstoned /
896    /// expired entries and to call this on a read-write handle.
897    pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
898        if self.read_only {
899            return Err(MnemoError::ReadOnly);
900        }
901        // Snapshot the directory fields we need, so the borrow on
902        // `old.cache_dir` ends before we touch `old.pager`.
903        let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
904            let e = &old.cache_dir[pos];
905            (
906                e.start_page,
907                e.page_count,
908                e.len,
909                e.accessed_at,
910                e.access_count,
911                e.gen,
912            )
913        };
914
915        // Read + decrypt the old record body.
916        let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
917        let mut entry: CacheEntry =
918            rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
919
920        // Overwrite the stale body copies with the directory's live
921        // values before persisting. Everything else — `created_at`,
922        // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
923        // `content_type`, `value`, `vector`, `model` — stays as the
924        // body already recorded it.
925        entry.accessed_at = dir_accessed_at;
926        entry.access_count = dir_access_count;
927
928        let bytes =
929            rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
930        let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
931
932        let dir_entry = CacheDirectoryEntry {
933            namespace: entry.namespace.clone(),
934            key_hash: entry.key_hash,
935            start_page: new_start_page,
936            page_count: new_page_count,
937            len: bytes.len() as u32,
938            deleted: false,
939            accessed_at: dir_accessed_at,
940            access_count: dir_access_count,
941            size_bytes: entry.size_bytes,
942            ttl_secs: entry.ttl_secs,
943            created_at: entry.created_at,
944            vector: entry.vector.clone(),
945            model: entry.model.clone(),
946            gen,
947        };
948        let new_pos = self.cache_dir.len();
949        self.cache_idx
950            .insert(&entry.namespace, entry.key_hash, new_pos);
951        self.cache_dir.push(dir_entry);
952        self.dirty_cache = true;
953        Ok(())
954    }
955}
956
957/// SEC-2 (RB-001.30): overwrite every occurrence of `needle` in the file
958/// with zeros, then sync. Rekey uses it for stale copies of the old header's
959/// key wrap: they're plaintext (page 0 is sealed, not encrypted) and can sit
960/// in WAL regions that were grown, relocated or freed. Every other page is
961/// AES-GCM ciphertext, where a 76-byte random match doesn't happen.
962pub(super) fn scrub_bytes(file: &mut std::fs::File, needle: &[u8]) -> Result<usize> {
963    if needle.is_empty() {
964        return Ok(0);
965    }
966    let len = file.seek(SeekFrom::End(0))?;
967    let chunk = 1 << 20;
968    let overlap = needle.len() - 1;
969    let mut hits: Vec<u64> = Vec::new();
970    let mut buf = vec![0u8; chunk + overlap];
971    let mut pos: u64 = 0;
972    while pos < len {
973        let want = (chunk as u64 + overlap as u64).min(len - pos) as usize;
974        file.seek(SeekFrom::Start(pos))?;
975        file.read_exact(&mut buf[..want])?;
976        let mut i = 0;
977        while i + needle.len() <= want {
978            if buf[i..i + needle.len()] == *needle {
979                hits.push(pos + i as u64);
980                i += needle.len();
981            } else {
982                i += 1;
983            }
984        }
985        pos += chunk as u64;
986    }
987    hits.dedup();
988    let zeros = vec![0u8; needle.len()];
989    for off in &hits {
990        file.seek(SeekFrom::Start(*off))?;
991        file.write_all(&zeros)?;
992    }
993    if !hits.is_empty() {
994        file.sync_all()?;
995        crate::bump_fsync();
996    }
997    Ok(hits.len())
998}
999
1000/// RB-007.8 item 8: remove the temp files that compactions of `brain` left
1001/// when their process died: in `brain`'s directory, regular files named
1002/// exactly `<brain's name>.compact-<pid>-<n>-<8 hex digits>.tmp` (the
1003/// pattern [`temp_sibling`] makes) whose pid isn't this process and no
1004/// longer runs, and, on Unix, that this user owns: in a shared directory
1005/// another user's file of the same name is left alone. Nothing else is
1006/// touched. Best effort; returns how many went.
1007///
1008/// Call it only with `brain`'s exclusive lock held: a live compaction holds
1009/// that lock for as long as its temp file exists. Off Unix no process
1010/// check is available, so nothing is removed.
1011pub(crate) fn remove_dead_compaction_temps(brain: &Path) -> usize {
1012    let (Some(dir), Some(name)) = (brain.parent(), brain.file_name()) else {
1013        return 0;
1014    };
1015    let prefix = format!("{}.compact-", name.to_string_lossy());
1016    let Ok(entries) = std::fs::read_dir(dir) else {
1017        return 0;
1018    };
1019    let mut removed = 0;
1020    for entry in entries.flatten() {
1021        let file_name = entry.file_name();
1022        let Some(pid) = file_name.to_str().and_then(|n| dead_temp_pid(n, &prefix)) else {
1023            continue;
1024        };
1025        if pid == std::process::id() || crate::shared::pid_alive(pid) {
1026            continue;
1027        }
1028        let path = entry.path();
1029        let Ok(meta) = std::fs::symlink_metadata(&path) else {
1030            continue;
1031        };
1032        if !meta.file_type().is_file() || !owned_by_us(&meta) {
1033            continue;
1034        }
1035        if std::fs::remove_file(&path).is_ok() {
1036            removed += 1;
1037        }
1038    }
1039    removed
1040}
1041
1042/// Whether this process's user owns the file (Unix). Elsewhere, true: the
1043/// caller removes nothing off Unix anyway.
1044#[cfg(unix)]
1045fn owned_by_us(meta: &std::fs::Metadata) -> bool {
1046    use std::os::unix::fs::MetadataExt;
1047    #[cfg(any(test, feature = "failpoints"))]
1048    if let Some(uid) = crate::__failpoints::euid_override() {
1049        return meta.uid() == uid;
1050    }
1051    meta.uid() == rustix::process::geteuid().as_raw()
1052}
1053
1054#[cfg(not(unix))]
1055fn owned_by_us(_meta: &std::fs::Metadata) -> bool {
1056    true
1057}
1058
1059/// The pid in a compaction temp name `<prefix><pid>-<n>-<8 hex>.tmp`, if the
1060/// name is exactly that.
1061fn dead_temp_pid(name: &str, prefix: &str) -> Option<u32> {
1062    let rest = name.strip_prefix(prefix)?.strip_suffix(".tmp")?;
1063    let mut parts = rest.split('-');
1064    let (pid, n, nanos) = (parts.next()?, parts.next()?, parts.next()?);
1065    let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
1066    let hex8 = nanos.len() == 8 && nanos.bytes().all(|b| b.is_ascii_hexdigit());
1067    if parts.next().is_some() || !digits(pid) || !digits(n) || !hex8 {
1068        return None;
1069    }
1070    pid.parse().ok()
1071}
1072
1073/// A new, locked temp file next to `dest` (`Create::New`, so nothing already
1074/// at the name, a symlink included, is ever written through), under a fresh
1075/// name for each attempt while names are taken. RB-006.10.
1076fn create_temp(
1077    dest: &Path,
1078    what: &str,
1079    secret: &[u8],
1080    config: MnemoConfig,
1081) -> Result<(PathBuf, Mnemo)> {
1082    let mut attempt = 0;
1083    loop {
1084        let tmp = temp_sibling(dest, what);
1085        match Mnemo::create_secret_new(&tmp, secret, config) {
1086            Ok(new) => return Ok((tmp, new)),
1087            Err(e) if is_name_taken(&e) && attempt + 1 < TEMP_NAME_ATTEMPTS => attempt += 1,
1088            Err(e) => return Err(e),
1089        }
1090    }
1091}