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(), SecretKind::Passphrase, 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, SecretKind::Key, KdfParams::raw_key())
160    }
161
162    pub(super) fn rekey_secret(
163        &mut self,
164        secret: &[u8],
165        kind: SecretKind,
166        kdf: KdfParams,
167    ) -> Result<()> {
168        if self.shared {
169            // RB-007.2: the shared handle would keep the old secret, and
170            // fail at the next compaction or recovery.
171            return Err(MnemoError::Unsupported(
172                "inside a shared-mode window, change the passphrase with SharedMnemo::rekey, \
173                 which also updates the secret the handle keeps. Nothing was changed"
174                    .into(),
175            ));
176        }
177        self.rekey_unchecked(secret, kind, kdf, None)
178    }
179
180    /// 12.3 (the keys note, section 4): [`Mnemo::rekey`] or
181    /// [`Mnemo::rekey_with_key`], with `before_commit` run once the new salt
182    /// is drawn and before anything is written, so a caller can store the new
183    /// secret under that salt first. An error from it stops the rekey with
184    /// nothing changed. Used by [`crate::keys::rekey_stored`].
185    pub(crate) fn rekey_staged(
186        &mut self,
187        secret: &[u8],
188        kind: SecretKind,
189        kdf: KdfParams,
190        before_commit: &mut crypto::SaltHook<'_>,
191    ) -> Result<()> {
192        if self.shared {
193            return Err(MnemoError::Unsupported(
194                "a staged rekey runs on a plain handle only".into(),
195            ));
196        }
197        self.rekey_unchecked(secret, kind, kdf, Some(before_commit))
198    }
199
200    /// The rekey itself; [`SharedMnemo::rekey`] calls it in its window. 12.3:
201    /// where every rekey meets, so a passphrase with raw-key parameters is
202    /// refused here (the keys note, section 1, rule 2).
203    pub(super) fn rekey_unchecked(
204        &mut self,
205        secret: &[u8],
206        kind: SecretKind,
207        kdf: KdfParams,
208        before_commit: Option<&mut crypto::SaltHook<'_>>,
209    ) -> Result<()> {
210        if self.read_only {
211            return Err(MnemoError::ReadOnly);
212        }
213        crypto::check_kdf_for(kind, kdf)?;
214        self.rekey_cleanup = None;
215        self.flush()?;
216        // v0.14.0 step 1: `flush` checks only when it has something to
217        // write; the rekey writes either way.
218        self.ensure_not_replaced()?;
219        let new_salt = crypto::random_salt();
220        let new_kek = crypto::derive_kek(secret, &new_salt, kdf)?;
221        let new_nonce = crypto::random_nonce();
222        let wrapped = crypto::wrap_dek(&new_kek, &new_nonce, self.pager.dek())?;
223        if wrapped.len() != WRAPPED_DEK_LEN {
224            return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
225        }
226        let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
227        wrapped_dek.copy_from_slice(&wrapped);
228        // 12.3: the caller stores the new secret under `new_salt` before
229        // anything is written.
230        if let Some(hook) = before_commit {
231            hook(&new_salt)?;
232        }
233
234        // SEC-2: the old header's key wrap (salt, DEK nonce, wrapped DEK, as
235        // laid out at header bytes 86..162), to scrub once the new header
236        // is committed.
237        let mut old_wrap =
238            Vec::with_capacity(crypto::SALT_LEN + crypto::NONCE_LEN + WRAPPED_DEK_LEN);
239        old_wrap.extend_from_slice(&self.header.salt);
240        old_wrap.extend_from_slice(&self.header.dek_nonce);
241        old_wrap.extend_from_slice(&self.header.wrapped_dek);
242
243        // REKEY-1 (RB-004.2): until the new page 0 is on disk, a failure puts
244        // these back, so an `Err` means "still the old secret".
245        let before = self.header.clone();
246        let before_kdf = self.kdf;
247
248        self.header.salt = new_salt;
249        self.header.dek_nonce = new_nonce;
250        self.header.wrapped_dek = wrapped_dek;
251        self.header.m_cost = kdf.m_cost;
252        self.header.t_cost = kdf.t_cost;
253        self.header.p_cost = kdf.p_cost;
254        self.kdf = kdf;
255
256        // DUR-1 (R-002.1): WAL-log the new page 0 before touching it.
257        // Allocate a fresh WAL region at the tail so that a crash during
258        // the rekey leaves either the old region (old passphrase works)
259        // or the new region (new passphrase works) fully committed —
260        // overwriting the existing region would risk destroying both.
261        let old_wal_start = self.header.wal_start;
262        let new_pages = self.header.wal_pages;
263        let new_start = self.header.next_page;
264        self.header.next_page += new_pages;
265        self.header.wal_start = new_start;
266        self.header.wal_pages = new_pages;
267        self.header.wal_seq += 1;
268
269        // The steps of `relocate_header_through_wal`, apart, so a failure
270        // can be told from one before page 0 and one after it.
271        self.header.write_counter = self.pager.write_counter;
272        let mut page = self.header.to_page();
273        if let Err(e) = self.header.apply_seal(&mut page, self.pager.dek()) {
274            return Err(self.undo_rekey(before, before_kdf, None, false, e));
275        }
276        let frames = vec![(0u64, page.to_vec())];
277        let txn_id = self.header.wal_seq;
278        if let Err(e) = wal::commit(self.pager.file_mut(), new_start, new_pages, txn_id, &frames) {
279            let region = Some((new_start, new_pages));
280            return Err(self.undo_rekey(before, before_kdf, region, false, e));
281        }
282        if let Err(e) = self
283            .pager
284            .write_raw(0, &page)
285            .and_then(|_| self.pager.sync())
286        {
287            let region = Some((new_start, new_pages));
288            return Err(self.undo_rekey(before, before_kdf, region, true, e));
289        }
290
291        // The new page 0 is on disk: the new secret is in force, and nothing
292        // below fails the rekey. SEC-2 (RB-001.30): zero the old region's
293        // first frame header (so no scan reads it as a WAL), then all of it
294        // (its frames hold page-0 images with the old wrap), then any other
295        // stale copy of the old wrap in the file (an earlier, grown or
296        // relocated region). Each step runs even if the one before failed.
297        // Hygiene only: a copy of the file taken before the rekey still
298        // opens with the old secret (see `rekey`).
299        let mut left = Vec::new();
300        if let Err(e) = wal::invalidate_region(self.pager.file_mut(), old_wal_start) {
301            left.push(format!("clearing the old WAL region's first frame: {e}"));
302        }
303        if let Err(e) = wal::scrub_region(self.pager.file_mut(), old_wal_start, new_pages) {
304            left.push(format!("zeroing the old WAL region: {e}"));
305        }
306        if let Err(e) = scrub_bytes(self.pager.file_mut(), &old_wrap) {
307            left.push(format!("overwriting other copies of the old key wrap: {e}"));
308        }
309        self.rekey_cleanup = (!left.is_empty()).then(|| left.join("; "));
310        // FMT-9 (a): the old region is freed by the next commit (see
311        // `ensure_wal_capacity`).
312        self.release_pages(old_wal_start, new_pages);
313        Ok(())
314    }
315
316    /// REKEY-1: a rekey failed before its new page 0 was on disk. Put the
317    /// header and the KDF back, so the handle (and every later write) uses
318    /// the old secret. Then, best effort: zero the new WAL region, whose
319    /// commit wraps the data key under the new secret, so a later
320    /// torn-header scan can't find it; and, if page 0 may have been
321    /// written, write the old one back.
322    fn undo_rekey(
323        &mut self,
324        before: crate::format::Header,
325        before_kdf: KdfParams,
326        new_region: Option<(u64, u64)>,
327        page0_written: bool,
328        err: MnemoError,
329    ) -> MnemoError {
330        self.header = before;
331        self.kdf = before_kdf;
332        // RB-005.2: a failed zeroing is reported, not dropped. The old
333        // secret is still in force either way; what's left is a committed
334        // copy of the new key wrap in the region past the file's end,
335        // which a torn-header scan could use with the new secret until a
336        // compaction clears it (a later write over those pages also does).
337        let scrub_failed = new_region.and_then(|(start, pages)| {
338            wal::scrub_region(self.pager.file_mut(), start, pages).err()
339        });
340        let with_scrub_note = |err: MnemoError| match &scrub_failed {
341            None => err,
342            Some(e) => MnemoError::Io(std::io::Error::other(format!(
343                "{err}; the old secret is still in force, but zeroing the new key wrap's \
344                 copy failed ({e}), so a copy may be left in the file until `mnemo compact` \
345                 clears it (a later write over those pages also does)"
346            ))),
347        };
348        if !page0_written {
349            return with_scrub_note(err);
350        }
351        self.header.write_counter = self.pager.write_counter;
352        let mut page = self.header.to_page();
353        let put_back = self
354            .header
355            .apply_seal(&mut page, self.pager.dek())
356            .and_then(|_| self.pager.write_raw(0, &page))
357            .and_then(|_| self.pager.sync());
358        match put_back {
359            Ok(()) => with_scrub_note(err),
360            // `mnemo rekey` looks for "may open with either secret" to leave
361            // out its "the passphrase was not changed": keep the phrase.
362            Err(again) => MnemoError::Io(std::io::Error::other(format!(
363                "rekey failed writing the new header ({err}), and the old header \
364                 couldn't be written back ({again}): the file {EITHER_SECRET}; close it \
365                 without writing and try both"
366            ))),
367        }
368    }
369
370    /// 12.3: whether `e` is REKEY-1's one exception, the error that says the
371    /// file may open with either secret. Kept beside the message it reads.
372    pub(crate) fn rekey_left_either_secret(e: &MnemoError) -> bool {
373        e.to_string().contains(EITHER_SECRET)
374    }
375
376    /// REKEY-1 (RB-004.2): after a successful [`Mnemo::rekey`] or
377    /// [`Mnemo::rekey_with_key`], what couldn't be scrubbed of the old key
378    /// wrap, or `None` if it all was. The rekey took effect either way; what
379    /// is left is plaintext key-wrap bytes the old secret could still use, so
380    /// to be sure, rotate (`compact_file`) as [`Mnemo::rekey`] describes.
381    /// Each rekey resets it.
382    pub fn rekey_cleanup_error(&self) -> Option<&str> {
383        self.rekey_cleanup.as_deref()
384    }
385
386    /// SEC-2 (RB-001.30): write a copy of this database at `dest` under a
387    /// **fresh data key**, protected by `passphrase` through `kdf`. It goes
388    /// through the compaction path (live memories, the result cache and
389    /// the index, no history), so the copy shares no key material with
390    /// this file: neither this file's passphrase nor its data key opens
391    /// it, and its passphrase opens nothing here. This file is flushed
392    /// first (unless read-only) and is otherwise unchanged; `dest` must not
393    /// exist. The copy is v9.
394    pub fn export_rekeyed(
395        &mut self,
396        dest: impl AsRef<Path>,
397        passphrase: &str,
398        kdf: KdfParams,
399    ) -> Result<CompactReport> {
400        self.export_rekeyed_secret(
401            dest.as_ref(),
402            passphrase.as_bytes(),
403            SecretKind::Passphrase,
404            kdf,
405        )
406    }
407
408    /// [`Mnemo::export_rekeyed`] protected by a raw 256-bit key (no KDF).
409    pub fn export_rekeyed_with_key(
410        &mut self,
411        dest: impl AsRef<Path>,
412        key: &[u8; crypto::KEY_LEN],
413    ) -> Result<CompactReport> {
414        self.export_rekeyed_secret(dest.as_ref(), key, SecretKind::Key, KdfParams::raw_key())
415    }
416
417    pub(super) fn export_rekeyed_secret(
418        &mut self,
419        dest: &Path,
420        secret: &[u8],
421        kind: SecretKind,
422        kdf: KdfParams,
423    ) -> Result<CompactReport> {
424        crypto::check_kdf_for(kind, kdf)?;
425        if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
426            return Err(MnemoError::Invalid(format!(
427                "export_rekeyed refuses to overwrite the open database at {}",
428                dest.display()
429            )));
430        }
431        if dest.exists() {
432            return Err(MnemoError::Invalid(format!(
433                "{} already exists",
434                dest.display()
435            )));
436        }
437        if !self.read_only {
438            self.flush()?;
439        }
440        let config = MnemoConfig {
441            dimensions: self.dimensions,
442            kdf,
443            store_float_vectors: self.float_vectors(),
444            ..Default::default()
445        };
446        let (tmp, mut new) = create_temp(dest, "export", secret, kind, config, None)?;
447        let result = (|| {
448            let report = self.copy_live_into(&mut new)?;
449            new.flush()?;
450            drop(new);
451            std::fs::rename(&tmp, dest)?;
452            Ok(report)
453        })();
454        if result.is_err() {
455            let _ = std::fs::remove_file(&tmp);
456        }
457        result
458    }
459
460    /// The compaction copy: every live, unexpired memory and cache entry of
461    /// `self` into `new` (a freshly created file), and the index if `self`
462    /// has one. Counts as [`CompactReport`].
463    pub(super) fn copy_live_into(&mut self, new: &mut Mnemo) -> Result<CompactReport> {
464        // FMT-9e: compaction rewrites everything, so it compresses every
465        // thread turn, recent or not.
466        new.turn_compress_after = 0;
467        // ANN-1.1: compaction is "re-tune for the current size" by
468        // default. Pass IndexConfig::default() so partitions,
469        // subspaces, n_probe and n_rerank are all re-derived from the
470        // compacted vector count. Previously we froze the pre-compact
471        // (n_probe, n_rerank), which left the new index on stale
472        // numbers for the smaller post-compact corpus.
473        let want_index = self.has_index();
474        let now = memory::now_secs();
475        let all = self.memories()?;
476        let before = all.len();
477        let mut after = 0;
478        let mut zero_vector_manifests = 0;
479        let mut zero_vector_memories = 0;
480        for mut m in all {
481            if m.is_expired(now) {
482                continue;
483            }
484            // 13a (R-010.8): a message acked more than 30 days ago.
485            if super::coordination::compact_drops(&m, now) {
486                continue;
487            }
488            // A file from before the zero-vector rule (Phase 3 PR 10a) can
489            // hold all-zero vectors. A legacy onboarding or manifest memory
490            // gets the sentinel unit vector a current manifest has, so it
491            // behaves like a new one; any other is carried unchanged.
492            if embed::is_zero_vector(&m.vector) {
493                if crud::is_onboarding(&m) || is_manifest(&m) {
494                    m.vector = Memory::scaffold_manifest(self.dimensions).vector;
495                    zero_vector_manifests += 1;
496                } else {
497                    zero_vector_memories += 1;
498                }
499            }
500            // The engine's own copy: `_mnemo.*` keys come through as they
501            // are, and the write-time zero-vector check doesn't apply.
502            new.put_existing(m)?;
503            after += 1;
504        }
505        if want_index && after > 0 {
506            new.build_index_with(IndexConfig::default())?;
507        }
508
509        // Count + copy cache entries. We walk `self.cache_dir` by index
510        // so each hop reads the directory's live `accessed_at` /
511        // `access_count` directly rather than going through
512        // `cache_get` (which would also treat read-only semantics,
513        // tombstones, etc. — we want the raw, authoritative values).
514        let mut cache_before = 0usize;
515        let mut cache_after = 0usize;
516        let positions: Vec<usize> = (0..self.cache_dir.len()).collect();
517        for pos in positions {
518            let (keep, reserved) = {
519                let e = &self.cache_dir[pos];
520                (
521                    !e.deleted && !e.is_expired(now),
522                    embed::is_reserved_namespace(&e.namespace),
523                )
524            };
525            if keep {
526                // EMBED-ID-1: the engine's own entries (the embedder
527                // identity) are copied but not counted.
528                new.copy_cache_entry_from(self, pos)?;
529                if !reserved {
530                    cache_before += 1;
531                    cache_after += 1;
532                }
533            }
534        }
535        Ok(CompactReport {
536            before,
537            after,
538            cache_before,
539            cache_after,
540            zero_vector_manifests,
541            zero_vector_memories,
542        })
543    }
544
545    /// Decrypt and validate every live record. Returns the count verified
546    /// across memories **and** cache entries (FIX-1 R-001.1: now that the
547    /// cache survives compaction, `verify()` has to walk it too — the
548    /// pre-FIX-1 implementation only checked `self.catalog`, so a
549    /// corrupted cache record went unnoticed).
550    pub fn verify(&mut self) -> Result<usize> {
551        Ok(self.verify_report()?.records)
552    }
553
554    /// [`Mnemo::verify`], also counting the memories whose vector is all
555    /// zeros. A file written before the zero-vector rule (Phase 3 PR 10a)
556    /// can hold them; they decode fine but score 0.0 on every vector query.
557    /// `mnemo verify` warns about them, and compaction carries them
558    /// (giving a legacy manifest the sentinel vector).
559    pub fn verify_report(&mut self) -> Result<VerifyReport> {
560        let entries: Vec<CatalogEntry> = self
561            .catalog
562            .iter()
563            .filter(|e| !e.deleted)
564            .cloned()
565            .collect();
566        let mut n = entries.len();
567        let mut zero_vector_memories = 0;
568        for e in &entries {
569            let bytes = self.read_record(e)?;
570            let m: Memory = self.decode_memory(&bytes)?;
571            // FMT-9b: and the row's vector column entry.
572            let zero = if e.v9.is_some() {
573                let (h, _) = self.column_entry(e)?;
574                if h.len() != self.dimensions {
575                    return Err(MnemoError::Invalid(
576                        "vector entry has the wrong width".into(),
577                    ));
578                }
579                // fp16 +0.0 and -0.0.
580                !h.is_empty() && h.iter().all(|b| b & 0x7fff == 0)
581            } else {
582                embed::is_zero_vector(&m.vector)
583            };
584            if zero {
585                zero_vector_memories += 1;
586            }
587        }
588
589        // Also decode every live cache entry. Tombstoned entries are
590        // skipped — their pages are orphan ciphertext awaiting
591        // `compact_file`, same as deleted memories. Expired entries
592        // are *still* on disk until compaction, so we verify them too.
593        let cache_positions: Vec<(u64, u32, u32, u64, bool)> = self
594            .cache_dir
595            .iter()
596            .filter(|e| !e.deleted)
597            .map(|e| {
598                let reserved = embed::is_reserved_namespace(&e.namespace);
599                (e.start_page, e.page_count, e.len, e.gen, reserved)
600            })
601            .collect();
602        for (start_page, page_count, len, gen, reserved) in cache_positions {
603            let buf = self.read_record_run(start_page, page_count, len, gen)?;
604            let _c: CacheEntry = rmp_serde::from_slice(&buf)
605                .map_err(|err| MnemoError::Serialize(err.to_string()))?;
606            // EMBED-ID-1: the engine's own entries are checked, not counted.
607            if !reserved {
608                n += 1;
609            }
610        }
611        // FMT-9 (a): no free run may overlap a page the committed state
612        // references (records, cache entries, control runs, the WAL).
613        if self.is_v9() {
614            self.check_free_list_disjoint()?;
615        }
616        Ok(VerifyReport {
617            records: n,
618            zero_vector_memories,
619            keyword_tokenizer: self.keyword_tokenizer()?,
620        })
621    }
622
623    /// RB-015.1 (v0.19.1): read the persisted ANN index run and its delta
624    /// runs from disk, apart from [`Mnemo::verify_report`]'s records. The
625    /// index is derived data, so a damaged one is reported, not an error:
626    /// the memories are intact and `mnemo index --rebuild` replaces it. An
627    /// I/O error still fails the call. Reads only; this handle's own
628    /// loaded index (if any) isn't touched.
629    pub fn verify_index(&mut self) -> Result<IndexCheck> {
630        let h = &self.header;
631        let (start, pages, len, gen, delta) = (
632            h.index_start,
633            h.index_pages,
634            h.index_len,
635            h.index_gen,
636            h.index_delta,
637        );
638        if pages == 0 {
639            return Ok(IndexCheck::None);
640        }
641        let damaged = |e: MnemoError| -> Result<IndexCheck> {
642            if index_damage(&e) {
643                Ok(IndexCheck::Damaged(e.to_string()))
644            } else {
645                Err(e)
646            }
647        };
648        let buf = match read_run_bytes(&mut self.pager, start, pages, len, gen) {
649            Ok(b) => b,
650            Err(e) => return damaged(e),
651        };
652        let decoded: Result<crate::index::IvfPqIndex> = if !self.is_v9() {
653            rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))
654        } else {
655            match buf.first() {
656                Some(&V9_INDEX_LAYOUT) => {
657                    crate::index::IvfPqIndex::read_layout2(&mut &buf[1..], buf.len() as u64 - 1)
658                }
659                Some(&V9_INDEX_LAYOUT_MSGPACK) => rmp_serde::from_slice(&buf[1..])
660                    .map_err(|e| MnemoError::Serialize(e.to_string())),
661                Some(&other) => return Ok(IndexCheck::UnknownLayout(other)),
662                None => Err(MnemoError::Invalid("the index run is empty".into())),
663            }
664        };
665        let mut idx = match decoded {
666            Ok(i) => i,
667            Err(e) => return damaged(e),
668        };
669        if idx.dims() != self.dimensions {
670            return damaged(MnemoError::Invalid(
671                "ANN index dimensionality does not match the database".into(),
672            ));
673        }
674        let delta_runs = if self.is_v9() {
675            match apply_index_chain(&mut self.pager, &mut idx, delta) {
676                Ok((chain, _)) => chain.len(),
677                Err(e) => return damaged(e),
678            }
679        } else {
680            0
681        };
682        Ok(IndexCheck::Ok {
683            vectors: idx.len(),
684            delta_runs,
685        })
686    }
687
688    /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
689    /// page the current state references.
690    pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
691        let h = &self.header;
692        let mut live: Vec<(u64, u64, &str)> = vec![
693            (h.wal_start, h.wal_pages, "WAL region"),
694            (h.catalog_start, h.catalog_pages, "catalog run"),
695            (h.index_start, h.index_pages, "index run"),
696            (h.manifest_start, h.manifest_pages, "manifest run"),
697            (h.cache_start, h.cache_pages, "cache directory run"),
698            (h.free.start, h.free.pages, "free-list run"),
699            (h.keys.start, h.keys.pages, "key-slot run"),
700        ];
701        live.extend(
702            self.catalog
703                .iter()
704                .filter(|e| !e.deleted)
705                .map(|e| (e.start_page, e.page_count as u64, "record")),
706        );
707        live.extend(
708            self.cache_dir
709                .iter()
710                .filter(|e| !e.deleted)
711                .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
712        );
713        live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
714        live.extend(
715            self.delta_chain
716                .iter()
717                .map(|r| (r.start, r.pages, "catalog delta run")),
718        );
719        live.extend(
720            self.index_chain
721                .iter()
722                .map(|r| (r.start, r.pages, "index delta run")),
723        );
724        live.push((
725            self.header.bm25.start,
726            self.header.bm25.pages,
727            "BM25 manifest",
728        ));
729        live.extend(
730            self.bm25
731                .manifest
732                .segments
733                .iter()
734                .map(|t| (t.0, t.1, "BM25 segment")),
735        );
736        for (p, c, what) in live {
737            if c == 0 {
738                continue;
739            }
740            if self.free.overlaps(p, c) {
741                return Err(MnemoError::Invalid(format!(
742                    "free list overlaps a live {what} at page {p} (+{c})"
743                )));
744            }
745            if self
746                .pending_free
747                .iter()
748                .any(|&(q, n)| q < p + c && p < q + n)
749            {
750                return Err(MnemoError::Invalid(format!(
751                    "a pending free overlaps a live {what} at page {p} (+{c})"
752                )));
753            }
754        }
755        Ok(())
756    }
757
758    /// The statistics that need no record decrypts and no index load
759    /// (v0.12.2, RB-002.3): counts, sizes, the format, whether an index
760    /// exists, the recall mode and the bytes the vector column needs. The
761    /// first [`Mnemo::stats`] on a handle decrypts every record (for its
762    /// agent list) and loads a persisted index; this is what a phone app
763    /// polling the recall mode should call.
764    pub fn stats_summary(&self) -> StatsSummary {
765        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
766        let v9 = self.is_v9();
767        let column = if v9 {
768            (self.scored_rows() * crate::veccol::entry_len(self.dimensions)) as u64
769        } else {
770            0
771        };
772        let recall_mode = if self.has_index() {
773            RecallMode::Indexed
774        } else if v9 && column <= self.vector_cache_budget as u64 {
775            RecallMode::ExactResident
776        } else {
777            RecallMode::ExactPaged
778        };
779        let rp = self.restore_points();
780        StatsSummary {
781            memories: self.len(),
782            deleted,
783            dimensions: self.dimensions,
784            file_bytes: self.header.next_page * PAGE_SIZE as u64,
785            format_version: self.header.version,
786            wal_pages: self.header.wal_pages,
787            has_index: self.has_index(),
788            recall_mode,
789            vector_column_bytes: column,
790            snapshots_retained: rp.retained,
791            oldest_restorable_at: rp.oldest_at,
792            snapshot_pinned_bytes: rp.pinned_bytes,
793        }
794    }
795
796    /// Summary statistics for the open database. The first call on a
797    /// handle decrypts every record (to list the agents) and loads a
798    /// persisted index; [`Mnemo::stats_summary`] does neither.
799    pub fn stats(&mut self) -> Result<Stats> {
800        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
801        // FIX-1 R-001.8 part 2: build the agent set lazily on first
802        // call per handle, then maintain in `put` / invalidate in
803        // `delete`. Pre-FIX-1 every `stats()` call decrypted every
804        // live memory (O(N) AES-GCM decrypts just to list a usually-
805        // tiny set of distinct agent IDs). On a 1M-memory database
806        // this was in the multi-second range on hardware AES.
807        if self.agent_set.is_none() {
808            let built: std::collections::BTreeSet<String> =
809                self.memories()?.into_iter().map(|m| m.agent_id).collect();
810            self.agent_set = Some(built);
811        }
812        let agents: Vec<String> = self
813            .agent_set
814            .as_ref()
815            .expect("agent_set just filled above")
816            .iter()
817            .cloned()
818            .collect();
819        let file_bytes = self.header.next_page * PAGE_SIZE as u64;
820        let recall_mode = self.recall_mode()?;
821        let rp = self.restore_points();
822        Ok(Stats {
823            memories: self.len(),
824            deleted,
825            dimensions: self.dimensions,
826            file_bytes,
827            agents,
828            encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
829            created_at: self.header.created_at,
830            index: {
831                self.ensure_ann()?;
832                self.ann.as_ref().map(|a| a.info())
833            },
834            wal_pages: self.header.wal_pages,
835            fsyncs_last_flush: self.fsyncs_last_flush,
836            format_version: self.header.version,
837            recall_mode,
838            snapshots_retained: rp.retained,
839            oldest_restorable_at: rp.oldest_at,
840            snapshot_pinned_bytes: rp.pinned_bytes,
841            keyword_tokenizer: self.keyword_tokenizer()?,
842        })
843    }
844
845    /// Rewrite the file, dropping tombstoned and expired memories and
846    /// reclaiming stale pages left by updates. Done out-of-place via a temp
847    /// file and an atomic rename.
848    ///
849    /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
850    /// compaction. Every live, non-expired directory entry is copied
851    /// into the new file verbatim — `created_at`, `ttl_secs`,
852    /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
853    /// `vector` and `model` come from the record body; `accessed_at`
854    /// and `access_count` come from the *directory* (the record body
855    /// only holds the insert-time snapshot — the directory is the
856    /// source of truth for the live counts, as of v5's recall trick).
857    /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
858    /// compaction kept only the memory catalog and silently emptied
859    /// the cache; the Planner's interim README caveat (c417d2e) called
860    /// that out — this PR removes the surprise.
861    ///
862    /// The output is always v9, so this is also how a v4–v8 file is
863    /// converted: the only read-write open that accepts one (the v8
864    /// sunset, v0.13). It keeps every live memory.
865    pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
866        Self::compact_file_secret(
867            path,
868            passphrase.as_bytes(),
869            SecretKind::Passphrase,
870            0,
871            &crate::SharedOptions::default(),
872        )
873    }
874
875    /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
876    pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
877        Self::compact_file_secret(
878            path,
879            key,
880            SecretKind::Key,
881            0,
882            &crate::SharedOptions::default(),
883        )
884    }
885
886    /// [`Mnemo::compact_file`] with the lock layer's options: how long to
887    /// wait for the file's lock (`opts.deadline`; `compact_file` waits 10 s),
888    /// a cancel, and `allow_network_fs`. `mnemo compact --wait` uses it.
889    pub fn compact_file_waiting(
890        path: &str,
891        passphrase: &str,
892        opts: crate::SharedOptions,
893    ) -> Result<CompactReport> {
894        Self::compact_file_secret(
895            path,
896            passphrase.as_bytes(),
897            SecretKind::Passphrase,
898            0,
899            &opts,
900        )
901    }
902
903    /// [`Mnemo::compact_file_waiting`] for a raw-key database.
904    pub fn compact_file_waiting_with_key(
905        path: &str,
906        key: &[u8; crypto::KEY_LEN],
907        opts: crate::SharedOptions,
908    ) -> Result<CompactReport> {
909        Self::compact_file_secret(path, key, SecretKind::Key, 0, &opts)
910    }
911
912    pub(super) fn compact_file_secret(
913        path: &str,
914        secret: &[u8],
915        kind: SecretKind,
916        format_version: u16,
917        opts: &crate::SharedOptions,
918    ) -> Result<CompactReport> {
919        // RB-007.3: compact the file the path names, through any symlink,
920        // and rename over that file, so a link stays a link and every path
921        // to the brain names the new file.
922        let real = std::fs::canonicalize(path)?;
923        // The one read-write open that takes a v4–v8 file (the v8 sunset).
924        // RB-007.4: through the lock layer, so shared handles' busy reads
925        // can't keep it out, and a shared caller that times out reads
926        // "compact" in the lock-info note.
927        let old = Mnemo::open_exclusive_secret(&real, secret, "compact", opts, true)?;
928        // RB-007.8 item 8: with the exclusive lock held no compaction of
929        // this file is running, so temp files left by dead ones can go.
930        remove_dead_compaction_temps(&real);
931        let dims = old.dimensions;
932        // 12.3 (the keys note, section 1, rule 6): never lower the
933        // parameters, and raise a passphrase file that's below the floor.
934        let kdf = if kind == SecretKind::Passphrase && old.kdf.below_passphrase_floor() {
935            old.kdf.for_passphrase()
936        } else {
937            old.kdf
938        };
939        // 12.3 (the salt rule): the new file keeps the salt, so whatever
940        // found the secret for the old file (a keychain entry) finds it.
941        let salt = old.header.salt;
942        let config = MnemoConfig {
943            dimensions: dims,
944            kdf,
945            // FMT-9f: compaction writes v9 (upgrading a v8 file),
946            // unless `compact_file_to` asked for v8. A v9 file that
947            // keeps float vectors keeps them.
948            format_version,
949            store_float_vectors: old.float_vectors(),
950            ..Default::default()
951        };
952        // v0.14.0 step 1: a new file under a name no other compaction shares.
953        let (tmp, new) = create_temp(&real, "compact", secret, kind, config, Some(salt))?;
954        // Created owner-only; it keeps the old file's mode.
955        if let Err(e) = copy_mode(old.pager.file(), new.pager.file()) {
956            drop(new);
957            let _ = std::fs::remove_file(&tmp);
958            return Err(e);
959        }
960        // `compact_into` releases the old file's lock only after the rename.
961        let result = Self::compact_into(old, new, &real, &tmp, |old, new| old.copy_live_into(new));
962        if result.is_err() {
963            let _ = std::fs::remove_file(&tmp);
964        }
965        result
966    }
967
968    /// Write the compacted copy of `old` to `tmp`, then rename it over
969    /// `path`, all while `old` holds the old file's exclusive lock.
970    ///
971    /// v0.14.0 step 1 (12.4's design note, "Gaps in today's code"): the lock
972    /// used to be released before the rename. A process that opened the
973    /// path in that window locked the old file and wrote to it, and the
974    /// rename then replaced it, losing those writes. Holding the lock
975    /// through the rename and the directory sync means a process either
976    /// waits on the old file's lock (and then finds, by `open_with_lock`'s
977    /// identity check, that the path names the new file) or opens the new
978    /// file.
979    ///
980    /// **Windows and the toolchain.** Renaming over a file another handle
981    /// holds open and locked works on Linux and macOS with every toolchain,
982    /// and on Windows when the engine is built with Rust 1.85 or later,
983    /// whose `std::fs::rename` uses POSIX semantics. Built with 1.75 to 1.84
984    /// (the MSRV is 1.75), Windows refuses it with "Access is denied" (os
985    /// error 5) while the old file is open, so the rename is retried once
986    /// after the old handle is closed, as before v0.14.0. That leaves the
987    /// old window open for those builds; each commit's identity check
988    /// (`ensure_not_replaced`) then turns nearly every write that would have
989    /// been lost into `Replaced`. (Probed on CI, 2026-11-13: 1.75 to 1.84
990    /// refuse, 1.85 to 1.100 succeed; the released binaries are built with
991    /// stable.)
992    fn compact_into<R>(
993        mut old: Mnemo,
994        mut new: Mnemo,
995        path: &Path,
996        tmp: &Path,
997        copy: impl FnOnce(&mut Mnemo, &mut Mnemo) -> Result<R>,
998    ) -> Result<R> {
999        let report = copy(&mut old, &mut new)?;
1000
1001        new.flush()?;
1002        // The new file is closed before the rename: Windows won't rename a
1003        // file this process still has open.
1004        drop(new);
1005
1006        match std::fs::rename(tmp, path) {
1007            Ok(()) => {}
1008            #[cfg(windows)]
1009            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
1010                // A toolchain before 1.85: see above.
1011                drop(old);
1012                std::fs::rename(tmp, path)?;
1013                return Ok(report);
1014            }
1015            Err(e) => return Err(MnemoError::Io(e)),
1016        }
1017        // Make the rename durable before the old file's lock goes.
1018        #[cfg(unix)]
1019        if let Some(parent) = path.parent() {
1020            let parent = if parent.as_os_str().is_empty() {
1021                Path::new(".")
1022            } else {
1023                parent
1024            };
1025            if let Ok(dir) = File::open(parent) {
1026                let _ = dir.sync_all();
1027                crate::bump_fsync();
1028            }
1029        }
1030        // Only now does the old file's lock go.
1031        drop(old);
1032        Ok(report)
1033    }
1034
1035    /// 12.3 step 4 (v0.15): **embed every live memory again with
1036    /// `embedder`** and record its identity, so a file moves to a new model
1037    /// (or a new query convention, or a new width) in one step.
1038    ///
1039    /// It's a compaction with new vectors: it runs under the file's
1040    /// exclusive lock (waiting 10 s for it, like [`Mnemo::compact_file`]),
1041    /// writes a temp file beside the brain with the same salt and KDF
1042    /// parameters, and renames it over the brain while the lock is held. An
1043    /// interrupted run leaves the old file whole (and a temp file the next
1044    /// compaction or reembed removes), so the file never opens with two
1045    /// identities or mixed vectors.
1046    ///
1047    /// - Every live memory is embedded with [`Embedder::embed`] (the
1048    ///   document side), in batches of 64: facts, superseded versions (so
1049    ///   history reads stay consistent), essence items and thread turns.
1050    ///   A manifest and a thread link (`_mnemo.kind = "thread_link"`) keep
1051    ///   their sentinel vector, at the new width, and aren't embedded.
1052    /// - The new identity is recorded in the `_mnemo.embedder` entry and in
1053    ///   the manifest's `metadata.embedder`.
1054    /// - The result cache is copied as compaction copies it; a semantic
1055    ///   entry whose vector has the old width is dropped.
1056    /// - The ANN index is rebuilt if there was one, and the keyword index
1057    ///   with the current tokenizer (TOK-1). Snapshot history is dropped,
1058    ///   as by compaction.
1059    pub fn reembed_file(
1060        path: &str,
1061        passphrase: &str,
1062        embedder: &dyn Embedder,
1063    ) -> Result<ReembedReport> {
1064        Self::reembed_file_secret(
1065            path,
1066            passphrase.as_bytes(),
1067            SecretKind::Passphrase,
1068            embedder,
1069            &crate::SharedOptions::default(),
1070        )
1071    }
1072
1073    /// [`Mnemo::reembed_file`] for a raw-key database.
1074    pub fn reembed_file_with_key(
1075        path: &str,
1076        key: &[u8; crypto::KEY_LEN],
1077        embedder: &dyn Embedder,
1078    ) -> Result<ReembedReport> {
1079        Self::reembed_file_secret(
1080            path,
1081            key,
1082            SecretKind::Key,
1083            embedder,
1084            &crate::SharedOptions::default(),
1085        )
1086    }
1087
1088    /// [`Mnemo::reembed_file`] with the lock layer's options (how long to
1089    /// wait for the lock, a cancel), as [`Mnemo::compact_file_waiting`].
1090    pub fn reembed_file_waiting(
1091        path: &str,
1092        passphrase: &str,
1093        embedder: &dyn Embedder,
1094        opts: crate::SharedOptions,
1095    ) -> Result<ReembedReport> {
1096        Self::reembed_file_secret(
1097            path,
1098            passphrase.as_bytes(),
1099            SecretKind::Passphrase,
1100            embedder,
1101            &opts,
1102        )
1103    }
1104
1105    /// [`Mnemo::reembed_file_waiting`] for a raw-key database.
1106    pub fn reembed_file_waiting_with_key(
1107        path: &str,
1108        key: &[u8; crypto::KEY_LEN],
1109        embedder: &dyn Embedder,
1110        opts: crate::SharedOptions,
1111    ) -> Result<ReembedReport> {
1112        Self::reembed_file_secret(path, key, SecretKind::Key, embedder, &opts)
1113    }
1114
1115    fn reembed_file_secret(
1116        path: &str,
1117        secret: &[u8],
1118        kind: SecretKind,
1119        embedder: &dyn Embedder,
1120        opts: &crate::SharedOptions,
1121    ) -> Result<ReembedReport> {
1122        let to = embedder.identity();
1123        if to.dimensions == 0 {
1124            return Err(MnemoError::Invalid(
1125                "reembed: the embedder's identity has 0 dimensions".into(),
1126            ));
1127        }
1128        let real = std::fs::canonicalize(path)?;
1129        let mut old = Mnemo::open_exclusive_secret(&real, secret, "reembed", opts, true)?;
1130        remove_dead_temps(&real, "reembed");
1131        let from = old.recorded_identity()?;
1132        let kdf = if kind == SecretKind::Passphrase && old.kdf.below_passphrase_floor() {
1133            old.kdf.for_passphrase()
1134        } else {
1135            old.kdf
1136        };
1137        let salt = old.header.salt;
1138        let config = MnemoConfig {
1139            dimensions: to.dimensions,
1140            kdf,
1141            format_version: 0,
1142            store_float_vectors: old.float_vectors(),
1143            ..Default::default()
1144        };
1145        let (tmp, new) = create_temp(&real, "reembed", secret, kind, config, Some(salt))?;
1146        if let Err(e) = copy_mode(old.pager.file(), new.pager.file()) {
1147            drop(new);
1148            let _ = std::fs::remove_file(&tmp);
1149            return Err(e);
1150        }
1151        let result = Self::compact_into(old, new, &real, &tmp, |old, new| {
1152            old.copy_reembedded_into(new, embedder, from.clone(), to.clone())
1153        });
1154        if result.is_err() {
1155            let _ = std::fs::remove_file(&tmp);
1156        }
1157        result
1158    }
1159
1160    /// [`Mnemo::reembed_file`]'s copy: every live memory with a new vector,
1161    /// the new identity, and the cache.
1162    fn copy_reembedded_into(
1163        &mut self,
1164        new: &mut Mnemo,
1165        embedder: &dyn Embedder,
1166        from: Option<embed::EmbedderIdentity>,
1167        to: embed::EmbedderIdentity,
1168    ) -> Result<ReembedReport> {
1169        const BATCH: usize = 64;
1170        new.turn_compress_after = 0;
1171        let want_index = self.has_index();
1172        let now = memory::now_secs();
1173        let dims = to.dimensions;
1174        let mut live: Vec<Memory> = self
1175            .memories()?
1176            .into_iter()
1177            .filter(|m| !m.is_expired(now))
1178            .collect();
1179        let mut manifests = 0;
1180        let mut thread_links = 0;
1181        for m in live.iter_mut() {
1182            if embed::read_identity_from_metadata(&m.metadata).is_some() {
1183                embed::write_identity_into_metadata(&mut m.metadata, &to);
1184            }
1185        }
1186        // R-008.3: a manifest and a thread link carry a sentinel vector, not
1187        // an embedding of their text.
1188        let is_link = |m: &Memory| {
1189            m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str())
1190                == Some(MNEMO_META_KIND_THREAD_LINK)
1191        };
1192        let to_embed: Vec<usize> = (0..live.len())
1193            .filter(|&i| !is_manifest(&live[i]) && !is_link(&live[i]))
1194            .collect();
1195        for chunk in to_embed.chunks(BATCH) {
1196            let texts: Vec<&str> = chunk.iter().map(|&i| live[i].content.as_str()).collect();
1197            let vectors = embedder.embed(&texts)?;
1198            if vectors.len() != texts.len() {
1199                return Err(MnemoError::Invalid(format!(
1200                    "reembed: the embedder returned {} vectors for {} texts",
1201                    vectors.len(),
1202                    texts.len()
1203                )));
1204            }
1205            for (&i, v) in chunk.iter().zip(vectors) {
1206                if v.len() != dims {
1207                    return Err(MnemoError::DimensionMismatch {
1208                        expected: dims,
1209                        got: v.len(),
1210                    });
1211                }
1212                if embed::is_zero_vector(&v) {
1213                    return Err(MnemoError::Invalid(format!(
1214                        "reembed: the embedder returned an all-zero vector for memory {}",
1215                        live[i].id
1216                    )));
1217                }
1218                live[i].vector = v;
1219            }
1220        }
1221        let memories = live.len();
1222        for mut m in live {
1223            if is_manifest(&m) {
1224                m.vector = Memory::scaffold_manifest(dims).vector;
1225                manifests += 1;
1226            } else if is_link(&m) {
1227                m.vector = new.sentinel_vector();
1228                thread_links += 1;
1229            }
1230            new.put_existing(m)?;
1231        }
1232        if want_index && memories > 0 {
1233            new.build_index_with(IndexConfig::default())?;
1234        }
1235        let mut cache_entries = 0;
1236        let mut cache_dropped = 0;
1237        for pos in 0..self.cache_dir.len() {
1238            let (keep, reserved, wrong_width) = {
1239                let e = &self.cache_dir[pos];
1240                (
1241                    !e.deleted && !e.is_expired(now),
1242                    embed::is_reserved_namespace(&e.namespace),
1243                    e.vector.as_ref().is_some_and(|v| v.len() != dims),
1244                )
1245            };
1246            if !keep || (reserved && self.cache_dir[pos].namespace == embed::IDENTITY_NAMESPACE) {
1247                continue;
1248            }
1249            if wrong_width {
1250                cache_dropped += 1;
1251                continue;
1252            }
1253            new.copy_cache_entry_from(self, pos)?;
1254            if !reserved {
1255                cache_entries += 1;
1256            }
1257        }
1258        new.record_identity(&to)?;
1259        Ok(ReembedReport {
1260            memories: memories - manifests - thread_links,
1261            manifests,
1262            thread_links,
1263            cache_entries,
1264            cache_dropped,
1265            from,
1266            to,
1267        })
1268    }
1269
1270    /// Copy one live cache entry from `old` at directory position
1271    /// `pos` into `self` (a freshly-created compaction target).
1272    /// Decrypts the old record body, substitutes the old *directory*'s
1273    /// `accessed_at` + `access_count` (the record body's copies are
1274    /// stale as of v5's directory-only hit path), re-encodes, writes
1275    /// a fresh record run, and pushes a matching directory entry.
1276    ///
1277    /// Caller is expected to have already filtered out tombstoned /
1278    /// expired entries and to call this on a read-write handle.
1279    pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
1280        if self.read_only {
1281            return Err(MnemoError::ReadOnly);
1282        }
1283        // Snapshot the directory fields we need, so the borrow on
1284        // `old.cache_dir` ends before we touch `old.pager`.
1285        let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
1286            let e = &old.cache_dir[pos];
1287            (
1288                e.start_page,
1289                e.page_count,
1290                e.len,
1291                e.accessed_at,
1292                e.access_count,
1293                e.gen,
1294            )
1295        };
1296
1297        // Read + decrypt the old record body.
1298        let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
1299        let mut entry: CacheEntry =
1300            rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
1301
1302        // Overwrite the stale body copies with the directory's live
1303        // values before persisting. Everything else — `created_at`,
1304        // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
1305        // `content_type`, `value`, `vector`, `model` — stays as the
1306        // body already recorded it.
1307        entry.accessed_at = dir_accessed_at;
1308        entry.access_count = dir_access_count;
1309
1310        let bytes =
1311            rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
1312        let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
1313
1314        let dir_entry = CacheDirectoryEntry {
1315            namespace: entry.namespace.clone(),
1316            key_hash: entry.key_hash,
1317            start_page: new_start_page,
1318            page_count: new_page_count,
1319            len: bytes.len() as u32,
1320            deleted: false,
1321            accessed_at: dir_accessed_at,
1322            access_count: dir_access_count,
1323            size_bytes: entry.size_bytes,
1324            ttl_secs: entry.ttl_secs,
1325            created_at: entry.created_at,
1326            vector: entry.vector.clone(),
1327            model: entry.model.clone(),
1328            gen,
1329        };
1330        let new_pos = self.cache_dir.len();
1331        self.cache_idx
1332            .insert(&entry.namespace, entry.key_hash, new_pos);
1333        self.cache_dir.push(dir_entry);
1334        self.dirty_cache = true;
1335        Ok(())
1336    }
1337}
1338
1339/// SEC-2 (RB-001.30): overwrite every occurrence of `needle` in the file
1340/// with zeros, then sync. Rekey uses it for stale copies of the old header's
1341/// key wrap: they're plaintext (page 0 is sealed, not encrypted) and can sit
1342/// in WAL regions that were grown, relocated or freed. Every other page is
1343/// AES-GCM ciphertext, where a 76-byte random match doesn't happen.
1344pub(super) fn scrub_bytes(file: &mut std::fs::File, needle: &[u8]) -> Result<usize> {
1345    if needle.is_empty() {
1346        return Ok(0);
1347    }
1348    let len = file.seek(SeekFrom::End(0))?;
1349    let chunk = 1 << 20;
1350    let overlap = needle.len() - 1;
1351    let mut hits: Vec<u64> = Vec::new();
1352    let mut buf = vec![0u8; chunk + overlap];
1353    let mut pos: u64 = 0;
1354    while pos < len {
1355        let want = (chunk as u64 + overlap as u64).min(len - pos) as usize;
1356        file.seek(SeekFrom::Start(pos))?;
1357        file.read_exact(&mut buf[..want])?;
1358        let mut i = 0;
1359        while i + needle.len() <= want {
1360            if buf[i..i + needle.len()] == *needle {
1361                hits.push(pos + i as u64);
1362                i += needle.len();
1363            } else {
1364                i += 1;
1365            }
1366        }
1367        pos += chunk as u64;
1368    }
1369    hits.dedup();
1370    let zeros = vec![0u8; needle.len()];
1371    for off in &hits {
1372        file.seek(SeekFrom::Start(*off))?;
1373        file.write_all(&zeros)?;
1374    }
1375    if !hits.is_empty() {
1376        file.sync_all()?;
1377        crate::bump_fsync();
1378    }
1379    Ok(hits.len())
1380}
1381
1382/// RB-007.8 item 8: remove the temp files that compactions of `brain` left
1383/// when their process died: in `brain`'s directory, regular files named
1384/// exactly `<brain's name>.compact-<pid>-<n>-<8 hex digits>.tmp` (the
1385/// pattern [`temp_sibling`] makes) whose pid isn't this process and no
1386/// longer runs, and, on Unix, that this user owns: in a shared directory
1387/// another user's file of the same name is left alone. Nothing else is
1388/// touched. Best effort; returns how many went.
1389///
1390/// Call it only with `brain`'s exclusive lock held: a live compaction holds
1391/// that lock for as long as its temp file exists. Off Unix no process
1392/// check is available, so nothing is removed.
1393pub(crate) fn remove_dead_compaction_temps(brain: &Path) -> usize {
1394    remove_dead_temps(brain, "compact")
1395}
1396
1397/// [`remove_dead_compaction_temps`] for the temps of another operation
1398/// (`what`, as [`temp_sibling`] names them): 12.3's `init` uses "init".
1399pub(crate) fn remove_dead_temps(brain: &Path, what: &str) -> usize {
1400    let (Some(dir), Some(name)) = (brain.parent(), brain.file_name()) else {
1401        return 0;
1402    };
1403    let prefix = format!("{}.{what}-", name.to_string_lossy());
1404    let Ok(entries) = std::fs::read_dir(dir) else {
1405        return 0;
1406    };
1407    let mut removed = 0;
1408    for entry in entries.flatten() {
1409        let file_name = entry.file_name();
1410        let Some(pid) = file_name.to_str().and_then(|n| dead_temp_pid(n, &prefix)) else {
1411            continue;
1412        };
1413        if pid == std::process::id() || crate::shared::pid_alive(pid) {
1414            continue;
1415        }
1416        let path = entry.path();
1417        let Ok(meta) = std::fs::symlink_metadata(&path) else {
1418            continue;
1419        };
1420        if !meta.file_type().is_file() || !owned_by_us(&meta) {
1421            continue;
1422        }
1423        if std::fs::remove_file(&path).is_ok() {
1424            removed += 1;
1425        }
1426    }
1427    removed
1428}
1429
1430/// Whether this process's user owns the file (Unix). Elsewhere, true: the
1431/// caller removes nothing off Unix anyway.
1432#[cfg(unix)]
1433fn owned_by_us(meta: &std::fs::Metadata) -> bool {
1434    use std::os::unix::fs::MetadataExt;
1435    #[cfg(any(test, feature = "failpoints"))]
1436    if let Some(uid) = crate::__failpoints::euid_override() {
1437        return meta.uid() == uid;
1438    }
1439    meta.uid() == rustix::process::geteuid().as_raw()
1440}
1441
1442#[cfg(not(unix))]
1443fn owned_by_us(_meta: &std::fs::Metadata) -> bool {
1444    true
1445}
1446
1447/// The pid in a compaction temp name `<prefix><pid>-<n>-<8 hex>.tmp`, if the
1448/// name is exactly that.
1449fn dead_temp_pid(name: &str, prefix: &str) -> Option<u32> {
1450    let rest = name.strip_prefix(prefix)?.strip_suffix(".tmp")?;
1451    let mut parts = rest.split('-');
1452    let (pid, n, nanos) = (parts.next()?, parts.next()?, parts.next()?);
1453    let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
1454    let hex8 = nanos.len() == 8 && nanos.bytes().all(|b| b.is_ascii_hexdigit());
1455    if parts.next().is_some() || !digits(pid) || !digits(n) || !hex8 {
1456        return None;
1457    }
1458    pid.parse().ok()
1459}
1460
1461/// The phrase REKEY-1's one exception carries; `mnemo rekey` and
1462/// [`crate::keys::rekey_stored`] look for it.
1463const EITHER_SECRET: &str = "may open with either secret";
1464
1465/// A new, locked temp file next to `dest` (`Create::New`, so nothing already
1466/// at the name, a symlink included, is ever written through), under a fresh
1467/// name for each attempt while names are taken. RB-006.10.
1468pub(crate) fn create_temp(
1469    dest: &Path,
1470    what: &str,
1471    secret: &[u8],
1472    kind: SecretKind,
1473    config: MnemoConfig,
1474    salt: Option<[u8; crypto::SALT_LEN]>,
1475) -> Result<(PathBuf, Mnemo)> {
1476    let mut attempt = 0;
1477    loop {
1478        let tmp = temp_sibling(dest, what);
1479        match Mnemo::create_secret_new(&tmp, secret, kind, config, salt) {
1480            Ok(new) => return Ok((tmp, new)),
1481            Err(e) if is_name_taken(&e) && attempt + 1 < TEMP_NAME_ATTEMPTS => attempt += 1,
1482            Err(e) => return Err(e),
1483        }
1484    }
1485}