mnemo_engine/store/open.rs
1//! Create, open (read-write, read-only, raw key) and the handle's basic accessors and per-handle settings.
2
3use super::*;
4
5/// Chunk size for the torn-header scan's streaming read of the file.
6/// We walk the file 1 MiB at a time looking for 8 KiB-aligned `MWAL`
7/// magic. There is **no** cap on how far a given candidate's frame
8/// chain may extend — a 1M-vector IVF+PQ relocation can push a single
9/// transaction well past 16 MiB — so each candidate is read frame by
10/// frame via [`wal::scan_committed_txn`] rather than slurped into a
11/// bounded buffer. (DUR-1 R-002.1 part 2.)
12const TORN_HEADER_SCAN_CHUNK: usize = 1 << 20; // 1 MiB
13
14/// The header a set of recovery frames would write to page 0, if they hold
15/// one that parses.
16fn page_zero_header(frames: &[(u64, Vec<u8>)]) -> Option<Header> {
17 frames
18 .iter()
19 .find(|(page_no, _)| *page_no == 0)
20 .and_then(|(_, bytes)| Header::from_page(bytes).ok())
21}
22
23/// Whether `h` is a v9 header sealed under `dek` (RB-007.2). The version
24/// matters: `validate_seal` passes any header older than v7, which has no
25/// seal.
26fn sealed_under(h: &Header, dek: &[u8; crypto::KEY_LEN]) -> bool {
27 h.version >= VERSION_V9 && h.validate_seal(dek).is_ok()
28}
29
30/// Walk the file for every 8 KiB-aligned page whose first four bytes are
31/// `MWAL`, treating each as a candidate WAL-region start, and return the
32/// frames of the highest-`txn_id` committed transaction whose header
33/// frame fully validates under `passphrase`.
34///
35/// A candidate is accepted only if:
36/// * `wal::scan_committed_txn` returns a committed transaction (chained
37/// CRC verifies, single `txn_id`, `KIND_COMMIT` closes it);
38/// * that transaction contains a `(0, header_page)` frame;
39/// * the header parses with `wal_start == candidate_page_no` and
40/// `wal_seq == txn_id` (so a frame cannot forge a region it was not
41/// written into);
42/// * deriving the KEK from `passphrase + header.salt`, unwrapping the
43/// wrapped DEK, and validating the header seal all succeed.
44///
45/// Returns `Ok(None)` when the scan finds no valid candidate — the
46/// caller is expected to propagate the original parse error so
47/// non-mnemo files still report `BadMagic`.
48///
49/// DUR-1 (R-002.1 part 2): there is no fixed scan window — the whole
50/// file is scanned. Reading at page granularity (not byte granularity)
51/// is sufficient because every WAL region in the format is page-aligned
52/// and every WAL commit writes its first frame at the region's start.
53fn scan_header_recovery_candidates(
54 file: &mut File,
55 secret: &[u8],
56 held_dek: Option<&[u8; crypto::KEY_LEN]>,
57) -> Result<Option<Vec<wal::Frame>>> {
58 let mut best: Option<(u64, Vec<wal::Frame>)> = None;
59 for_each_wal_candidate(file, &mut |file, page_no| {
60 if let Some((txn_id, frames)) = try_recover_candidate(file, page_no, secret, held_dek)? {
61 if best.as_ref().is_none_or(|(id, _)| txn_id > *id) {
62 best = Some((txn_id, frames));
63 }
64 }
65 Ok(())
66 })?;
67 Ok(best.map(|(_, f)| f))
68}
69
70/// Call `f` with every page-aligned page past page 0 whose first four bytes
71/// are `MWAL`: the candidate WAL-region starts the torn-header scan walks.
72fn for_each_wal_candidate(
73 file: &mut File,
74 f: &mut dyn FnMut(&mut File, u64) -> Result<()>,
75) -> Result<()> {
76 let file_len = file.seek(SeekFrom::End(0))?;
77 if file_len < PAGE_SIZE as u64 * 2 {
78 return Ok(()); // No room for even one WAL page past the header.
79 }
80 let page_sz = PAGE_SIZE as u64;
81 let mut offset = page_sz; // Skip page 0.
82
83 // Stream through the file in 1 MiB chunks, scanning each chunk for
84 // page-aligned `MWAL` candidates. Each candidate's frame chain is
85 // then read incrementally via `wal::scan_committed_txn`, which has
86 // no window cap — a 1M-vector IVF+PQ relocation can span tens of
87 // MiB in one committed transaction.
88 let mut chunk = vec![0u8; TORN_HEADER_SCAN_CHUNK];
89 while offset < file_len {
90 let want = (TORN_HEADER_SCAN_CHUNK as u64).min(file_len - offset) as usize;
91 chunk.resize(want, 0);
92 file.seek(SeekFrom::Start(offset))?;
93 let mut filled = 0;
94 while filled < want {
95 match file.read(&mut chunk[filled..])? {
96 0 => break,
97 n => filled += n,
98 }
99 }
100 if filled == 0 {
101 break;
102 }
103 let mut inner = 0usize;
104 while inner + 4 <= filled {
105 if &chunk[inner..inner + 4] == wal::FRAME_MAGIC_BYTES {
106 let page_no = (offset + inner as u64) / page_sz;
107 f(file, page_no)?;
108 }
109 inner += PAGE_SIZE;
110 }
111 offset += filled as u64;
112 }
113 Ok(())
114}
115
116/// 12.3 step 2 (the keys note, section 6): the salts and KDF parameters in
117/// the header frames of the file's committed WAL transactions, newest first
118/// and each salt once, read **without a key** (a WAL frame holds a plaintext
119/// page-0 image). For finding a key-store entry when page 0 doesn't parse.
120/// Nothing here is trusted: the open that follows verifies it all, and heals
121/// the header.
122pub(crate) fn wal_header_salts(path: &Path) -> Result<Vec<([u8; crypto::SALT_LEN], KdfParams)>> {
123 let mut file = File::open(path)?;
124 let mut found: Vec<(u64, [u8; crypto::SALT_LEN], KdfParams)> = Vec::new();
125 for_each_wal_candidate(&mut file, &mut |file, page_no| {
126 if let Some((txn_id, _, h)) = committed_header_candidate(file, page_no)? {
127 found.push((
128 txn_id,
129 h.salt,
130 KdfParams {
131 m_cost: h.m_cost,
132 t_cost: h.t_cost,
133 p_cost: h.p_cost,
134 },
135 ));
136 }
137 Ok(())
138 })?;
139 found.sort_by_key(|f| std::cmp::Reverse(f.0));
140 let mut out: Vec<([u8; crypto::SALT_LEN], KdfParams)> = Vec::new();
141 for (_, salt, kdf) in found {
142 if !out.iter().any(|(s, _)| *s == salt) {
143 out.push((salt, kdf));
144 }
145 }
146 Ok(out)
147}
148
149/// A committed WAL transaction starting at `candidate_page_no` whose header
150/// frame parses and names that region (`wal_start`, `wal_seq`), before any
151/// key is involved.
152fn committed_header_candidate(
153 file: &mut File,
154 candidate_page_no: u64,
155) -> Result<Option<(u64, Vec<wal::Frame>, Header)>> {
156 let Some((txn_id, frames)) = wal::scan_committed_txn(file, candidate_page_no)? else {
157 return Ok(None);
158 };
159 let header_bytes = match frames.iter().find(|(p, _)| *p == 0) {
160 Some((_, b)) => b,
161 None => return Ok(None),
162 };
163 if header_bytes.len() != PAGE_SIZE {
164 return Ok(None);
165 }
166 let mut hbuf = [0u8; PAGE_SIZE];
167 hbuf.copy_from_slice(header_bytes);
168 let Ok(candidate) = Header::from_page(&hbuf) else {
169 return Ok(None);
170 };
171 if candidate.wal_start != candidate_page_no || candidate.wal_seq != txn_id {
172 return Ok(None);
173 }
174 Ok(Some((txn_id, frames, candidate)))
175}
176
177/// Try to recover a committed transaction from `candidate_page_no`,
178/// returning `(txn_id, frames)` only if the candidate's
179/// `(0, header_page)` frame fully validates: the frame chain commits
180/// (via [`wal::scan_committed_txn`]'s streaming reader), the header
181/// parses with `wal_start == candidate_page_no` **and**
182/// `wal_seq == txn_id`, the DEK unwraps under `passphrase`, and the
183/// AES-GCM seal validates. DUR-1 (R-002.1 item 2) requires the
184/// `wal_seq == txn_id` check and no fixed scan window — the streaming
185/// reader handles transactions of arbitrary size.
186fn try_recover_candidate(
187 file: &mut File,
188 candidate_page_no: u64,
189 secret: &[u8],
190 held_dek: Option<&[u8; crypto::KEY_LEN]>,
191) -> Result<Option<(u64, Vec<wal::Frame>)>> {
192 // A header frame at page 0 whose claimed region matches where we found
193 // it, and whose `wal_seq` matches the committed transaction's `txn_id`
194 // — this is what pins the frame to the region it was written into and
195 // keeps a stale checkpointed-and-copied frame from being accepted as a
196 // new region's root.
197 let Some((txn_id, frames, candidate)) = committed_header_candidate(file, candidate_page_no)?
198 else {
199 return Ok(None);
200 };
201 // RB-007.2: a shared handle's data key, when the candidate's seal
202 // verifies under it, without the KDF.
203 if let Some(held) = held_dek {
204 if sealed_under(&candidate, held) {
205 return Ok(Some((txn_id, frames)));
206 }
207 }
208 // DEK unwrap under this candidate's own salt + KDF params.
209 let kdf = KdfParams {
210 m_cost: candidate.m_cost,
211 t_cost: candidate.t_cost,
212 p_cost: candidate.p_cost,
213 };
214 let kek = match crypto::derive_kek(secret, &candidate.salt, kdf) {
215 Ok(k) => k,
216 Err(_) => return Ok(None),
217 };
218 let dek = match crypto::unwrap_dek(&kek, &candidate.dek_nonce, &candidate.wrapped_dek) {
219 Ok(d) => d,
220 Err(_) => return Ok(None),
221 };
222 if candidate.validate_seal(&dek).is_err() {
223 return Ok(None);
224 }
225
226 Ok(Some((txn_id, frames)))
227}
228
229impl Mnemo {
230 /// Create a brand-new encrypted database at `path`.
231 pub fn create(
232 path: impl Into<PathBuf>,
233 passphrase: &str,
234 config: MnemoConfig,
235 ) -> Result<Mnemo> {
236 Self::create_secret(path, passphrase.as_bytes(), SecretKind::Passphrase, config)
237 }
238
239 /// PERF-1 step 7 (R-004.5): create a database unlocked by a **raw
240 /// 256-bit key** instead of a passphrase, for keys held by an OS
241 /// keychain or keystore. The key must be uniformly random (see
242 /// [`Mnemo::generate_key`]); it gets no stretching. The header records
243 /// minimal Argon2id parameters ([`KdfParams::raw_key`]), so opening
244 /// costs microseconds instead of tens of milliseconds. `config.kdf` is
245 /// ignored. No format change: the key goes through the same KEK
246 /// derivation a passphrase does.
247 pub fn create_with_key(
248 path: impl Into<PathBuf>,
249 key: &[u8; crypto::KEY_LEN],
250 config: MnemoConfig,
251 ) -> Result<Mnemo> {
252 let config = MnemoConfig {
253 kdf: KdfParams::raw_key(),
254 ..config
255 };
256 Self::create_secret(path, key, SecretKind::Key, config)
257 }
258
259 /// A fresh random 256-bit key for [`Mnemo::create_with_key`], from the
260 /// thread-local CSPRNG (seeded from the OS). Store it in a keychain;
261 /// it can't be recovered from the file.
262 pub fn generate_key() -> [u8; crypto::KEY_LEN] {
263 *crypto::random_dek()
264 }
265
266 pub(super) fn create_secret(
267 path: impl Into<PathBuf>,
268 secret: &[u8],
269 kind: SecretKind,
270 config: MnemoConfig,
271 ) -> Result<Mnemo> {
272 Self::create_secret_as(path.into(), secret, kind, config, Create::Truncate, None)
273 }
274
275 /// [`Mnemo::create_secret`] for a temp file: `Create::New` refuses a
276 /// name that already exists (a symlink included), with `AlreadyExists`.
277 /// `salt` is the salt to keep (a compaction's, 12.3's salt rule), or
278 /// `None` for a fresh one.
279 pub(super) fn create_secret_new(
280 path: &Path,
281 secret: &[u8],
282 kind: SecretKind,
283 config: MnemoConfig,
284 salt: Option<[u8; crypto::SALT_LEN]>,
285 ) -> Result<Mnemo> {
286 Self::create_secret_as(path.to_path_buf(), secret, kind, config, Create::New, salt)
287 }
288
289 /// Where every create meets. 12.3: a passphrase with raw-key parameters
290 /// is refused here, before anything touches the disk (the keys note,
291 /// section 1, rule 2).
292 pub(super) fn create_secret_as(
293 path: PathBuf,
294 secret: &[u8],
295 kind: SecretKind,
296 config: MnemoConfig,
297 create: Create,
298 salt: Option<[u8; crypto::SALT_LEN]>,
299 ) -> Result<Mnemo> {
300 crypto::check_kdf_for(kind, config.kdf)?;
301 if config.dimensions == 0 {
302 return Err(MnemoError::Invalid("dimensions must be > 0".into()));
303 }
304 let version = resolve_format_version(config.format_version)?;
305 if version >= VERSION_V9 && veccol::per_page(config.dimensions) == 0 {
306 return Err(MnemoError::Invalid(format!(
307 "a v9 file supports up to {} dimensions for now (one fp16 vector \
308 must fit a page); vector entries that span pages are not supported yet",
309 (PAYLOAD - veccol::PAGE_HEADER - 4) / 2
310 )));
311 }
312 let flags = if version >= VERSION_V9 && config.store_float_vectors {
313 FLAG_ENCRYPTED | FLAG_FLOAT_VECTORS
314 } else {
315 FLAG_ENCRYPTED
316 };
317 // Exclusive lock covers the write path; second writer sees `Locked`.
318 let file = open_with_lock(&path, /*write=*/ true, create)?;
319
320 let salt = salt.unwrap_or_else(crypto::random_salt);
321 let dek = crypto::random_dek();
322 let kek = crypto::derive_kek(secret, &salt, config.kdf)?;
323 let dek_nonce = crypto::random_nonce();
324 let wrapped = crypto::wrap_dek(&kek, &dek_nonce, &dek)?;
325 if wrapped.len() != WRAPPED_DEK_LEN {
326 return Err(MnemoError::Crypto("unexpected wrapped DEK length".into()));
327 }
328 let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
329 wrapped_dek.copy_from_slice(&wrapped);
330
331 let mut header = Header {
332 version,
333 page_size: PAGE_SIZE as u32,
334 flags,
335 dimensions: config.dimensions as u32,
336 created_at: memory::now_secs(),
337 write_counter: 0,
338 // Page 0 is the header; pages 1..=wal_pages are the WAL;
339 // record/catalog/index pages start after it. Initial WAL size is
340 // chosen per-config (default 8 pages = 64 KiB) and clamped to a
341 // sane floor so the first transaction can always commit.
342 next_page: 1 + config.wal_pages_initial.max(MIN_WAL_PAGES),
343 catalog_start: 0,
344 catalog_pages: 0,
345 catalog_len: 0,
346 vector_count: 0,
347 m_cost: config.kdf.m_cost,
348 t_cost: config.kdf.t_cost,
349 p_cost: config.kdf.p_cost,
350 salt,
351 dek_nonce,
352 wrapped_dek,
353 index_start: 0,
354 index_pages: 0,
355 index_len: 0,
356 wal_start: 1,
357 wal_pages: config.wal_pages_initial.max(MIN_WAL_PAGES),
358 wal_seq: 0,
359 manifest_start: 0,
360 manifest_pages: 0,
361 manifest_len: 0,
362 // Regenerated per write by `apply_seal`; `None` until we seal.
363 seal_nonce: None,
364 seal_tag: None,
365 // v8+ result-cache pointer — zero-initialized on create,
366 // populated only when `cache_put` runs at least once and
367 // the next `flush` seals a directory run.
368 cache_start: 0,
369 cache_pages: 0,
370 cache_len: 0,
371 // FMT-9 v9 fields; all zero on a fresh file (and unused on v8).
372 catalog_gen: 0,
373 index_gen: 0,
374 manifest_gen: 0,
375 cache_gen: 0,
376 free: RunPtr::default(),
377 keys: RunPtr::default(),
378 bm25: RunPtr::default(),
379 index_delta: RunPtr::default(),
380 catalog_delta: RunPtr::default(),
381 };
382
383 let mut pager = Pager::new(file, dek, 0, version);
384 let mut page = header.to_page();
385 header.apply_seal(&mut page, pager.dek())?;
386 pager.write_raw(0, &page)?;
387 pager.sync()?;
388
389 Ok(Mnemo {
390 pager,
391 header,
392 catalog: Vec::new(),
393 index: IdIndex::default(),
394 path: absolute(path),
395 dimensions: config.dimensions,
396 kdf: config.kdf,
397 dirty_catalog: false,
398 ann: None,
399 dirty_index: false,
400 index_persist: IndexPersist::default(),
401 ann_unloaded: false,
402 manifest: Vec::new(),
403 // FMT-9c: v9 keeps fewer snapshots by default: with page reuse,
404 // retention is what pins pages.
405 max_snapshots: if version >= VERSION_V9 && config.max_snapshots == DEFAULT_MAX_SNAPSHOTS
406 {
407 V9_DEFAULT_MAX_SNAPSHOTS
408 } else {
409 config.max_snapshots
410 },
411 read_only: false,
412 cache_dir: Vec::new(),
413 cache_idx: DirectoryIndex::new(),
414 dirty_cache: false,
415 cache_budgets: std::collections::HashMap::new(),
416 cache_flush_policy: CacheFlushPolicy::default(),
417 cache_batch: BatchState::default(),
418 cache_counters: CounterState::default(),
419 embedder: None,
420 fsyncs_last_flush: 0,
421 agent_set: None,
422 key_index: None,
423 superseded: None,
424 layers: None,
425 rekey_cleanup: None,
426 access_delta: None,
427 commit_point: None,
428 lock_note: None,
429 notices: Vec::new(),
430 window_committed: false,
431 shared: false,
432 turn_compress_after: DEFAULT_TURN_COMPRESS_AFTER_SECS,
433 author: None,
434 presence_held: false,
435 clock_offset: 0,
436 legacy_coordination: None,
437 free: FreeList::default(),
438 pending_free: Vec::new(),
439 free_dirty: false,
440 key_slots: KeySlotRun::default(),
441 dirty_keys: false,
442 gen_leased: false,
443 col: VecColumn::default(),
444 recs: RecPages::default(),
445 bm25: Bm25State::default(),
446 kw: None,
447 index_layout_override: None,
448 dirty_rows: std::collections::BTreeSet::new(),
449 delta_chain: Vec::new(),
450 delta_rows: 0,
451 catalog_rewrite: false,
452 index_chain: Vec::new(),
453 index_chain_ops: 0,
454 index_rebase: false,
455 index_delta_ops: None,
456 snapshot_cap_explicit: config.max_snapshots != DEFAULT_MAX_SNAPSHOTS,
457 direct_writes: false,
458 vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
459 })
460 }
461
462 /// Open an existing database. A wrong passphrase fails cleanly with
463 /// [`MnemoError::WrongPassphrase`]. Takes an OS exclusive lock for
464 /// the lifetime of the returned handle; a second concurrent open
465 /// (from any process) returns [`MnemoError::Locked`].
466 ///
467 /// For a caller that only needs to read (and can tolerate the
468 /// pending-recovery / pending-migration cases documented on
469 /// [`Mnemo::open_read_only`]), prefer that entry point — it takes a
470 /// shared lock and coexists with other readers.
471 pub fn open(path: impl Into<PathBuf>, passphrase: &str) -> Result<Mnemo> {
472 Self::open_secret(path, passphrase.as_bytes()).map(passphrase_opened)
473 }
474
475 /// PERF-1 step 7: open a database created by [`Mnemo::create_with_key`]
476 /// (or rekeyed with [`Mnemo::rekey_with_key`]) with its raw key.
477 pub fn open_with_key(path: impl Into<PathBuf>, key: &[u8; crypto::KEY_LEN]) -> Result<Mnemo> {
478 Self::open_secret(path, key)
479 }
480
481 pub(super) fn open_secret(path: impl Into<PathBuf>, secret: &[u8]) -> Result<Mnemo> {
482 Self::open_secret_with(path, secret, false)
483 }
484
485 /// The read-write open. `allow_old` lets a file older than v9 open (and
486 /// migrate in memory to v8): only compaction uses it, to read a v4–v8
487 /// file and write the v9 copy. Every public read-write open refuses
488 /// those with [`MnemoError::FormatTooOld`] (the v8 sunset, v0.13).
489 pub(super) fn open_secret_with(
490 path: impl Into<PathBuf>,
491 secret: &[u8],
492 allow_old: bool,
493 ) -> Result<Mnemo> {
494 let path: PathBuf = path.into();
495 let file = open_with_lock(&path, /*write=*/ true, Create::No)?;
496 Self::load_locked(path, file, secret, allow_old)
497 }
498
499 /// Open read-write through 12.4's lock layer, for a long operation that
500 /// must not run alongside shared handles' calls: an import, a rekey, a
501 /// compaction ([`Mnemo::compact_file`] does this itself).
502 ///
503 /// Unlike [`Mnemo::open`], which tries the lock once and fails with
504 /// [`MnemoError::Locked`], this waits up to `opts.deadline` with writer
505 /// preference (the intent lock), so busy shared readers can't keep it
506 /// out. Once it holds the lock it writes a `lock-info` note naming `op`,
507 /// so a shared caller that times out learns what holds the file. The
508 /// handle keeps the exclusive lock until it's dropped or closed, like
509 /// any read-write handle.
510 ///
511 /// Where shared mode isn't available (a network or synced filesystem
512 /// without `opts.allow_network_fs`, or a Windows build made with Rust
513 /// before 1.85) it opens as [`Mnemo::open`] does: one try, no note.
514 pub fn open_exclusive(
515 path: impl AsRef<Path>,
516 passphrase: &str,
517 op: &str,
518 opts: crate::SharedOptions,
519 ) -> Result<Mnemo> {
520 Self::open_exclusive_secret(path.as_ref(), passphrase.as_bytes(), op, &opts, false)
521 .map(passphrase_opened)
522 }
523
524 /// [`Mnemo::open_exclusive`] for a raw-key file.
525 pub fn open_exclusive_with_key(
526 path: impl AsRef<Path>,
527 key: &[u8; crypto::KEY_LEN],
528 op: &str,
529 opts: crate::SharedOptions,
530 ) -> Result<Mnemo> {
531 Self::open_exclusive_secret(path.as_ref(), key, op, &opts, false)
532 }
533
534 pub(super) fn open_exclusive_secret(
535 path: &Path,
536 secret: &[u8],
537 op: &str,
538 opts: &crate::SharedOptions,
539 allow_old: bool,
540 ) -> Result<Mnemo> {
541 let path = absolute(path.to_path_buf());
542 let (file, note) = lock_exclusive(&path, op, opts)?;
543 let mut db = Self::load_locked(path, file, secret, allow_old)?;
544 db.lock_note = note;
545 Ok(db)
546 }
547
548 /// The read-write open's work on a file its caller already holds
549 /// exclusively: heal a torn header, replay a pending WAL, derive the key
550 /// from `secret`, and build the handle. A shared-mode handle (12.4)
551 /// reloads through it with the call's locked file.
552 pub(super) fn load_locked(
553 path: PathBuf,
554 file: LockedFile,
555 secret: &[u8],
556 allow_old: bool,
557 ) -> Result<Mnemo> {
558 Self::load_locked_with(path, file, secret, None, allow_old)
559 }
560
561 /// [`Mnemo::load_locked`], with a data key the caller already holds (a
562 /// shared handle's, RB-007.2). The torn-header scan accepts a candidate
563 /// whose seal verifies under it, and a pending WAL is replayed with it
564 /// when the header the replay writes verifies under it, without running
565 /// the KDF: a rekey changes the secret, never the data key. Anything
566 /// that doesn't verify under it is checked with `secret`, as an open
567 /// does.
568 pub(super) fn load_locked_with(
569 path: PathBuf,
570 mut file: LockedFile,
571 secret: &[u8],
572 held_dek: Option<&[u8; crypto::KEY_LEN]>,
573 allow_old: bool,
574 ) -> Result<Mnemo> {
575 let mut hbuf = [0u8; PAGE_SIZE];
576 file.seek(SeekFrom::Start(0))?;
577 file.read_exact(&mut hbuf)?;
578 let mut header = match Header::from_page(&hbuf) {
579 Ok(h) => h,
580 Err(e) => {
581 // DUR-1 (R-002.1 part 2+3): page 0 did not parse — any
582 // error is treated as a torn-header candidate, not just
583 // `HeaderChecksum`. The whole 294-byte header lives in
584 // the first 512-byte sector, so the realistic failure is
585 // the sector zeroed or garbled, which returns `BadMagic`
586 // or `UnsupportedVersion` *before* the CRC gate.
587 //
588 // Scan the file for valid committed header-frame WAL
589 // regions, pick the highest `txn_id`, and replay it. If
590 // nothing valid is found, return the *original* error so
591 // non-mnemo files still report `BadMagic`.
592 let scan = scan_header_recovery_candidates(&mut file, secret, held_dek)?;
593 let frames = scan.ok_or(e)?;
594 // RB-003.3: the scan has checked the key; refuse an old
595 // format before healing anything.
596 if !allow_old {
597 if let Some(h) = page_zero_header(&frames) {
598 if h.version < VERSION_V9 {
599 return Err(MnemoError::FormatTooOld { version: h.version });
600 }
601 }
602 }
603 for (page_no, bytes) in &frames {
604 if bytes.len() != PAGE_SIZE {
605 return Err(MnemoError::Invalid("WAL frame is not page-sized".into()));
606 }
607 file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
608 file.write_all(bytes)?;
609 }
610 file.sync_all()?;
611 crate::bump_fsync();
612 file.seek(SeekFrom::Start(0))?;
613 file.read_exact(&mut hbuf)?;
614 Header::from_page(&hbuf)?
615 }
616 };
617
618 // Crash recovery: a committed-but-uncheckpointed transaction is
619 // replayed below. Each frame is a finished page image; the header
620 // frame, replayed to page 0, supersedes the header just read.
621 let pending = wal::recover(
622 &mut file,
623 header.wal_start,
624 header.wal_pages,
625 header.wal_seq,
626 )?;
627
628 // RB-003.3: settle the key and the format before writing anything,
629 // so a wrong secret or a refused old format leaves the file
630 // byte-identical. Both are checked against the header the file will
631 // have once the WAL is replayed (its page-0 frame, else the current
632 // header), since that header is the one the secret must open. No write
633 // the engine makes leaves a pending page-0 frame whose key wrap differs
634 // from page 0's (a rekey logs its new page 0 into a fresh WAL region,
635 // so a cut-off rekey leaves the old secret or the new one, never a
636 // mix), but checking against the replay's header is the right
637 // defence if one ever does.
638 let target = match pending.as_deref().and_then(page_zero_header) {
639 Some(h) => h,
640 None => header.clone(),
641 };
642 let kdf = KdfParams {
643 m_cost: target.m_cost,
644 t_cost: target.t_cost,
645 p_cost: target.p_cost,
646 };
647 let dek = match held_dek {
648 Some(held) if sealed_under(&target, held) => zeroize::Zeroizing::new(*held),
649 _ => {
650 let kek = crypto::derive_kek(secret, &target.salt, kdf)?;
651 crypto::unwrap_dek(&kek, &target.dek_nonce, &target.wrapped_dek)?
652 }
653 };
654 if !allow_old && target.version < VERSION_V9 {
655 return Err(MnemoError::FormatTooOld {
656 version: target.version,
657 });
658 }
659
660 if let Some(frames) = pending {
661 for (page_no, bytes) in &frames {
662 if bytes.len() != PAGE_SIZE {
663 return Err(MnemoError::Invalid("WAL frame is not page-sized".into()));
664 }
665 file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
666 file.write_all(bytes)?;
667 }
668 file.sync_all()?;
669 crate::bump_fsync();
670 // Re-read the now-current header from the replayed page 0.
671 file.seek(SeekFrom::Start(0))?;
672 file.read_exact(&mut hbuf)?;
673 header = Header::from_page(&hbuf)?;
674 }
675
676 Self::from_locked(path, file, header, dek, kdf, allow_old)
677 }
678
679 /// Build a read-write handle from a locked file whose page 0 is
680 /// `header`, with the data key already unwrapped. The shared-mode reload
681 /// (12.4) comes here directly when the seal verifies under the key it
682 /// holds, so it pays no KDF.
683 pub(super) fn from_locked(
684 path: PathBuf,
685 file: LockedFile,
686 mut header: Header,
687 dek: zeroize::Zeroizing<[u8; crypto::KEY_LEN]>,
688 kdf: KdfParams,
689 allow_old: bool,
690 ) -> Result<Mnemo> {
691 // Validate the v7 header seal now that we have the DEK. Returns
692 // `MnemoError::HeaderTampered` if any of the sealed mutable fields
693 // were rewritten after the last legitimate flush. No-op for v6 and
694 // older — pre-v7 files don't carry a seal.
695 //
696 // DUR-1 (Planner decision 2026-11-01, Option B): a seal failure is
697 // **always** reported as tampering, never auto-healed. R-002.1
698 // part 3's seal-mismatch WAL fallback is withdrawn: the seal
699 // exists for tamper-evidence; silently loading a stale committed
700 // header from the WAL would erase that evidence. A real crash
701 // cannot produce "CRC valid + seal invalid" either, because the
702 // whole 294-byte header lies inside sector 0 which storage
703 // writes atomically — a torn sector breaks magic, version or
704 // CRC first, and *those* are healed by the scan above.
705 header.validate_seal(&dek)?;
706
707 // Build the pager at the file's *current* version so initial reads
708 // use the matching AAD scheme — `Pager::page_aad` returns empty AAD
709 // for v4/v5 (no page binding) and `page_no.to_le_bytes()` for v6+.
710 let on_disk_version = header.version;
711 // The v8 sunset (v0.13): a read-write handle is v9. Older files open
712 // read-only (v8) or through `compact_file`, which converts them.
713 if !allow_old && on_disk_version < VERSION_V9 {
714 return Err(MnemoError::FormatTooOld {
715 version: on_disk_version,
716 });
717 }
718 let mut pager = Pager::new(file, dek, header.write_counter, on_disk_version);
719 let dimensions = header.dimensions as usize;
720
721 // === v4→v5 catalog migration =====================================
722 // v6 reads directly; v5 reads directly; v4 replays the catalog into
723 // the v5 shape by reading each memory's body to populate the new
724 // `accessed_at` / `access_count` fields. All page reads here still
725 // use the v4/v5 AAD scheme (none).
726 let (catalog, migrated_from_v4) = if on_disk_version >= 5 {
727 (
728 load_catalog(
729 &mut pager,
730 header.catalog_start,
731 header.catalog_pages,
732 header.catalog_len,
733 header.catalog_gen,
734 )?,
735 false,
736 )
737 } else if on_disk_version == 4 {
738 let v4 = load_catalog_v4(
739 &mut pager,
740 header.catalog_start,
741 header.catalog_pages,
742 header.catalog_len,
743 )?;
744 (migrate_v4_catalog(&mut pager, v4)?, true)
745 } else {
746 return Err(MnemoError::UnsupportedVersion(on_disk_version));
747 };
748 // FMT-9c.2: replay the v9 delta chain onto the base catalog.
749 let (catalog, delta_chain, delta_rows) =
750 apply_delta_chain(&mut pager, catalog, header.catalog_delta)?;
751 let index = build_id_index(&catalog);
752 // PERF-1 step 3: the ANN index loads on first use, not at open. A
753 // v5→v6 page migration is the exception: it must read the index
754 // now, under the old page AAD, to rewrite it.
755 let ann = if on_disk_version < 6 {
756 load_index(
757 &mut pager,
758 header.index_start,
759 header.index_pages,
760 header.index_len,
761 header.index_gen,
762 dimensions,
763 )?
764 } else {
765 None
766 };
767 let ann_unloaded = ann.is_none() && header.index_pages > 0;
768 let mut manifest = load_manifest(
769 &mut pager,
770 header.manifest_start,
771 header.manifest_pages,
772 header.manifest_len,
773 header.manifest_gen,
774 )?;
775
776 // === v5→v6 page-encryption migration =============================
777 // Pre-v6 data pages were encrypted under no AAD; v6 binds the home
778 // `page_no` as AAD so a page-transplant attack fails authentication
779 // on read. Re-stage every live record page through `write_page` so
780 // the next flush re-encrypts it under v6 AAD at the same home slot.
781 // Tombstoned entries skip — they're reclaimed by `compact_file`.
782 // Old catalog / ANN / manifest pages stay as orphan ciphertext;
783 // the next flush writes the new runs at fresh slots.
784 let migrated_pages_to_v6 = on_disk_version < 6;
785 if migrated_pages_to_v6 {
786 for e in &catalog {
787 if e.deleted {
788 continue;
789 }
790 for i in 0..e.page_count as u64 {
791 let payload = pager.read_page(e.start_page + i, 0)?;
792 pager.write_page(e.start_page + i, 0, &payload)?;
793 }
794 }
795 pager.set_version(6);
796 }
797
798 // === v6→v7 header-seal migration =================================
799 // v7 adds an AES-GCM seal at the tail of the header page that
800 // authenticates every mutable header field. Pre-v7 files have no
801 // seal — we just bump the version in memory and mark `dirty_catalog`
802 // so the next flush writes a sealed v7 header. Pages are untouched
803 // (page crypto is unchanged from v6).
804 let migrated_header_to_v7 = on_disk_version < 7;
805 if migrated_header_to_v7 {
806 pager.set_version(7);
807 }
808
809 // === v7→v8 cache-directory migration =============================
810 // v8 adds three u64 header fields (cache_start/pages/len) for the
811 // result-cache directory (Phase 10.1). Pre-v8 files have those
812 // three bytes as zero (the on-disk region beyond the v7 seal is
813 // zero-initialized), which is the legal "empty cache directory"
814 // state — no data migration required. We bump the version in
815 // memory and mark dirty_catalog so the next flush writes a
816 // v8-sealed header with the new AAD shape covering the cache
817 // pointer. Pages are untouched.
818 let migrated_header_to_v8 = on_disk_version < 8;
819 if migrated_header_to_v8 {
820 pager.set_version(VERSION);
821 }
822
823 let migrated = migrated_from_v4
824 || migrated_pages_to_v6
825 || migrated_header_to_v7
826 || migrated_header_to_v8;
827 if migrated {
828 // Stamp the version forward in memory; the next flush persists
829 // it via the WAL-committed header frame (and the v7 seal).
830 header.version = VERSION;
831 // Snapshots written under an older format reference page runs
832 // encrypted under the old AAD scheme; this build can't decrypt
833 // them under the new pager. Drop the manifest so the next
834 // flush records a fresh snapshot of the migrated state.
835 // Point-in-time recovery into the pre-migration past is
836 // sacrificed for migration simplicity. Old pages remain on
837 // disk until `compact_file`. (For v6→v7 alone — which doesn't
838 // change page crypto — the old snapshots would technically
839 // still be readable, but dropping them uniformly keeps the
840 // migration policy simple.)
841 manifest.clear();
842 }
843
844 // The ANN index pages on disk were sealed under the *old* AAD scheme
845 // if we migrated pages to v6; force a rewrite at fresh v6-encrypted
846 // slots on the next flush so a future reopen doesn't try to read
847 // them under the new AAD and fail. (Catalog and manifest already
848 // get rewritten via dirty_catalog and the manifest.clear() above.)
849 let dirty_index = migrated_pages_to_v6 && ann.is_some();
850
851 // Load the cache directory (v8+ only). Pre-v8 files have
852 // cache_pages == 0 by header layout, so this trivially yields
853 // an empty directory without touching the disk.
854 let cache_dir = load_cache_directory(
855 &mut pager,
856 header.cache_start,
857 header.cache_pages,
858 header.cache_len,
859 header.cache_gen,
860 )?;
861 let cache_idx = DirectoryIndex::build(&cache_dir);
862 // FMT-9 (a)/(b): the free list and key-slot run (empty pointers on
863 // v8, so these don't touch the disk there).
864 let free = load_free_list(&mut pager, header.free)?;
865 let key_slots = load_key_slots(&mut pager, header.keys)?;
866 let col = VecColumn::from_catalog(&catalog);
867 let recs = RecPages::from_catalog(&catalog);
868 let bm25_manifest = load_bm25_manifest(&mut pager, header.bm25)?;
869 let max_snapshots = if header.version >= VERSION_V9 {
870 V9_DEFAULT_MAX_SNAPSHOTS
871 } else {
872 DEFAULT_MAX_SNAPSHOTS
873 };
874
875 Ok(Mnemo {
876 pager,
877 header,
878 catalog,
879 index,
880 path: absolute(path),
881 dimensions,
882 kdf,
883 dirty_catalog: migrated,
884 ann,
885 dirty_index,
886 // A v5→v6 page migration leaves the index sealed under the old
887 // page AAD, so it must be rewritten on the next flush.
888 index_persist: IndexPersist {
889 forced: dirty_index,
890 ..IndexPersist::default()
891 },
892 ann_unloaded,
893 manifest,
894 // `Mnemo::open` has no [`MnemoConfig`] to read; default the cap
895 // to [`DEFAULT_MAX_SNAPSHOTS`]. Override with
896 // [`Mnemo::set_max_snapshots`] right after open if you need
897 // unlimited retention or a different cap for this handle.
898 max_snapshots,
899 read_only: false,
900 cache_dir,
901 cache_idx,
902 dirty_cache: false,
903 cache_budgets: std::collections::HashMap::new(),
904 cache_flush_policy: CacheFlushPolicy::default(),
905 cache_batch: BatchState::default(),
906 cache_counters: CounterState::default(),
907 embedder: None,
908 fsyncs_last_flush: 0,
909 agent_set: None,
910 key_index: None,
911 superseded: None,
912 layers: None,
913 rekey_cleanup: None,
914 access_delta: None,
915 commit_point: None,
916 lock_note: None,
917 notices: Vec::new(),
918 window_committed: false,
919 shared: false,
920 turn_compress_after: DEFAULT_TURN_COMPRESS_AFTER_SECS,
921 author: None,
922 presence_held: false,
923 clock_offset: 0,
924 legacy_coordination: None,
925 free,
926 pending_free: Vec::new(),
927 free_dirty: false,
928 key_slots,
929 dirty_keys: false,
930 gen_leased: false,
931 col,
932 recs,
933 bm25: Bm25State {
934 manifest: bm25_manifest,
935 ..Bm25State::default()
936 },
937 kw: None,
938 index_layout_override: None,
939 dirty_rows: std::collections::BTreeSet::new(),
940 delta_chain,
941 delta_rows,
942 catalog_rewrite: false,
943 index_chain: Vec::new(),
944 index_chain_ops: 0,
945 index_rebase: false,
946 index_delta_ops: None,
947 snapshot_cap_explicit: false,
948 direct_writes: false,
949 vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
950 })
951 }
952
953 /// Open an existing database in **read-only** mode. Takes an OS shared
954 /// lock; multiple read-only handles can coexist, but any attempt to
955 /// open the same file read-write elsewhere returns
956 /// [`MnemoError::Locked`]. All mutating methods on the returned handle
957 /// return [`MnemoError::ReadOnly`], including `recall` with
958 /// `track_access(true)`.
959 ///
960 /// Two conditions block a read-only open and return
961 /// [`MnemoError::NeedsWriteOpen`]:
962 ///
963 /// 1. The file has a committed-but-uncheckpointed WAL transaction that
964 /// would ordinarily be replayed on open. A read-only handle
965 /// cannot write the recovered pages back.
966 /// 2. The on-disk format version is older than the current
967 /// `format::VERSION`, requiring an on-disk migration.
968 ///
969 /// In either case, open the file read-write once (which recovers /
970 /// migrates in place), close the handle cleanly, and reopen
971 /// read-only. This is documented in the README's Durability section.
972 pub fn open_read_only(path: impl Into<PathBuf>, passphrase: &str) -> Result<Mnemo> {
973 Self::open_read_only_secret(path, passphrase.as_bytes()).map(passphrase_opened)
974 }
975
976 /// PERF-1 step 7: [`Mnemo::open_read_only`] for a raw-key database.
977 pub fn open_read_only_with_key(
978 path: impl Into<PathBuf>,
979 key: &[u8; crypto::KEY_LEN],
980 ) -> Result<Mnemo> {
981 Self::open_read_only_secret(path, key)
982 }
983
984 /// The embedding width the file at `path` records, read from its header
985 /// (page 0 is sealed, not encrypted): no key, no lock, no KDF. A caller
986 /// that embeds before it takes the lock uses it to build its embedder's
987 /// identity (12.4: slow work first, unlocked). A torn header is an
988 /// error here (a read-write open heals it).
989 pub fn peek_dimensions(path: impl AsRef<std::path::Path>) -> Result<usize> {
990 let mut file = File::open(path.as_ref())?;
991 let mut hbuf = [0u8; PAGE_SIZE];
992 file.read_exact(&mut hbuf)?;
993 Ok(Header::from_page(&hbuf)?.dimensions as usize)
994 }
995
996 /// Whether `key` opens the raw-key file at `path`, decided from its
997 /// header alone: no catalog load, no lock, microseconds. `Ok(false)` is
998 /// "not this key". Unlike a read-only open, it answers for a file that
999 /// has a WAL transaction to recover (the state a kill between a commit
1000 /// and its checkpoint leaves), so a caller trying each of its keys in
1001 /// turn isn't stopped by [`MnemoError::NeedsWriteOpen`]. A torn header is
1002 /// judged from the WAL frame that would heal it. Other failures (not a
1003 /// `.mnemo` file, a tampered header, an I/O error) are errors. Added in
1004 /// v0.12.2 (RB-001.23).
1005 pub fn key_opens(
1006 path: impl AsRef<std::path::Path>,
1007 key: &[u8; crypto::KEY_LEN],
1008 ) -> Result<bool> {
1009 let mut file = File::open(path.as_ref())?;
1010 let mut hbuf = [0u8; PAGE_SIZE];
1011 file.seek(SeekFrom::Start(0))?;
1012 file.read_exact(&mut hbuf)?;
1013 let header = match Header::from_page(&hbuf) {
1014 Ok(h) => h,
1015 // A candidate frame only counts when it validates with `key`.
1016 Err(parse_err) => {
1017 return match scan_header_recovery_candidates(&mut file, key, None)? {
1018 Some(_) => Ok(true),
1019 None => Err(parse_err),
1020 }
1021 }
1022 };
1023 let kdf = KdfParams {
1024 m_cost: header.m_cost,
1025 t_cost: header.t_cost,
1026 p_cost: header.p_cost,
1027 };
1028 let kek = crypto::derive_kek(key, &header.salt, kdf)?;
1029 let dek = match crypto::unwrap_dek(&kek, &header.dek_nonce, &header.wrapped_dek) {
1030 Ok(dek) => dek,
1031 Err(MnemoError::WrongPassphrase) => return Ok(false),
1032 Err(e) => return Err(e),
1033 };
1034 header.validate_seal(&dek)?;
1035 Ok(true)
1036 }
1037
1038 pub(super) fn open_read_only_secret(path: impl Into<PathBuf>, secret: &[u8]) -> Result<Mnemo> {
1039 let path: PathBuf = path.into();
1040 let file = open_with_lock(&path, /*write=*/ false, Create::No)?;
1041 Self::read_only_from_locked(path, file, secret)
1042 }
1043
1044 /// [`Mnemo::open_read_only`] through 12.4's lock layer: it waits up to
1045 /// `opts.deadline` for a writer (a plain handle, a shared write, a
1046 /// compaction) instead of failing at once with `Locked`, and runs
1047 /// alongside other readers. The handle then holds the shared lock for
1048 /// its life, as any read-only handle does; close it promptly. A `Locked`
1049 /// after the wait names what holds the file when it left a note.
1050 ///
1051 /// Like `open_read_only`, it never recovers anything: a pending WAL or
1052 /// a torn header gives [`MnemoError::NeedsWriteOpen`]. Where shared
1053 /// mode isn't available it tries once, as `open_read_only` does.
1054 pub fn open_read_only_waiting(
1055 path: impl AsRef<Path>,
1056 passphrase: &str,
1057 opts: crate::SharedOptions,
1058 ) -> Result<Mnemo> {
1059 Self::open_read_only_waiting_secret(path.as_ref(), passphrase.as_bytes(), &opts)
1060 .map(passphrase_opened)
1061 }
1062
1063 /// [`Mnemo::open_read_only_waiting`] for a raw-key file.
1064 pub fn open_read_only_waiting_with_key(
1065 path: impl AsRef<Path>,
1066 key: &[u8; crypto::KEY_LEN],
1067 opts: crate::SharedOptions,
1068 ) -> Result<Mnemo> {
1069 Self::open_read_only_waiting_secret(path.as_ref(), key, &opts)
1070 }
1071
1072 fn open_read_only_waiting_secret(
1073 path: &Path,
1074 secret: &[u8],
1075 opts: &crate::SharedOptions,
1076 ) -> Result<Mnemo> {
1077 let path = absolute(path.to_path_buf());
1078 let file = lock_shared(&path, opts)?;
1079 Self::read_only_from_locked(path, file, secret)
1080 }
1081
1082 /// The read-only open's work on a file its caller holds the shared lock
1083 /// on.
1084 fn read_only_from_locked(path: PathBuf, mut file: LockedFile, secret: &[u8]) -> Result<Mnemo> {
1085 let mut hbuf = [0u8; PAGE_SIZE];
1086 file.seek(SeekFrom::Start(0))?;
1087 file.read_exact(&mut hbuf)?;
1088 // A torn header on a read-only open cannot be healed (that requires
1089 // writing recovered frames back). Surface as `NeedsWriteOpen` so the
1090 // caller knows to reopen read-write once. DUR-1 (R-002.1 part 4):
1091 // any `Header::from_page` failure (`BadMagic`,
1092 // `UnsupportedVersion`, `HeaderChecksum`) qualifies — but only
1093 // when the file-wide scan actually finds a valid committed
1094 // header frame to recover from, so a non-mnemo file still
1095 // reports `BadMagic` cleanly. A `validate_seal` failure is NOT
1096 // routed here (Option B: tampering is never auto-healed).
1097 let header = match Header::from_page(&hbuf) {
1098 Ok(h) => h,
1099 Err(parse_err) => {
1100 let recoverable = scan_header_recovery_candidates(&mut file, secret, None)?;
1101 return Err(match (parse_err, recoverable) {
1102 // RB-004.5 item 2: as for a pending WAL (RB-003.3), a
1103 // pre-v9 file can't be opened read-write, so the advice
1104 // names the step that does heal it.
1105 (_, Some(frames))
1106 if page_zero_header(&frames).is_some_and(|h| h.version < VERSION_V9) =>
1107 {
1108 MnemoError::NeedsWriteOpen {
1109 reason: "torn header page in a pre-v9 file; run `mnemo compact \
1110 <file>` (with `--key-file <key>` for a raw-key file), \
1111 which recovers it and converts the file to v9",
1112 }
1113 }
1114 (_, Some(_)) => MnemoError::NeedsWriteOpen {
1115 reason: "torn header page needs recovery from WAL",
1116 },
1117 (e, None) => e,
1118 });
1119 }
1120 };
1121
1122 // Refuse to migrate on read-only opens. v6→v7 is header-only
1123 // (no page writes required), but even that bumps `version` on
1124 // disk and re-seals the header — which needs write access. Keep
1125 // the policy uniform across all sub-version bumps.
1126 // A v4–v7 file needs migrating, which a read-only handle can't do,
1127 // and since v0.13 no read-write handle opens it either: compaction
1128 // converts it to v9.
1129 if header.version < VERSION {
1130 return Err(MnemoError::FormatTooOld {
1131 version: header.version,
1132 });
1133 }
1134
1135 // Refuse if there is a committed-but-uncheckpointed transaction
1136 // waiting for `wal::recover` to fold it into home pages.
1137 if wal::recover(
1138 &mut file,
1139 header.wal_start,
1140 header.wal_pages,
1141 header.wal_seq,
1142 )?
1143 .is_some()
1144 {
1145 // RB-003.3: a pre-v9 file can't be opened read-write any more,
1146 // so the usual advice would send the user in a circle.
1147 // Compaction recovers the WAL and converts the file.
1148 return Err(MnemoError::NeedsWriteOpen {
1149 reason: if header.version < VERSION_V9 {
1150 "pending WAL recovery in a pre-v9 file; run `mnemo compact <file>` \
1151 (with `--key-file <key>` for a raw-key file), which recovers it and \
1152 converts the file to v9"
1153 } else {
1154 "pending WAL recovery"
1155 },
1156 });
1157 }
1158
1159 let kdf = KdfParams {
1160 m_cost: header.m_cost,
1161 t_cost: header.t_cost,
1162 p_cost: header.p_cost,
1163 };
1164 let kek = crypto::derive_kek(secret, &header.salt, kdf)?;
1165 let dek = crypto::unwrap_dek(&kek, &header.dek_nonce, &header.wrapped_dek)?;
1166 header.validate_seal(&dek)?;
1167
1168 let mut pager = Pager::new(file, dek, header.write_counter, header.version);
1169 let dimensions = header.dimensions as usize;
1170
1171 let catalog = load_catalog(
1172 &mut pager,
1173 header.catalog_start,
1174 header.catalog_pages,
1175 header.catalog_len,
1176 header.catalog_gen,
1177 )?;
1178 // FMT-9c.2: replay the v9 delta chain onto the base catalog.
1179 let (catalog, delta_chain, delta_rows) =
1180 apply_delta_chain(&mut pager, catalog, header.catalog_delta)?;
1181 let index = build_id_index(&catalog);
1182 // PERF-1 step 3: the ANN index loads on first use, not at open.
1183 let ann: Option<IvfPqIndex> = None;
1184 let ann_unloaded = header.index_pages > 0;
1185 let manifest = load_manifest(
1186 &mut pager,
1187 header.manifest_start,
1188 header.manifest_pages,
1189 header.manifest_len,
1190 header.manifest_gen,
1191 )?;
1192 let cache_dir = load_cache_directory(
1193 &mut pager,
1194 header.cache_start,
1195 header.cache_pages,
1196 header.cache_len,
1197 header.cache_gen,
1198 )?;
1199 let cache_idx = DirectoryIndex::build(&cache_dir);
1200 let free = load_free_list(&mut pager, header.free)?;
1201 let key_slots = load_key_slots(&mut pager, header.keys)?;
1202 let col = VecColumn::from_catalog(&catalog);
1203 let recs = RecPages::from_catalog(&catalog);
1204 let bm25_manifest = load_bm25_manifest(&mut pager, header.bm25)?;
1205 let max_snapshots = if header.version >= VERSION_V9 {
1206 V9_DEFAULT_MAX_SNAPSHOTS
1207 } else {
1208 DEFAULT_MAX_SNAPSHOTS
1209 };
1210
1211 Ok(Mnemo {
1212 pager,
1213 header,
1214 catalog,
1215 index,
1216 path: absolute(path),
1217 dimensions,
1218 kdf,
1219 // No mutation is possible; leave both dirty flags false so
1220 // `close()` is a genuine no-op even if we later add an
1221 // auto-flush on drop.
1222 dirty_catalog: false,
1223 ann,
1224 dirty_index: false,
1225 index_persist: IndexPersist::default(),
1226 ann_unloaded,
1227 manifest,
1228 max_snapshots,
1229 read_only: true,
1230 cache_dir,
1231 cache_idx,
1232 dirty_cache: false,
1233 cache_budgets: std::collections::HashMap::new(),
1234 cache_flush_policy: CacheFlushPolicy::default(),
1235 cache_batch: BatchState::default(),
1236 cache_counters: CounterState::default(),
1237 embedder: None,
1238 fsyncs_last_flush: 0,
1239 agent_set: None,
1240 key_index: None,
1241 superseded: None,
1242 layers: None,
1243 rekey_cleanup: None,
1244 access_delta: None,
1245 commit_point: None,
1246 lock_note: None,
1247 notices: Vec::new(),
1248 window_committed: false,
1249 shared: false,
1250 turn_compress_after: DEFAULT_TURN_COMPRESS_AFTER_SECS,
1251 author: None,
1252 presence_held: false,
1253 clock_offset: 0,
1254 legacy_coordination: None,
1255 free,
1256 pending_free: Vec::new(),
1257 free_dirty: false,
1258 key_slots,
1259 dirty_keys: false,
1260 gen_leased: false,
1261 col,
1262 recs,
1263 bm25: Bm25State {
1264 manifest: bm25_manifest,
1265 ..Bm25State::default()
1266 },
1267 kw: None,
1268 index_layout_override: None,
1269 dirty_rows: std::collections::BTreeSet::new(),
1270 delta_chain,
1271 delta_rows,
1272 catalog_rewrite: false,
1273 index_chain: Vec::new(),
1274 index_chain_ops: 0,
1275 index_rebase: false,
1276 index_delta_ops: None,
1277 snapshot_cap_explicit: false,
1278 direct_writes: false,
1279 vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
1280 })
1281 }
1282
1283 /// 13a: stamp `_mnemo.author` = `author` on each new record this handle
1284 /// writes (a fact, a turn, an essence item; an edit in place keeps the
1285 /// record's own). The CLI, the MCP server and the hooks set it from
1286 /// `MNEMO_AGENT`. Unproven until 13.4 signs it. Per handle, not
1287 /// persisted.
1288 pub fn set_author(&mut self, author: Option<String>) {
1289 self.author = author;
1290 }
1291
1292 /// 13a: the author this handle stamps on new records, if any.
1293 pub fn author(&self) -> Option<&str> {
1294 self.author.as_deref()
1295 }
1296
1297 /// FMT-9e: compress v9 thread-turn records once they're older than
1298 /// `secs` (by their `created_at`). The default,
1299 /// [`DEFAULT_TURN_COMPRESS_AFTER_SECS`], is 7 days: recent turns stay
1300 /// plain, so a live session reads them at full speed, and each commit
1301 /// compresses up to 256 turns that have aged past the cutoff. `0`
1302 /// compresses every turn as it's written. Compaction always compresses
1303 /// every turn, and so does a vacuum that moves one. Applies to this
1304 /// handle only (not persisted); a no-op on v8 files, which never
1305 /// compress. Reading never depends on it.
1306 pub fn set_turn_compress_after(&mut self, secs: u64) {
1307 self.turn_compress_after = secs.min(i64::MAX as u64) as i64;
1308 }
1309
1310 /// Override the manifest snapshot cap on this open handle. `0` disables
1311 /// the cap; any positive value keeps the most-recent `max` snapshots and
1312 /// drops the rest on the next flush. See [`MnemoConfig::max_snapshots`].
1313 pub fn set_max_snapshots(&mut self, max: usize) {
1314 self.max_snapshots = max;
1315 // FMT-9c: an explicit count is a hard cap on v9 (see
1316 // `apply_retention`).
1317 self.snapshot_cap_explicit = true;
1318 }
1319
1320 /// 12.3: the salt in this handle's header, which names its keychain
1321 /// entry (the keys note, section 4).
1322 pub(crate) fn header_salt(&self) -> [u8; crypto::SALT_LEN] {
1323 self.header.salt
1324 }
1325
1326 /// 12.3: the salt in page 0 as it is on disk now, read through this
1327 /// handle's own file (a second open would fail against Windows' lock).
1328 /// After a failed rekey it tells which salt is in force.
1329 pub(crate) fn disk_salt(&mut self) -> Result<[u8; crypto::SALT_LEN]> {
1330 let page = self.pager.read_raw(0)?;
1331 Ok(Header::from_page(&page)?.salt)
1332 }
1333
1334 /// 12.3: what this handle has to tell its owner, once each: today, that
1335 /// a passphrase opened a file whose KDF parameters are the raw-key kind
1336 /// (the keys note, section 1, rule 7), with the fix. Empty otherwise.
1337 pub fn notices(&self) -> &[String] {
1338 &self.notices
1339 }
1340
1341 /// Embedding dimensionality this database expects.
1342 pub fn dimensions(&self) -> usize {
1343 self.dimensions
1344 }
1345
1346 /// Number of live (non-deleted) memories.
1347 pub fn len(&self) -> usize {
1348 self.catalog.iter().filter(|e| !e.deleted).count()
1349 }
1350
1351 /// True if the database holds no live memories.
1352 pub fn is_empty(&self) -> bool {
1353 self.len() == 0
1354 }
1355
1356 // --- internal page/record helpers -------------------------------------
1357}
1358
1359/// 12.3 (the keys note, section 1, rule 7): the notice for a file a
1360/// passphrase opened whose KDF parameters are the raw-key kind, if it is one.
1361pub(crate) fn passphrase_floor_notice(path: &Path, kdf: KdfParams) -> Option<String> {
1362 kdf.below_passphrase_floor().then(|| {
1363 format!(
1364 "{} is protected by a passphrase on raw-key KDF parameters ({} KiB, {} pass), \
1365 which makes each guess of it cheap; `mnemo rekey` or `mnemo compact` raises \
1366 the parameters",
1367 path.display(),
1368 kdf.m_cost,
1369 kdf.t_cost
1370 )
1371 })
1372}
1373
1374/// A handle a passphrase just opened, with [`passphrase_floor_notice`] added.
1375fn passphrase_opened(mut db: Mnemo) -> Mnemo {
1376 if let Some(n) = passphrase_floor_notice(&db.path, db.kdf) {
1377 db.notices.push(n);
1378 }
1379 db
1380}