Skip to main content

mnemo_engine/store/
maintenance.rs

1//! Maintenance: export, rekey, verify, stats, and compaction (which also upgrades v8 files to v9).
2
3use super::*;
4
5impl Mnemo {
6    /// Return the KDF (Argon2id) parameters this file currently uses to
7    /// wrap its DEK. Needed by callers that want to [`rekey`] while
8    /// keeping the file's original protection level (e.g. the Python
9    /// binding's `rekey(fast=False)`, whose docstring promises exactly
10    /// that). FIX-1 R-001.5.
11    pub fn kdf_params(&self) -> KdfParams {
12        self.kdf
13    }
14
15    /// Flush any pending writes, then stream the (encrypted) file to
16    /// `dest` atomically: writes to a sibling temp file in `dest`'s
17    /// parent directory, `sync_all`s it, renames onto `dest`, and
18    /// fsyncs the parent directory on Unix so a crash never leaves a
19    /// partial export.
20    ///
21    /// Refuses when `dest` resolves to the file this handle has open
22    /// — that case would otherwise `File::create`-truncate the live
23    /// database to 0 bytes (`fs::copy` on Unix reads *after* the
24    /// `O_TRUNC`, so a naive export-to-self destroys the source).
25    /// Unix: compares `(dev, ino)` of both paths via `MetadataExt`,
26    /// catching symlinks and hard links. Windows: compares
27    /// canonicalized paths; a rename onto an open file also fails on
28    /// Windows because of the mandatory lock the handle holds, so the
29    /// rename step is a second line of defense.
30    ///
31    /// Reads the bytes from the already-open file handle, not by
32    /// `fs::copy`. On Windows that matters: `LockFileEx` locks are
33    /// mandatory, so a second handle opened by `fs::copy` would fail
34    /// while this writer still holds the lock.
35    ///
36    /// FIX-1 R-001.5 + R-002.2 part 3.
37    pub fn export_encrypted(&mut self, dest: impl AsRef<Path>) -> Result<()> {
38        let dest = dest.as_ref();
39
40        // Step 1 — refuse export to the open file itself. We compare
41        // by identity, not string, so symlinks and hard links to
42        // `self.path` are caught too. The check runs before any flush
43        // so a self-targeted export is a pure no-op.
44        if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
45            return Err(MnemoError::Invalid(format!(
46                "export_encrypted refuses to overwrite the open database at {}",
47                dest.display()
48            )));
49        }
50
51        // Step 2 — flush, so on-disk bytes match the live state.
52        if !self.read_only {
53            self.flush()?;
54        }
55
56        // Step 3 — stream from the open handle into a sibling temp.
57        // Using the open handle (instead of a second open on `self.path`)
58        // means a Windows mandatory lock can't block the copy.
59        let parent = dest.parent().ok_or_else(|| {
60            MnemoError::Invalid(format!(
61                "export_encrypted: dest {} has no parent directory",
62                dest.display()
63            ))
64        })?;
65        let tmp = temp_sibling(dest);
66        // Scope the temp handle so it closes before the rename on
67        // Windows (which refuses to rename over an open file).
68        {
69            let src = self.pager.file_mut();
70            src.seek(SeekFrom::Start(0))?;
71            let mut out = OpenOptions::new()
72                .write(true)
73                .create(true)
74                .truncate(true)
75                .open(&tmp)?;
76            let mut buf = vec![0u8; 1 << 20]; // 1 MiB
77            loop {
78                let n = src.read(&mut buf)?;
79                if n == 0 {
80                    break;
81                }
82                out.write_all(&buf[..n])?;
83            }
84            out.sync_all()?;
85            crate::bump_fsync();
86        }
87
88        // Step 4 — atomic rename onto `dest`.
89        if let Err(e) = std::fs::rename(&tmp, dest) {
90            // Best-effort cleanup; propagate the rename error.
91            let _ = std::fs::remove_file(&tmp);
92            return Err(MnemoError::Io(e));
93        }
94
95        // Step 5 — fsync the parent directory on Unix so the rename
96        // itself is durable. On Windows directory syncs aren't
97        // supported; the rename above is atomic enough on NTFS.
98        #[cfg(unix)]
99        {
100            if let Ok(dir) = File::open(parent) {
101                let _ = dir.sync_all();
102                crate::bump_fsync();
103            }
104        }
105        #[cfg(not(unix))]
106        {
107            let _ = parent;
108        }
109
110        Ok(())
111    }
112
113    /// Change the passphrase. Cheap: re-derives the KEK and re-wraps the DEK;
114    /// the encrypted pages are never rewritten.
115    ///
116    /// **This changes the secret that opens this file from now on; anyone who
117    /// had the file and the old secret can still read it and later writes.**
118    /// The data key stays the same, so an earlier copy of the file (or of
119    /// just its header) and the old passphrase still unlock it. The old wrap
120    /// is scrubbed from this file (the previous WAL region is zeroed, and any
121    /// stale copy of the old header's key wrap is overwritten); that's
122    /// hygiene, not revocation. **To revoke, rotate:** rekey, then
123    /// [`Mnemo::compact_file`] (`mnemo rekey --rotate`), which rewrites the
124    /// file under a fresh data key. Rotation can't erase old ciphertext the storage hardware still holds: flash keeps rewritten blocks until it reuses them, and that's out of the engine's hands.
125    pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
126        self.rekey_secret(new_passphrase.as_bytes(), kdf)
127    }
128
129    /// PERF-1 step 7: switch to (or rotate) a raw 256-bit key, recording
130    /// [`KdfParams::raw_key`] in the header. Like [`Mnemo::rekey`], only the
131    /// wrapped DEK changes; pages aren't rewritten, and it doesn't revoke
132    /// the old key (see [`Mnemo::rekey`]).
133    pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
134        self.rekey_secret(new_key, KdfParams::raw_key())
135    }
136
137    pub(super) fn rekey_secret(&mut self, secret: &[u8], kdf: KdfParams) -> Result<()> {
138        if self.read_only {
139            return Err(MnemoError::ReadOnly);
140        }
141        self.flush()?;
142        let new_salt = crypto::random_salt();
143        let new_kek = crypto::derive_kek(secret, &new_salt, kdf)?;
144        let new_nonce = crypto::random_nonce();
145        let wrapped = crypto::wrap_dek(&new_kek, &new_nonce, self.pager.dek())?;
146        if wrapped.len() != WRAPPED_DEK_LEN {
147            return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
148        }
149        let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
150        wrapped_dek.copy_from_slice(&wrapped);
151
152        // SEC-2: the old header's key wrap (salt, DEK nonce, wrapped DEK, as
153        // laid out at header bytes 86..162), to scrub once the new header
154        // is committed.
155        let mut old_wrap =
156            Vec::with_capacity(crypto::SALT_LEN + crypto::NONCE_LEN + WRAPPED_DEK_LEN);
157        old_wrap.extend_from_slice(&self.header.salt);
158        old_wrap.extend_from_slice(&self.header.dek_nonce);
159        old_wrap.extend_from_slice(&self.header.wrapped_dek);
160
161        self.header.salt = new_salt;
162        self.header.dek_nonce = new_nonce;
163        self.header.wrapped_dek = wrapped_dek;
164        self.header.m_cost = kdf.m_cost;
165        self.header.t_cost = kdf.t_cost;
166        self.header.p_cost = kdf.p_cost;
167        self.kdf = kdf;
168
169        // DUR-1 (R-002.1): WAL-log the new page 0 before touching it.
170        // Allocate a fresh WAL region at the tail so that a crash during
171        // the rekey leaves either the old region (old passphrase works)
172        // or the new region (new passphrase works) fully committed —
173        // overwriting the existing region would risk destroying both.
174        let old_wal_start = self.header.wal_start;
175        let new_pages = self.header.wal_pages;
176        let new_start = self.header.next_page;
177        self.header.next_page += new_pages;
178        self.header.wal_start = new_start;
179        self.header.wal_pages = new_pages;
180        self.header.wal_seq += 1;
181        self.relocate_header_through_wal(old_wal_start)?;
182        // SEC-2 (RB-001.30): the old region holds page-0 images with the old
183        // wrap; `relocate_header_through_wal` only zeroed its first frame
184        // header. Zero all of it, then overwrite any other stale copy of
185        // the old wrap in the file (an earlier, grown or relocated region).
186        // Hygiene only: a copy of the file taken before the rekey still
187        // opens with the old secret (see `rekey`).
188        wal::scrub_region(self.pager.file_mut(), old_wal_start, new_pages)?;
189        scrub_bytes(self.pager.file_mut(), &old_wrap)?;
190        // FMT-9 (a): the old region is freed by the next commit (see
191        // `ensure_wal_capacity`).
192        self.release_pages(old_wal_start, new_pages);
193        Ok(())
194    }
195
196    /// SEC-2 (RB-001.30): write a copy of this database at `dest` under a
197    /// **fresh data key**, protected by `passphrase` through `kdf`. It goes
198    /// through the compaction path (live memories, the result cache and
199    /// the index, no history), so the copy shares no key material with
200    /// this file: neither this file's passphrase nor its data key opens
201    /// it, and its passphrase opens nothing here. This file is flushed
202    /// first (unless read-only) and is otherwise unchanged; `dest` must not
203    /// exist. The copy is v9.
204    pub fn export_rekeyed(
205        &mut self,
206        dest: impl AsRef<Path>,
207        passphrase: &str,
208        kdf: KdfParams,
209    ) -> Result<CompactReport> {
210        self.export_rekeyed_secret(dest.as_ref(), passphrase.as_bytes(), kdf)
211    }
212
213    /// [`Mnemo::export_rekeyed`] protected by a raw 256-bit key (no KDF).
214    pub fn export_rekeyed_with_key(
215        &mut self,
216        dest: impl AsRef<Path>,
217        key: &[u8; crypto::KEY_LEN],
218    ) -> Result<CompactReport> {
219        self.export_rekeyed_secret(dest.as_ref(), key, KdfParams::raw_key())
220    }
221
222    pub(super) fn export_rekeyed_secret(
223        &mut self,
224        dest: &Path,
225        secret: &[u8],
226        kdf: KdfParams,
227    ) -> Result<CompactReport> {
228        if paths_refer_to_same_file(&self.path, dest).unwrap_or(false) {
229            return Err(MnemoError::Invalid(format!(
230                "export_rekeyed refuses to overwrite the open database at {}",
231                dest.display()
232            )));
233        }
234        if dest.exists() {
235            return Err(MnemoError::Invalid(format!(
236                "{} already exists",
237                dest.display()
238            )));
239        }
240        if !self.read_only {
241            self.flush()?;
242        }
243        let mut name = dest.file_name().unwrap_or_default().to_os_string();
244        name.push(".export-tmp");
245        let tmp = dest.with_file_name(name);
246        let _ = std::fs::remove_file(&tmp);
247        let result = (|| {
248            let mut new = Mnemo::create_secret(
249                &tmp,
250                secret,
251                MnemoConfig {
252                    dimensions: self.dimensions,
253                    kdf,
254                    store_float_vectors: self.float_vectors(),
255                    ..Default::default()
256                },
257            )?;
258            let report = self.copy_live_into(&mut new)?;
259            new.flush()?;
260            drop(new);
261            std::fs::rename(&tmp, dest)?;
262            Ok(report)
263        })();
264        if result.is_err() {
265            let _ = std::fs::remove_file(&tmp);
266        }
267        result
268    }
269
270    /// The compaction copy: every live, unexpired memory and cache entry of
271    /// `self` into `new` (a freshly created file), and the index if `self`
272    /// has one. Counts as [`CompactReport`].
273    pub(super) fn copy_live_into(&mut self, new: &mut Mnemo) -> Result<CompactReport> {
274        // FMT-9e: compaction rewrites everything, so it compresses every
275        // thread turn, recent or not.
276        new.turn_compress_after = 0;
277        // ANN-1.1: compaction is "re-tune for the current size" by
278        // default. Pass IndexConfig::default() so partitions,
279        // subspaces, n_probe and n_rerank are all re-derived from the
280        // compacted vector count. Previously we froze the pre-compact
281        // (n_probe, n_rerank), which left the new index on stale
282        // numbers for the smaller post-compact corpus.
283        let want_index = self.has_index();
284        let now = memory::now_secs();
285        let all = self.memories()?;
286        let before = all.len();
287        let mut after = 0;
288        for m in all {
289            if m.is_expired(now) {
290                continue;
291            }
292            // The engine's own copy: `_mnemo.*` keys come through as they are.
293            new.put(m)?;
294            after += 1;
295        }
296        if want_index && after > 0 {
297            new.build_index_with(IndexConfig::default())?;
298        }
299
300        // Count + copy cache entries. We walk `self.cache_dir` by index
301        // so each hop reads the directory's live `accessed_at` /
302        // `access_count` directly rather than going through
303        // `cache_get` (which would also treat read-only semantics,
304        // tombstones, etc. — we want the raw, authoritative values).
305        let mut cache_before = 0usize;
306        let mut cache_after = 0usize;
307        let positions: Vec<usize> = (0..self.cache_dir.len()).collect();
308        for pos in positions {
309            let keep = {
310                let e = &self.cache_dir[pos];
311                !e.deleted && !e.is_expired(now)
312            };
313            if keep {
314                cache_before += 1;
315                new.copy_cache_entry_from(self, pos)?;
316                cache_after += 1;
317            }
318        }
319        Ok(CompactReport {
320            before,
321            after,
322            cache_before,
323            cache_after,
324        })
325    }
326
327    /// Decrypt and validate every live record. Returns the count verified
328    /// across memories **and** cache entries (FIX-1 R-001.1: now that the
329    /// cache survives compaction, `verify()` has to walk it too — the
330    /// pre-FIX-1 implementation only checked `self.catalog`, so a
331    /// corrupted cache record went unnoticed).
332    pub fn verify(&mut self) -> Result<usize> {
333        let entries: Vec<CatalogEntry> = self
334            .catalog
335            .iter()
336            .filter(|e| !e.deleted)
337            .cloned()
338            .collect();
339        let mut n = entries.len();
340        for e in &entries {
341            let bytes = self.read_record(e)?;
342            let _m: Memory = self.decode_memory(&bytes)?;
343            // FMT-9b: and the row's vector column entry.
344            if e.v9.is_some() {
345                let (h, _) = self.column_entry(e)?;
346                if h.len() != self.dimensions {
347                    return Err(MnemoError::Invalid(
348                        "vector entry has the wrong width".into(),
349                    ));
350                }
351            }
352        }
353
354        // Also decode every live cache entry. Tombstoned entries are
355        // skipped — their pages are orphan ciphertext awaiting
356        // `compact_file`, same as deleted memories. Expired entries
357        // are *still* on disk until compaction, so we verify them too.
358        let cache_positions: Vec<(u64, u32, u32, u64)> = self
359            .cache_dir
360            .iter()
361            .filter(|e| !e.deleted)
362            .map(|e| (e.start_page, e.page_count, e.len, e.gen))
363            .collect();
364        for (start_page, page_count, len, gen) in cache_positions {
365            let buf = self.read_record_run(start_page, page_count, len, gen)?;
366            let _c: CacheEntry = rmp_serde::from_slice(&buf)
367                .map_err(|err| MnemoError::Serialize(err.to_string()))?;
368            n += 1;
369        }
370        // FMT-9 (a): no free run may overlap a page the committed state
371        // references (records, cache entries, control runs, the WAL).
372        if self.is_v9() {
373            self.check_free_list_disjoint()?;
374        }
375        Ok(n)
376    }
377
378    /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
379    /// page the current state references.
380    pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
381        let h = &self.header;
382        let mut live: Vec<(u64, u64, &str)> = vec![
383            (h.wal_start, h.wal_pages, "WAL region"),
384            (h.catalog_start, h.catalog_pages, "catalog run"),
385            (h.index_start, h.index_pages, "index run"),
386            (h.manifest_start, h.manifest_pages, "manifest run"),
387            (h.cache_start, h.cache_pages, "cache directory run"),
388            (h.free.start, h.free.pages, "free-list run"),
389            (h.keys.start, h.keys.pages, "key-slot run"),
390        ];
391        live.extend(
392            self.catalog
393                .iter()
394                .filter(|e| !e.deleted)
395                .map(|e| (e.start_page, e.page_count as u64, "record")),
396        );
397        live.extend(
398            self.cache_dir
399                .iter()
400                .filter(|e| !e.deleted)
401                .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
402        );
403        live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
404        live.extend(
405            self.delta_chain
406                .iter()
407                .map(|r| (r.start, r.pages, "catalog delta run")),
408        );
409        live.extend(
410            self.index_chain
411                .iter()
412                .map(|r| (r.start, r.pages, "index delta run")),
413        );
414        live.push((
415            self.header.bm25.start,
416            self.header.bm25.pages,
417            "BM25 manifest",
418        ));
419        live.extend(
420            self.bm25
421                .manifest
422                .segments
423                .iter()
424                .map(|t| (t.0, t.1, "BM25 segment")),
425        );
426        for (p, c, what) in live {
427            if c == 0 {
428                continue;
429            }
430            if self.free.overlaps(p, c) {
431                return Err(MnemoError::Invalid(format!(
432                    "free list overlaps a live {what} at page {p} (+{c})"
433                )));
434            }
435            if self
436                .pending_free
437                .iter()
438                .any(|&(q, n)| q < p + c && p < q + n)
439            {
440                return Err(MnemoError::Invalid(format!(
441                    "a pending free overlaps a live {what} at page {p} (+{c})"
442                )));
443            }
444        }
445        Ok(())
446    }
447
448    /// The statistics that need no record decrypts and no index load
449    /// (v0.12.2, RB-002.3): counts, sizes, the format, whether an index
450    /// exists, the recall mode and the bytes the vector column needs. The
451    /// first [`Mnemo::stats`] on a handle decrypts every record (for its
452    /// agent list) and loads a persisted index; this is what a phone app
453    /// polling the recall mode should call.
454    pub fn stats_summary(&self) -> StatsSummary {
455        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
456        let v9 = self.is_v9();
457        let column = if v9 {
458            (self.scored_rows() * crate::veccol::entry_len(self.dimensions)) as u64
459        } else {
460            0
461        };
462        let recall_mode = if self.has_index() {
463            RecallMode::Indexed
464        } else if v9 && column <= self.vector_cache_budget as u64 {
465            RecallMode::ExactResident
466        } else {
467            RecallMode::ExactPaged
468        };
469        StatsSummary {
470            memories: self.len(),
471            deleted,
472            dimensions: self.dimensions,
473            file_bytes: self.header.next_page * PAGE_SIZE as u64,
474            format_version: self.header.version,
475            wal_pages: self.header.wal_pages,
476            has_index: self.has_index(),
477            recall_mode,
478            vector_column_bytes: column,
479        }
480    }
481
482    /// Summary statistics for the open database. The first call on a
483    /// handle decrypts every record (to list the agents) and loads a
484    /// persisted index; [`Mnemo::stats_summary`] does neither.
485    pub fn stats(&mut self) -> Result<Stats> {
486        let deleted = self.catalog.iter().filter(|e| e.deleted).count();
487        // FIX-1 R-001.8 part 2: build the agent set lazily on first
488        // call per handle, then maintain in `put` / invalidate in
489        // `delete`. Pre-FIX-1 every `stats()` call decrypted every
490        // live memory (O(N) AES-GCM decrypts just to list a usually-
491        // tiny set of distinct agent IDs). On a 1M-memory database
492        // this was in the multi-second range on hardware AES.
493        if self.agent_set.is_none() {
494            let built: std::collections::BTreeSet<String> =
495                self.memories()?.into_iter().map(|m| m.agent_id).collect();
496            self.agent_set = Some(built);
497        }
498        let agents: Vec<String> = self
499            .agent_set
500            .as_ref()
501            .expect("agent_set just filled above")
502            .iter()
503            .cloned()
504            .collect();
505        let file_bytes = self.header.next_page * PAGE_SIZE as u64;
506        let recall_mode = self.recall_mode()?;
507        Ok(Stats {
508            memories: self.len(),
509            deleted,
510            dimensions: self.dimensions,
511            file_bytes,
512            agents,
513            encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
514            created_at: self.header.created_at,
515            index: {
516                self.ensure_ann()?;
517                self.ann.as_ref().map(|a| a.info())
518            },
519            wal_pages: self.header.wal_pages,
520            fsyncs_last_flush: self.fsyncs_last_flush,
521            format_version: self.header.version,
522            recall_mode,
523        })
524    }
525
526    /// Rewrite the file, dropping tombstoned and expired memories and
527    /// reclaiming stale pages left by updates. Done out-of-place via a temp
528    /// file and an atomic rename.
529    ///
530    /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
531    /// compaction. Every live, non-expired directory entry is copied
532    /// into the new file verbatim — `created_at`, `ttl_secs`,
533    /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
534    /// `vector` and `model` come from the record body; `accessed_at`
535    /// and `access_count` come from the *directory* (the record body
536    /// only holds the insert-time snapshot — the directory is the
537    /// source of truth for the live counts, as of v5's recall trick).
538    /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
539    /// compaction kept only the memory catalog and silently emptied
540    /// the cache; the Planner's interim README caveat (c417d2e) called
541    /// that out — this PR removes the surprise.
542    pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
543        Self::compact_file_secret(path, passphrase.as_bytes(), 0)
544    }
545
546    /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
547    pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
548        Self::compact_file_secret(path, key, 0)
549    }
550
551    /// FMT-9f: [`Mnemo::compact_file`] into an explicit format: `9` (what
552    /// `compact_file` does) or `8`, which keeps a v8 file readable by
553    /// v0.10 and earlier. The v8 target is kept for one release.
554    pub fn compact_file_to(
555        path: &str,
556        passphrase: &str,
557        format_version: u16,
558    ) -> Result<CompactReport> {
559        if format_version != VERSION && format_version != VERSION_V9 {
560            return Err(MnemoError::Invalid(format!(
561                "compact target format {format_version} isn't supported (use 8 or 9)"
562            )));
563        }
564        Self::compact_file_secret(path, passphrase.as_bytes(), format_version)
565    }
566
567    pub(super) fn compact_file_secret(
568        path: &str,
569        secret: &[u8],
570        format_version: u16,
571    ) -> Result<CompactReport> {
572        let mut old = Mnemo::open_secret(path, secret)?;
573        let dims = old.dimensions;
574        let kdf = old.kdf;
575        let tmp = format!("{path}.compact-tmp");
576
577        let mut new = Mnemo::create_secret(
578            &tmp,
579            secret,
580            MnemoConfig {
581                dimensions: dims,
582                kdf,
583                // FMT-9f: compaction writes v9 (upgrading a v8 file),
584                // unless `compact_file_to` asked for v8. A v9 file that
585                // keeps float vectors keeps them.
586                format_version,
587                store_float_vectors: old.float_vectors(),
588                ..Default::default()
589            },
590        )?;
591        let report = old.copy_live_into(&mut new)?;
592
593        new.flush()?;
594        drop(new);
595        drop(old);
596
597        std::fs::rename(&tmp, path)?;
598        Ok(report)
599    }
600
601    /// Copy one live cache entry from `old` at directory position
602    /// `pos` into `self` (a freshly-created compaction target).
603    /// Decrypts the old record body, substitutes the old *directory*'s
604    /// `accessed_at` + `access_count` (the record body's copies are
605    /// stale as of v5's directory-only hit path), re-encodes, writes
606    /// a fresh record run, and pushes a matching directory entry.
607    ///
608    /// Caller is expected to have already filtered out tombstoned /
609    /// expired entries and to call this on a read-write handle.
610    pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
611        if self.read_only {
612            return Err(MnemoError::ReadOnly);
613        }
614        // Snapshot the directory fields we need, so the borrow on
615        // `old.cache_dir` ends before we touch `old.pager`.
616        let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
617            let e = &old.cache_dir[pos];
618            (
619                e.start_page,
620                e.page_count,
621                e.len,
622                e.accessed_at,
623                e.access_count,
624                e.gen,
625            )
626        };
627
628        // Read + decrypt the old record body.
629        let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
630        let mut entry: CacheEntry =
631            rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
632
633        // Overwrite the stale body copies with the directory's live
634        // values before persisting. Everything else — `created_at`,
635        // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
636        // `content_type`, `value`, `vector`, `model` — stays as the
637        // body already recorded it.
638        entry.accessed_at = dir_accessed_at;
639        entry.access_count = dir_access_count;
640
641        let bytes =
642            rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
643        let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
644
645        let dir_entry = CacheDirectoryEntry {
646            namespace: entry.namespace.clone(),
647            key_hash: entry.key_hash,
648            start_page: new_start_page,
649            page_count: new_page_count,
650            len: bytes.len() as u32,
651            deleted: false,
652            accessed_at: dir_accessed_at,
653            access_count: dir_access_count,
654            size_bytes: entry.size_bytes,
655            ttl_secs: entry.ttl_secs,
656            created_at: entry.created_at,
657            vector: entry.vector.clone(),
658            model: entry.model.clone(),
659            gen,
660        };
661        let new_pos = self.cache_dir.len();
662        self.cache_idx
663            .insert(&entry.namespace, entry.key_hash, new_pos);
664        self.cache_dir.push(dir_entry);
665        self.dirty_cache = true;
666        Ok(())
667    }
668}
669
670/// SEC-2 (RB-001.30): overwrite every occurrence of `needle` in the file
671/// with zeros, then sync. Rekey uses it for stale copies of the old header's
672/// key wrap: they're plaintext (page 0 is sealed, not encrypted) and can sit
673/// in WAL regions that were grown, relocated or freed. Every other page is
674/// AES-GCM ciphertext, where a 76-byte random match doesn't happen.
675pub(super) fn scrub_bytes(file: &mut std::fs::File, needle: &[u8]) -> Result<usize> {
676    if needle.is_empty() {
677        return Ok(0);
678    }
679    let len = file.seek(SeekFrom::End(0))?;
680    let chunk = 1 << 20;
681    let overlap = needle.len() - 1;
682    let mut hits: Vec<u64> = Vec::new();
683    let mut buf = vec![0u8; chunk + overlap];
684    let mut pos: u64 = 0;
685    while pos < len {
686        let want = (chunk as u64 + overlap as u64).min(len - pos) as usize;
687        file.seek(SeekFrom::Start(pos))?;
688        file.read_exact(&mut buf[..want])?;
689        let mut i = 0;
690        while i + needle.len() <= want {
691            if buf[i..i + needle.len()] == *needle {
692                hits.push(pos + i as u64);
693                i += needle.len();
694            } else {
695                i += 1;
696            }
697        }
698        pos += chunk as u64;
699    }
700    hits.dedup();
701    let zeros = vec![0u8; needle.len()];
702    for off in &hits {
703        file.seek(SeekFrom::Start(*off))?;
704        file.write_all(&zeros)?;
705    }
706    if !hits.is_empty() {
707        file.sync_all()?;
708        crate::bump_fsync();
709    }
710    Ok(hits.len())
711}