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 /// FMT-9 (a): fail if the free list (or a pending free) overlaps any
624 /// page the current state references.
625 pub(super) fn check_free_list_disjoint(&self) -> Result<()> {
626 let h = &self.header;
627 let mut live: Vec<(u64, u64, &str)> = vec![
628 (h.wal_start, h.wal_pages, "WAL region"),
629 (h.catalog_start, h.catalog_pages, "catalog run"),
630 (h.index_start, h.index_pages, "index run"),
631 (h.manifest_start, h.manifest_pages, "manifest run"),
632 (h.cache_start, h.cache_pages, "cache directory run"),
633 (h.free.start, h.free.pages, "free-list run"),
634 (h.keys.start, h.keys.pages, "key-slot run"),
635 ];
636 live.extend(
637 self.catalog
638 .iter()
639 .filter(|e| !e.deleted)
640 .map(|e| (e.start_page, e.page_count as u64, "record")),
641 );
642 live.extend(
643 self.cache_dir
644 .iter()
645 .filter(|e| !e.deleted)
646 .map(|e| (e.start_page, e.page_count as u64, "cache entry")),
647 );
648 live.extend(self.col.page_rows.keys().map(|&p| (p, 1, "vector page")));
649 live.extend(
650 self.delta_chain
651 .iter()
652 .map(|r| (r.start, r.pages, "catalog delta run")),
653 );
654 live.extend(
655 self.index_chain
656 .iter()
657 .map(|r| (r.start, r.pages, "index delta run")),
658 );
659 live.push((
660 self.header.bm25.start,
661 self.header.bm25.pages,
662 "BM25 manifest",
663 ));
664 live.extend(
665 self.bm25
666 .manifest
667 .segments
668 .iter()
669 .map(|t| (t.0, t.1, "BM25 segment")),
670 );
671 for (p, c, what) in live {
672 if c == 0 {
673 continue;
674 }
675 if self.free.overlaps(p, c) {
676 return Err(MnemoError::Invalid(format!(
677 "free list overlaps a live {what} at page {p} (+{c})"
678 )));
679 }
680 if self
681 .pending_free
682 .iter()
683 .any(|&(q, n)| q < p + c && p < q + n)
684 {
685 return Err(MnemoError::Invalid(format!(
686 "a pending free overlaps a live {what} at page {p} (+{c})"
687 )));
688 }
689 }
690 Ok(())
691 }
692
693 /// The statistics that need no record decrypts and no index load
694 /// (v0.12.2, RB-002.3): counts, sizes, the format, whether an index
695 /// exists, the recall mode and the bytes the vector column needs. The
696 /// first [`Mnemo::stats`] on a handle decrypts every record (for its
697 /// agent list) and loads a persisted index; this is what a phone app
698 /// polling the recall mode should call.
699 pub fn stats_summary(&self) -> StatsSummary {
700 let deleted = self.catalog.iter().filter(|e| e.deleted).count();
701 let v9 = self.is_v9();
702 let column = if v9 {
703 (self.scored_rows() * crate::veccol::entry_len(self.dimensions)) as u64
704 } else {
705 0
706 };
707 let recall_mode = if self.has_index() {
708 RecallMode::Indexed
709 } else if v9 && column <= self.vector_cache_budget as u64 {
710 RecallMode::ExactResident
711 } else {
712 RecallMode::ExactPaged
713 };
714 let rp = self.restore_points();
715 StatsSummary {
716 memories: self.len(),
717 deleted,
718 dimensions: self.dimensions,
719 file_bytes: self.header.next_page * PAGE_SIZE as u64,
720 format_version: self.header.version,
721 wal_pages: self.header.wal_pages,
722 has_index: self.has_index(),
723 recall_mode,
724 vector_column_bytes: column,
725 snapshots_retained: rp.retained,
726 oldest_restorable_at: rp.oldest_at,
727 snapshot_pinned_bytes: rp.pinned_bytes,
728 }
729 }
730
731 /// Summary statistics for the open database. The first call on a
732 /// handle decrypts every record (to list the agents) and loads a
733 /// persisted index; [`Mnemo::stats_summary`] does neither.
734 pub fn stats(&mut self) -> Result<Stats> {
735 let deleted = self.catalog.iter().filter(|e| e.deleted).count();
736 // FIX-1 R-001.8 part 2: build the agent set lazily on first
737 // call per handle, then maintain in `put` / invalidate in
738 // `delete`. Pre-FIX-1 every `stats()` call decrypted every
739 // live memory (O(N) AES-GCM decrypts just to list a usually-
740 // tiny set of distinct agent IDs). On a 1M-memory database
741 // this was in the multi-second range on hardware AES.
742 if self.agent_set.is_none() {
743 let built: std::collections::BTreeSet<String> =
744 self.memories()?.into_iter().map(|m| m.agent_id).collect();
745 self.agent_set = Some(built);
746 }
747 let agents: Vec<String> = self
748 .agent_set
749 .as_ref()
750 .expect("agent_set just filled above")
751 .iter()
752 .cloned()
753 .collect();
754 let file_bytes = self.header.next_page * PAGE_SIZE as u64;
755 let recall_mode = self.recall_mode()?;
756 let rp = self.restore_points();
757 Ok(Stats {
758 memories: self.len(),
759 deleted,
760 dimensions: self.dimensions,
761 file_bytes,
762 agents,
763 encrypted: self.header.flags & FLAG_ENCRYPTED != 0,
764 created_at: self.header.created_at,
765 index: {
766 self.ensure_ann()?;
767 self.ann.as_ref().map(|a| a.info())
768 },
769 wal_pages: self.header.wal_pages,
770 fsyncs_last_flush: self.fsyncs_last_flush,
771 format_version: self.header.version,
772 recall_mode,
773 snapshots_retained: rp.retained,
774 oldest_restorable_at: rp.oldest_at,
775 snapshot_pinned_bytes: rp.pinned_bytes,
776 keyword_tokenizer: self.keyword_tokenizer()?,
777 })
778 }
779
780 /// Rewrite the file, dropping tombstoned and expired memories and
781 /// reclaiming stale pages left by updates. Done out-of-place via a temp
782 /// file and an atomic rename.
783 ///
784 /// FIX-1 R-001.1 + R-002.2 part 2: the result cache now survives
785 /// compaction. Every live, non-expired directory entry is copied
786 /// into the new file verbatim — `created_at`, `ttl_secs`,
787 /// `cost_hint_ms`, `key_preview`, `size_bytes`, `content_type`,
788 /// `vector` and `model` come from the record body; `accessed_at`
789 /// and `access_count` come from the *directory* (the record body
790 /// only holds the insert-time snapshot — the directory is the
791 /// source of truth for the live counts, as of v5's recall trick).
792 /// Tombstoned and TTL-expired entries are dropped. Pre-FIX-1
793 /// compaction kept only the memory catalog and silently emptied
794 /// the cache; the Planner's interim README caveat (c417d2e) called
795 /// that out — this PR removes the surprise.
796 ///
797 /// The output is always v9, so this is also how a v4–v8 file is
798 /// converted: the only read-write open that accepts one (the v8
799 /// sunset, v0.13). It keeps every live memory.
800 pub fn compact_file(path: &str, passphrase: &str) -> Result<CompactReport> {
801 Self::compact_file_secret(
802 path,
803 passphrase.as_bytes(),
804 SecretKind::Passphrase,
805 0,
806 &crate::SharedOptions::default(),
807 )
808 }
809
810 /// PERF-1 step 7: [`Mnemo::compact_file`] for a raw-key database.
811 pub fn compact_file_with_key(path: &str, key: &[u8; crypto::KEY_LEN]) -> Result<CompactReport> {
812 Self::compact_file_secret(
813 path,
814 key,
815 SecretKind::Key,
816 0,
817 &crate::SharedOptions::default(),
818 )
819 }
820
821 /// [`Mnemo::compact_file`] with the lock layer's options: how long to
822 /// wait for the file's lock (`opts.deadline`; `compact_file` waits 10 s),
823 /// a cancel, and `allow_network_fs`. `mnemo compact --wait` uses it.
824 pub fn compact_file_waiting(
825 path: &str,
826 passphrase: &str,
827 opts: crate::SharedOptions,
828 ) -> Result<CompactReport> {
829 Self::compact_file_secret(
830 path,
831 passphrase.as_bytes(),
832 SecretKind::Passphrase,
833 0,
834 &opts,
835 )
836 }
837
838 /// [`Mnemo::compact_file_waiting`] for a raw-key database.
839 pub fn compact_file_waiting_with_key(
840 path: &str,
841 key: &[u8; crypto::KEY_LEN],
842 opts: crate::SharedOptions,
843 ) -> Result<CompactReport> {
844 Self::compact_file_secret(path, key, SecretKind::Key, 0, &opts)
845 }
846
847 pub(super) fn compact_file_secret(
848 path: &str,
849 secret: &[u8],
850 kind: SecretKind,
851 format_version: u16,
852 opts: &crate::SharedOptions,
853 ) -> Result<CompactReport> {
854 // RB-007.3: compact the file the path names, through any symlink,
855 // and rename over that file, so a link stays a link and every path
856 // to the brain names the new file.
857 let real = std::fs::canonicalize(path)?;
858 // The one read-write open that takes a v4–v8 file (the v8 sunset).
859 // RB-007.4: through the lock layer, so shared handles' busy reads
860 // can't keep it out, and a shared caller that times out reads
861 // "compact" in the lock-info note.
862 let old = Mnemo::open_exclusive_secret(&real, secret, "compact", opts, true)?;
863 // RB-007.8 item 8: with the exclusive lock held no compaction of
864 // this file is running, so temp files left by dead ones can go.
865 remove_dead_compaction_temps(&real);
866 let dims = old.dimensions;
867 // 12.3 (the keys note, section 1, rule 6): never lower the
868 // parameters, and raise a passphrase file that's below the floor.
869 let kdf = if kind == SecretKind::Passphrase && old.kdf.below_passphrase_floor() {
870 old.kdf.for_passphrase()
871 } else {
872 old.kdf
873 };
874 // 12.3 (the salt rule): the new file keeps the salt, so whatever
875 // found the secret for the old file (a keychain entry) finds it.
876 let salt = old.header.salt;
877 let config = MnemoConfig {
878 dimensions: dims,
879 kdf,
880 // FMT-9f: compaction writes v9 (upgrading a v8 file),
881 // unless `compact_file_to` asked for v8. A v9 file that
882 // keeps float vectors keeps them.
883 format_version,
884 store_float_vectors: old.float_vectors(),
885 ..Default::default()
886 };
887 // v0.14.0 step 1: a new file under a name no other compaction shares.
888 let (tmp, new) = create_temp(&real, "compact", secret, kind, config, Some(salt))?;
889 // Created owner-only; it keeps the old file's mode.
890 if let Err(e) = copy_mode(old.pager.file(), new.pager.file()) {
891 drop(new);
892 let _ = std::fs::remove_file(&tmp);
893 return Err(e);
894 }
895 // `compact_into` releases the old file's lock only after the rename.
896 let result = Self::compact_into(old, new, &real, &tmp, |old, new| old.copy_live_into(new));
897 if result.is_err() {
898 let _ = std::fs::remove_file(&tmp);
899 }
900 result
901 }
902
903 /// Write the compacted copy of `old` to `tmp`, then rename it over
904 /// `path`, all while `old` holds the old file's exclusive lock.
905 ///
906 /// v0.14.0 step 1 (12.4's design note, "Gaps in today's code"): the lock
907 /// used to be released before the rename. A process that opened the
908 /// path in that window locked the old file and wrote to it, and the
909 /// rename then replaced it, losing those writes. Holding the lock
910 /// through the rename and the directory sync means a process either
911 /// waits on the old file's lock (and then finds, by `open_with_lock`'s
912 /// identity check, that the path names the new file) or opens the new
913 /// file.
914 ///
915 /// **Windows and the toolchain.** Renaming over a file another handle
916 /// holds open and locked works on Linux and macOS with every toolchain,
917 /// and on Windows when the engine is built with Rust 1.85 or later,
918 /// whose `std::fs::rename` uses POSIX semantics. Built with 1.75 to 1.84
919 /// (the MSRV is 1.75), Windows refuses it with "Access is denied" (os
920 /// error 5) while the old file is open, so the rename is retried once
921 /// after the old handle is closed, as before v0.14.0. That leaves the
922 /// old window open for those builds; each commit's identity check
923 /// (`ensure_not_replaced`) then turns nearly every write that would have
924 /// been lost into `Replaced`. (Probed on CI, 2026-11-13: 1.75 to 1.84
925 /// refuse, 1.85 to 1.100 succeed; the released binaries are built with
926 /// stable.)
927 fn compact_into<R>(
928 mut old: Mnemo,
929 mut new: Mnemo,
930 path: &Path,
931 tmp: &Path,
932 copy: impl FnOnce(&mut Mnemo, &mut Mnemo) -> Result<R>,
933 ) -> Result<R> {
934 let report = copy(&mut old, &mut new)?;
935
936 new.flush()?;
937 // The new file is closed before the rename: Windows won't rename a
938 // file this process still has open.
939 drop(new);
940
941 match std::fs::rename(tmp, path) {
942 Ok(()) => {}
943 #[cfg(windows)]
944 Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
945 // A toolchain before 1.85: see above.
946 drop(old);
947 std::fs::rename(tmp, path)?;
948 return Ok(report);
949 }
950 Err(e) => return Err(MnemoError::Io(e)),
951 }
952 // Make the rename durable before the old file's lock goes.
953 #[cfg(unix)]
954 if let Some(parent) = path.parent() {
955 let parent = if parent.as_os_str().is_empty() {
956 Path::new(".")
957 } else {
958 parent
959 };
960 if let Ok(dir) = File::open(parent) {
961 let _ = dir.sync_all();
962 crate::bump_fsync();
963 }
964 }
965 // Only now does the old file's lock go.
966 drop(old);
967 Ok(report)
968 }
969
970 /// 12.3 step 4 (v0.15): **embed every live memory again with
971 /// `embedder`** and record its identity, so a file moves to a new model
972 /// (or a new query convention, or a new width) in one step.
973 ///
974 /// It's a compaction with new vectors: it runs under the file's
975 /// exclusive lock (waiting 10 s for it, like [`Mnemo::compact_file`]),
976 /// writes a temp file beside the brain with the same salt and KDF
977 /// parameters, and renames it over the brain while the lock is held. An
978 /// interrupted run leaves the old file whole (and a temp file the next
979 /// compaction or reembed removes), so the file never opens with two
980 /// identities or mixed vectors.
981 ///
982 /// - Every live memory is embedded with [`Embedder::embed`] (the
983 /// document side), in batches of 64: facts, superseded versions (so
984 /// history reads stay consistent), essence items and thread turns.
985 /// A manifest and a thread link (`_mnemo.kind = "thread_link"`) keep
986 /// their sentinel vector, at the new width, and aren't embedded.
987 /// - The new identity is recorded in the `_mnemo.embedder` entry and in
988 /// the manifest's `metadata.embedder`.
989 /// - The result cache is copied as compaction copies it; a semantic
990 /// entry whose vector has the old width is dropped.
991 /// - The ANN index is rebuilt if there was one, and the keyword index
992 /// with the current tokenizer (TOK-1). Snapshot history is dropped,
993 /// as by compaction.
994 pub fn reembed_file(
995 path: &str,
996 passphrase: &str,
997 embedder: &dyn Embedder,
998 ) -> Result<ReembedReport> {
999 Self::reembed_file_secret(
1000 path,
1001 passphrase.as_bytes(),
1002 SecretKind::Passphrase,
1003 embedder,
1004 &crate::SharedOptions::default(),
1005 )
1006 }
1007
1008 /// [`Mnemo::reembed_file`] for a raw-key database.
1009 pub fn reembed_file_with_key(
1010 path: &str,
1011 key: &[u8; crypto::KEY_LEN],
1012 embedder: &dyn Embedder,
1013 ) -> Result<ReembedReport> {
1014 Self::reembed_file_secret(
1015 path,
1016 key,
1017 SecretKind::Key,
1018 embedder,
1019 &crate::SharedOptions::default(),
1020 )
1021 }
1022
1023 /// [`Mnemo::reembed_file`] with the lock layer's options (how long to
1024 /// wait for the lock, a cancel), as [`Mnemo::compact_file_waiting`].
1025 pub fn reembed_file_waiting(
1026 path: &str,
1027 passphrase: &str,
1028 embedder: &dyn Embedder,
1029 opts: crate::SharedOptions,
1030 ) -> Result<ReembedReport> {
1031 Self::reembed_file_secret(
1032 path,
1033 passphrase.as_bytes(),
1034 SecretKind::Passphrase,
1035 embedder,
1036 &opts,
1037 )
1038 }
1039
1040 /// [`Mnemo::reembed_file_waiting`] for a raw-key database.
1041 pub fn reembed_file_waiting_with_key(
1042 path: &str,
1043 key: &[u8; crypto::KEY_LEN],
1044 embedder: &dyn Embedder,
1045 opts: crate::SharedOptions,
1046 ) -> Result<ReembedReport> {
1047 Self::reembed_file_secret(path, key, SecretKind::Key, embedder, &opts)
1048 }
1049
1050 fn reembed_file_secret(
1051 path: &str,
1052 secret: &[u8],
1053 kind: SecretKind,
1054 embedder: &dyn Embedder,
1055 opts: &crate::SharedOptions,
1056 ) -> Result<ReembedReport> {
1057 let to = embedder.identity();
1058 if to.dimensions == 0 {
1059 return Err(MnemoError::Invalid(
1060 "reembed: the embedder's identity has 0 dimensions".into(),
1061 ));
1062 }
1063 let real = std::fs::canonicalize(path)?;
1064 let mut old = Mnemo::open_exclusive_secret(&real, secret, "reembed", opts, true)?;
1065 remove_dead_temps(&real, "reembed");
1066 let from = old.recorded_identity()?;
1067 let kdf = if kind == SecretKind::Passphrase && old.kdf.below_passphrase_floor() {
1068 old.kdf.for_passphrase()
1069 } else {
1070 old.kdf
1071 };
1072 let salt = old.header.salt;
1073 let config = MnemoConfig {
1074 dimensions: to.dimensions,
1075 kdf,
1076 format_version: 0,
1077 store_float_vectors: old.float_vectors(),
1078 ..Default::default()
1079 };
1080 let (tmp, new) = create_temp(&real, "reembed", secret, kind, config, Some(salt))?;
1081 if let Err(e) = copy_mode(old.pager.file(), new.pager.file()) {
1082 drop(new);
1083 let _ = std::fs::remove_file(&tmp);
1084 return Err(e);
1085 }
1086 let result = Self::compact_into(old, new, &real, &tmp, |old, new| {
1087 old.copy_reembedded_into(new, embedder, from.clone(), to.clone())
1088 });
1089 if result.is_err() {
1090 let _ = std::fs::remove_file(&tmp);
1091 }
1092 result
1093 }
1094
1095 /// [`Mnemo::reembed_file`]'s copy: every live memory with a new vector,
1096 /// the new identity, and the cache.
1097 fn copy_reembedded_into(
1098 &mut self,
1099 new: &mut Mnemo,
1100 embedder: &dyn Embedder,
1101 from: Option<embed::EmbedderIdentity>,
1102 to: embed::EmbedderIdentity,
1103 ) -> Result<ReembedReport> {
1104 const BATCH: usize = 64;
1105 new.turn_compress_after = 0;
1106 let want_index = self.has_index();
1107 let now = memory::now_secs();
1108 let dims = to.dimensions;
1109 let mut live: Vec<Memory> = self
1110 .memories()?
1111 .into_iter()
1112 .filter(|m| !m.is_expired(now))
1113 .collect();
1114 let mut manifests = 0;
1115 let mut thread_links = 0;
1116 for m in live.iter_mut() {
1117 if embed::read_identity_from_metadata(&m.metadata).is_some() {
1118 embed::write_identity_into_metadata(&mut m.metadata, &to);
1119 }
1120 }
1121 // R-008.3: a manifest and a thread link carry a sentinel vector, not
1122 // an embedding of their text.
1123 let is_link = |m: &Memory| {
1124 m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str())
1125 == Some(MNEMO_META_KIND_THREAD_LINK)
1126 };
1127 let to_embed: Vec<usize> = (0..live.len())
1128 .filter(|&i| !is_manifest(&live[i]) && !is_link(&live[i]))
1129 .collect();
1130 for chunk in to_embed.chunks(BATCH) {
1131 let texts: Vec<&str> = chunk.iter().map(|&i| live[i].content.as_str()).collect();
1132 let vectors = embedder.embed(&texts)?;
1133 if vectors.len() != texts.len() {
1134 return Err(MnemoError::Invalid(format!(
1135 "reembed: the embedder returned {} vectors for {} texts",
1136 vectors.len(),
1137 texts.len()
1138 )));
1139 }
1140 for (&i, v) in chunk.iter().zip(vectors) {
1141 if v.len() != dims {
1142 return Err(MnemoError::DimensionMismatch {
1143 expected: dims,
1144 got: v.len(),
1145 });
1146 }
1147 if embed::is_zero_vector(&v) {
1148 return Err(MnemoError::Invalid(format!(
1149 "reembed: the embedder returned an all-zero vector for memory {}",
1150 live[i].id
1151 )));
1152 }
1153 live[i].vector = v;
1154 }
1155 }
1156 let memories = live.len();
1157 for mut m in live {
1158 if is_manifest(&m) {
1159 m.vector = Memory::scaffold_manifest(dims).vector;
1160 manifests += 1;
1161 } else if is_link(&m) {
1162 m.vector = new.sentinel_vector();
1163 thread_links += 1;
1164 }
1165 new.put_existing(m)?;
1166 }
1167 if want_index && memories > 0 {
1168 new.build_index_with(IndexConfig::default())?;
1169 }
1170 let mut cache_entries = 0;
1171 let mut cache_dropped = 0;
1172 for pos in 0..self.cache_dir.len() {
1173 let (keep, reserved, wrong_width) = {
1174 let e = &self.cache_dir[pos];
1175 (
1176 !e.deleted && !e.is_expired(now),
1177 embed::is_reserved_namespace(&e.namespace),
1178 e.vector.as_ref().is_some_and(|v| v.len() != dims),
1179 )
1180 };
1181 if !keep || (reserved && self.cache_dir[pos].namespace == embed::IDENTITY_NAMESPACE) {
1182 continue;
1183 }
1184 if wrong_width {
1185 cache_dropped += 1;
1186 continue;
1187 }
1188 new.copy_cache_entry_from(self, pos)?;
1189 if !reserved {
1190 cache_entries += 1;
1191 }
1192 }
1193 new.record_identity(&to)?;
1194 Ok(ReembedReport {
1195 memories: memories - manifests - thread_links,
1196 manifests,
1197 thread_links,
1198 cache_entries,
1199 cache_dropped,
1200 from,
1201 to,
1202 })
1203 }
1204
1205 /// Copy one live cache entry from `old` at directory position
1206 /// `pos` into `self` (a freshly-created compaction target).
1207 /// Decrypts the old record body, substitutes the old *directory*'s
1208 /// `accessed_at` + `access_count` (the record body's copies are
1209 /// stale as of v5's directory-only hit path), re-encodes, writes
1210 /// a fresh record run, and pushes a matching directory entry.
1211 ///
1212 /// Caller is expected to have already filtered out tombstoned /
1213 /// expired entries and to call this on a read-write handle.
1214 pub(crate) fn copy_cache_entry_from(&mut self, old: &mut Mnemo, pos: usize) -> Result<()> {
1215 if self.read_only {
1216 return Err(MnemoError::ReadOnly);
1217 }
1218 // Snapshot the directory fields we need, so the borrow on
1219 // `old.cache_dir` ends before we touch `old.pager`.
1220 let (start_page, page_count, len, dir_accessed_at, dir_access_count, old_gen) = {
1221 let e = &old.cache_dir[pos];
1222 (
1223 e.start_page,
1224 e.page_count,
1225 e.len,
1226 e.accessed_at,
1227 e.access_count,
1228 e.gen,
1229 )
1230 };
1231
1232 // Read + decrypt the old record body.
1233 let buf = old.read_record_run(start_page, page_count, len, old_gen)?;
1234 let mut entry: CacheEntry =
1235 rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
1236
1237 // Overwrite the stale body copies with the directory's live
1238 // values before persisting. Everything else — `created_at`,
1239 // `ttl_secs`, `cost_hint_ms`, `key_preview`, `size_bytes`,
1240 // `content_type`, `value`, `vector`, `model` — stays as the
1241 // body already recorded it.
1242 entry.accessed_at = dir_accessed_at;
1243 entry.access_count = dir_access_count;
1244
1245 let bytes =
1246 rmp_serde::to_vec(&entry).map_err(|err| MnemoError::Serialize(err.to_string()))?;
1247 let (new_start_page, new_page_count, gen) = self.write_record(&bytes)?;
1248
1249 let dir_entry = CacheDirectoryEntry {
1250 namespace: entry.namespace.clone(),
1251 key_hash: entry.key_hash,
1252 start_page: new_start_page,
1253 page_count: new_page_count,
1254 len: bytes.len() as u32,
1255 deleted: false,
1256 accessed_at: dir_accessed_at,
1257 access_count: dir_access_count,
1258 size_bytes: entry.size_bytes,
1259 ttl_secs: entry.ttl_secs,
1260 created_at: entry.created_at,
1261 vector: entry.vector.clone(),
1262 model: entry.model.clone(),
1263 gen,
1264 };
1265 let new_pos = self.cache_dir.len();
1266 self.cache_idx
1267 .insert(&entry.namespace, entry.key_hash, new_pos);
1268 self.cache_dir.push(dir_entry);
1269 self.dirty_cache = true;
1270 Ok(())
1271 }
1272}
1273
1274/// SEC-2 (RB-001.30): overwrite every occurrence of `needle` in the file
1275/// with zeros, then sync. Rekey uses it for stale copies of the old header's
1276/// key wrap: they're plaintext (page 0 is sealed, not encrypted) and can sit
1277/// in WAL regions that were grown, relocated or freed. Every other page is
1278/// AES-GCM ciphertext, where a 76-byte random match doesn't happen.
1279pub(super) fn scrub_bytes(file: &mut std::fs::File, needle: &[u8]) -> Result<usize> {
1280 if needle.is_empty() {
1281 return Ok(0);
1282 }
1283 let len = file.seek(SeekFrom::End(0))?;
1284 let chunk = 1 << 20;
1285 let overlap = needle.len() - 1;
1286 let mut hits: Vec<u64> = Vec::new();
1287 let mut buf = vec![0u8; chunk + overlap];
1288 let mut pos: u64 = 0;
1289 while pos < len {
1290 let want = (chunk as u64 + overlap as u64).min(len - pos) as usize;
1291 file.seek(SeekFrom::Start(pos))?;
1292 file.read_exact(&mut buf[..want])?;
1293 let mut i = 0;
1294 while i + needle.len() <= want {
1295 if buf[i..i + needle.len()] == *needle {
1296 hits.push(pos + i as u64);
1297 i += needle.len();
1298 } else {
1299 i += 1;
1300 }
1301 }
1302 pos += chunk as u64;
1303 }
1304 hits.dedup();
1305 let zeros = vec![0u8; needle.len()];
1306 for off in &hits {
1307 file.seek(SeekFrom::Start(*off))?;
1308 file.write_all(&zeros)?;
1309 }
1310 if !hits.is_empty() {
1311 file.sync_all()?;
1312 crate::bump_fsync();
1313 }
1314 Ok(hits.len())
1315}
1316
1317/// RB-007.8 item 8: remove the temp files that compactions of `brain` left
1318/// when their process died: in `brain`'s directory, regular files named
1319/// exactly `<brain's name>.compact-<pid>-<n>-<8 hex digits>.tmp` (the
1320/// pattern [`temp_sibling`] makes) whose pid isn't this process and no
1321/// longer runs, and, on Unix, that this user owns: in a shared directory
1322/// another user's file of the same name is left alone. Nothing else is
1323/// touched. Best effort; returns how many went.
1324///
1325/// Call it only with `brain`'s exclusive lock held: a live compaction holds
1326/// that lock for as long as its temp file exists. Off Unix no process
1327/// check is available, so nothing is removed.
1328pub(crate) fn remove_dead_compaction_temps(brain: &Path) -> usize {
1329 remove_dead_temps(brain, "compact")
1330}
1331
1332/// [`remove_dead_compaction_temps`] for the temps of another operation
1333/// (`what`, as [`temp_sibling`] names them): 12.3's `init` uses "init".
1334pub(crate) fn remove_dead_temps(brain: &Path, what: &str) -> usize {
1335 let (Some(dir), Some(name)) = (brain.parent(), brain.file_name()) else {
1336 return 0;
1337 };
1338 let prefix = format!("{}.{what}-", name.to_string_lossy());
1339 let Ok(entries) = std::fs::read_dir(dir) else {
1340 return 0;
1341 };
1342 let mut removed = 0;
1343 for entry in entries.flatten() {
1344 let file_name = entry.file_name();
1345 let Some(pid) = file_name.to_str().and_then(|n| dead_temp_pid(n, &prefix)) else {
1346 continue;
1347 };
1348 if pid == std::process::id() || crate::shared::pid_alive(pid) {
1349 continue;
1350 }
1351 let path = entry.path();
1352 let Ok(meta) = std::fs::symlink_metadata(&path) else {
1353 continue;
1354 };
1355 if !meta.file_type().is_file() || !owned_by_us(&meta) {
1356 continue;
1357 }
1358 if std::fs::remove_file(&path).is_ok() {
1359 removed += 1;
1360 }
1361 }
1362 removed
1363}
1364
1365/// Whether this process's user owns the file (Unix). Elsewhere, true: the
1366/// caller removes nothing off Unix anyway.
1367#[cfg(unix)]
1368fn owned_by_us(meta: &std::fs::Metadata) -> bool {
1369 use std::os::unix::fs::MetadataExt;
1370 #[cfg(any(test, feature = "failpoints"))]
1371 if let Some(uid) = crate::__failpoints::euid_override() {
1372 return meta.uid() == uid;
1373 }
1374 meta.uid() == rustix::process::geteuid().as_raw()
1375}
1376
1377#[cfg(not(unix))]
1378fn owned_by_us(_meta: &std::fs::Metadata) -> bool {
1379 true
1380}
1381
1382/// The pid in a compaction temp name `<prefix><pid>-<n>-<8 hex>.tmp`, if the
1383/// name is exactly that.
1384fn dead_temp_pid(name: &str, prefix: &str) -> Option<u32> {
1385 let rest = name.strip_prefix(prefix)?.strip_suffix(".tmp")?;
1386 let mut parts = rest.split('-');
1387 let (pid, n, nanos) = (parts.next()?, parts.next()?, parts.next()?);
1388 let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
1389 let hex8 = nanos.len() == 8 && nanos.bytes().all(|b| b.is_ascii_hexdigit());
1390 if parts.next().is_some() || !digits(pid) || !digits(n) || !hex8 {
1391 return None;
1392 }
1393 pid.parse().ok()
1394}
1395
1396/// The phrase REKEY-1's one exception carries; `mnemo rekey` and
1397/// [`crate::keys::rekey_stored`] look for it.
1398const EITHER_SECRET: &str = "may open with either secret";
1399
1400/// A new, locked temp file next to `dest` (`Create::New`, so nothing already
1401/// at the name, a symlink included, is ever written through), under a fresh
1402/// name for each attempt while names are taken. RB-006.10.
1403pub(crate) fn create_temp(
1404 dest: &Path,
1405 what: &str,
1406 secret: &[u8],
1407 kind: SecretKind,
1408 config: MnemoConfig,
1409 salt: Option<[u8; crypto::SALT_LEN]>,
1410) -> Result<(PathBuf, Mnemo)> {
1411 let mut attempt = 0;
1412 loop {
1413 let tmp = temp_sibling(dest, what);
1414 match Mnemo::create_secret_new(&tmp, secret, kind, config, salt) {
1415 Ok(new) => return Ok((tmp, new)),
1416 Err(e) if is_name_taken(&e) && attempt + 1 < TEMP_NAME_ATTEMPTS => attempt += 1,
1417 Err(e) => return Err(e),
1418 }
1419 }
1420}