Skip to main content

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            index_repair: false,
449            dirty_rows: std::collections::BTreeSet::new(),
450            delta_chain: Vec::new(),
451            delta_rows: 0,
452            catalog_rewrite: false,
453            index_chain: Vec::new(),
454            index_chain_ops: 0,
455            index_rebase: false,
456            index_delta_ops: None,
457            snapshot_cap_explicit: config.max_snapshots != DEFAULT_MAX_SNAPSHOTS,
458            direct_writes: false,
459            vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
460        })
461    }
462
463    /// Open an existing database. A wrong passphrase fails cleanly with
464    /// [`MnemoError::WrongPassphrase`]. Takes an OS exclusive lock for
465    /// the lifetime of the returned handle; a second concurrent open
466    /// (from any process) returns [`MnemoError::Locked`].
467    ///
468    /// For a caller that only needs to read (and can tolerate the
469    /// pending-recovery / pending-migration cases documented on
470    /// [`Mnemo::open_read_only`]), prefer that entry point — it takes a
471    /// shared lock and coexists with other readers.
472    pub fn open(path: impl Into<PathBuf>, passphrase: &str) -> Result<Mnemo> {
473        Self::open_secret(path, passphrase.as_bytes()).map(passphrase_opened)
474    }
475
476    /// PERF-1 step 7: open a database created by [`Mnemo::create_with_key`]
477    /// (or rekeyed with [`Mnemo::rekey_with_key`]) with its raw key.
478    pub fn open_with_key(path: impl Into<PathBuf>, key: &[u8; crypto::KEY_LEN]) -> Result<Mnemo> {
479        Self::open_secret(path, key)
480    }
481
482    pub(super) fn open_secret(path: impl Into<PathBuf>, secret: &[u8]) -> Result<Mnemo> {
483        Self::open_secret_with(path, secret, false)
484    }
485
486    /// The read-write open. `allow_old` lets a file older than v9 open (and
487    /// migrate in memory to v8): only compaction uses it, to read a v4–v8
488    /// file and write the v9 copy. Every public read-write open refuses
489    /// those with [`MnemoError::FormatTooOld`] (the v8 sunset, v0.13).
490    pub(super) fn open_secret_with(
491        path: impl Into<PathBuf>,
492        secret: &[u8],
493        allow_old: bool,
494    ) -> Result<Mnemo> {
495        let path: PathBuf = path.into();
496        let file = open_with_lock(&path, /*write=*/ true, Create::No)?;
497        Self::load_locked(path, file, secret, allow_old)
498    }
499
500    /// Open read-write through 12.4's lock layer, for a long operation that
501    /// must not run alongside shared handles' calls: an import, a rekey, a
502    /// compaction ([`Mnemo::compact_file`] does this itself).
503    ///
504    /// Unlike [`Mnemo::open`], which tries the lock once and fails with
505    /// [`MnemoError::Locked`], this waits up to `opts.deadline` with writer
506    /// preference (the intent lock), so busy shared readers can't keep it
507    /// out. Once it holds the lock it writes a `lock-info` note naming `op`,
508    /// so a shared caller that times out learns what holds the file. The
509    /// handle keeps the exclusive lock until it's dropped or closed, like
510    /// any read-write handle.
511    ///
512    /// Where shared mode isn't available (a network or synced filesystem
513    /// without `opts.allow_network_fs`, or a Windows build made with Rust
514    /// before 1.85) it opens as [`Mnemo::open`] does: one try, no note.
515    pub fn open_exclusive(
516        path: impl AsRef<Path>,
517        passphrase: &str,
518        op: &str,
519        opts: crate::SharedOptions,
520    ) -> Result<Mnemo> {
521        Self::open_exclusive_secret(path.as_ref(), passphrase.as_bytes(), op, &opts, false)
522            .map(passphrase_opened)
523    }
524
525    /// [`Mnemo::open_exclusive`] for a raw-key file.
526    pub fn open_exclusive_with_key(
527        path: impl AsRef<Path>,
528        key: &[u8; crypto::KEY_LEN],
529        op: &str,
530        opts: crate::SharedOptions,
531    ) -> Result<Mnemo> {
532        Self::open_exclusive_secret(path.as_ref(), key, op, &opts, false)
533    }
534
535    pub(super) fn open_exclusive_secret(
536        path: &Path,
537        secret: &[u8],
538        op: &str,
539        opts: &crate::SharedOptions,
540        allow_old: bool,
541    ) -> Result<Mnemo> {
542        let path = absolute(path.to_path_buf());
543        let (file, note) = lock_exclusive(&path, op, opts)?;
544        let mut db = Self::load_locked(path, file, secret, allow_old)?;
545        db.lock_note = note;
546        Ok(db)
547    }
548
549    /// The read-write open's work on a file its caller already holds
550    /// exclusively: heal a torn header, replay a pending WAL, derive the key
551    /// from `secret`, and build the handle. A shared-mode handle (12.4)
552    /// reloads through it with the call's locked file.
553    pub(super) fn load_locked(
554        path: PathBuf,
555        file: LockedFile,
556        secret: &[u8],
557        allow_old: bool,
558    ) -> Result<Mnemo> {
559        Self::load_locked_with(path, file, secret, None, allow_old)
560    }
561
562    /// [`Mnemo::load_locked`], with a data key the caller already holds (a
563    /// shared handle's, RB-007.2). The torn-header scan accepts a candidate
564    /// whose seal verifies under it, and a pending WAL is replayed with it
565    /// when the header the replay writes verifies under it, without running
566    /// the KDF: a rekey changes the secret, never the data key. Anything
567    /// that doesn't verify under it is checked with `secret`, as an open
568    /// does.
569    pub(super) fn load_locked_with(
570        path: PathBuf,
571        mut file: LockedFile,
572        secret: &[u8],
573        held_dek: Option<&[u8; crypto::KEY_LEN]>,
574        allow_old: bool,
575    ) -> Result<Mnemo> {
576        let mut hbuf = [0u8; PAGE_SIZE];
577        file.seek(SeekFrom::Start(0))?;
578        file.read_exact(&mut hbuf)?;
579        let mut header = match Header::from_page(&hbuf) {
580            Ok(h) => h,
581            Err(e) => {
582                // DUR-1 (R-002.1 part 2+3): page 0 did not parse — any
583                // error is treated as a torn-header candidate, not just
584                // `HeaderChecksum`. The whole 294-byte header lives in
585                // the first 512-byte sector, so the realistic failure is
586                // the sector zeroed or garbled, which returns `BadMagic`
587                // or `UnsupportedVersion` *before* the CRC gate.
588                //
589                // Scan the file for valid committed header-frame WAL
590                // regions, pick the highest `txn_id`, and replay it. If
591                // nothing valid is found, return the *original* error so
592                // non-mnemo files still report `BadMagic`.
593                let scan = scan_header_recovery_candidates(&mut file, secret, held_dek)?;
594                let frames = scan.ok_or(e)?;
595                // RB-003.3: the scan has checked the key; refuse an old
596                // format before healing anything.
597                if !allow_old {
598                    if let Some(h) = page_zero_header(&frames) {
599                        if h.version < VERSION_V9 {
600                            return Err(MnemoError::FormatTooOld { version: h.version });
601                        }
602                    }
603                }
604                for (page_no, bytes) in &frames {
605                    if bytes.len() != PAGE_SIZE {
606                        return Err(MnemoError::Invalid("WAL frame is not page-sized".into()));
607                    }
608                    file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
609                    file.write_all(bytes)?;
610                }
611                file.sync_all()?;
612                crate::bump_fsync();
613                file.seek(SeekFrom::Start(0))?;
614                file.read_exact(&mut hbuf)?;
615                Header::from_page(&hbuf)?
616            }
617        };
618
619        // Crash recovery: a committed-but-uncheckpointed transaction is
620        // replayed below. Each frame is a finished page image; the header
621        // frame, replayed to page 0, supersedes the header just read.
622        let pending = wal::recover(
623            &mut file,
624            header.wal_start,
625            header.wal_pages,
626            header.wal_seq,
627        )?;
628
629        // RB-003.3: settle the key and the format before writing anything,
630        // so a wrong secret or a refused old format leaves the file
631        // byte-identical. Both are checked against the header the file will
632        // have once the WAL is replayed (its page-0 frame, else the current
633        // header), since that header is the one the secret must open. No write
634        // the engine makes leaves a pending page-0 frame whose key wrap differs
635        // from page 0's (a rekey logs its new page 0 into a fresh WAL region,
636        // so a cut-off rekey leaves the old secret or the new one, never a
637        // mix), but checking against the replay's header is the right
638        // defence if one ever does.
639        let target = match pending.as_deref().and_then(page_zero_header) {
640            Some(h) => h,
641            None => header.clone(),
642        };
643        let kdf = KdfParams {
644            m_cost: target.m_cost,
645            t_cost: target.t_cost,
646            p_cost: target.p_cost,
647        };
648        let dek = match held_dek {
649            Some(held) if sealed_under(&target, held) => zeroize::Zeroizing::new(*held),
650            _ => {
651                let kek = crypto::derive_kek(secret, &target.salt, kdf)?;
652                crypto::unwrap_dek(&kek, &target.dek_nonce, &target.wrapped_dek)?
653            }
654        };
655        if !allow_old && target.version < VERSION_V9 {
656            return Err(MnemoError::FormatTooOld {
657                version: target.version,
658            });
659        }
660
661        if let Some(frames) = pending {
662            for (page_no, bytes) in &frames {
663                if bytes.len() != PAGE_SIZE {
664                    return Err(MnemoError::Invalid("WAL frame is not page-sized".into()));
665                }
666                file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
667                file.write_all(bytes)?;
668            }
669            file.sync_all()?;
670            crate::bump_fsync();
671            // Re-read the now-current header from the replayed page 0.
672            file.seek(SeekFrom::Start(0))?;
673            file.read_exact(&mut hbuf)?;
674            header = Header::from_page(&hbuf)?;
675        }
676
677        Self::from_locked(path, file, header, dek, kdf, allow_old)
678    }
679
680    /// Build a read-write handle from a locked file whose page 0 is
681    /// `header`, with the data key already unwrapped. The shared-mode reload
682    /// (12.4) comes here directly when the seal verifies under the key it
683    /// holds, so it pays no KDF.
684    pub(super) fn from_locked(
685        path: PathBuf,
686        file: LockedFile,
687        mut header: Header,
688        dek: zeroize::Zeroizing<[u8; crypto::KEY_LEN]>,
689        kdf: KdfParams,
690        allow_old: bool,
691    ) -> Result<Mnemo> {
692        // Validate the v7 header seal now that we have the DEK. Returns
693        // `MnemoError::HeaderTampered` if any of the sealed mutable fields
694        // were rewritten after the last legitimate flush. No-op for v6 and
695        // older — pre-v7 files don't carry a seal.
696        //
697        // DUR-1 (Planner decision 2026-11-01, Option B): a seal failure is
698        // **always** reported as tampering, never auto-healed. R-002.1
699        // part 3's seal-mismatch WAL fallback is withdrawn: the seal
700        // exists for tamper-evidence; silently loading a stale committed
701        // header from the WAL would erase that evidence. A real crash
702        // cannot produce "CRC valid + seal invalid" either, because the
703        // whole 294-byte header lies inside sector 0 which storage
704        // writes atomically — a torn sector breaks magic, version or
705        // CRC first, and *those* are healed by the scan above.
706        header.validate_seal(&dek)?;
707
708        // Build the pager at the file's *current* version so initial reads
709        // use the matching AAD scheme — `Pager::page_aad` returns empty AAD
710        // for v4/v5 (no page binding) and `page_no.to_le_bytes()` for v6+.
711        let on_disk_version = header.version;
712        // The v8 sunset (v0.13): a read-write handle is v9. Older files open
713        // read-only (v8) or through `compact_file`, which converts them.
714        if !allow_old && on_disk_version < VERSION_V9 {
715            return Err(MnemoError::FormatTooOld {
716                version: on_disk_version,
717            });
718        }
719        let mut pager = Pager::new(file, dek, header.write_counter, on_disk_version);
720        let dimensions = header.dimensions as usize;
721
722        // === v4→v5 catalog migration =====================================
723        // v6 reads directly; v5 reads directly; v4 replays the catalog into
724        // the v5 shape by reading each memory's body to populate the new
725        // `accessed_at` / `access_count` fields. All page reads here still
726        // use the v4/v5 AAD scheme (none).
727        let (catalog, migrated_from_v4) = if on_disk_version >= 5 {
728            (
729                load_catalog(
730                    &mut pager,
731                    header.catalog_start,
732                    header.catalog_pages,
733                    header.catalog_len,
734                    header.catalog_gen,
735                )?,
736                false,
737            )
738        } else if on_disk_version == 4 {
739            let v4 = load_catalog_v4(
740                &mut pager,
741                header.catalog_start,
742                header.catalog_pages,
743                header.catalog_len,
744            )?;
745            (migrate_v4_catalog(&mut pager, v4)?, true)
746        } else {
747            return Err(MnemoError::UnsupportedVersion(on_disk_version));
748        };
749        // FMT-9c.2: replay the v9 delta chain onto the base catalog.
750        let (catalog, delta_chain, delta_rows) =
751            apply_delta_chain(&mut pager, catalog, header.catalog_delta)?;
752        let index = build_id_index(&catalog);
753        // PERF-1 step 3: the ANN index loads on first use, not at open. A
754        // v5→v6 page migration is the exception: it must read the index
755        // now, under the old page AAD, to rewrite it.
756        let ann = if on_disk_version < 6 {
757            load_index(
758                &mut pager,
759                header.index_start,
760                header.index_pages,
761                header.index_len,
762                header.index_gen,
763                dimensions,
764            )?
765        } else {
766            None
767        };
768        let ann_unloaded = ann.is_none() && header.index_pages > 0;
769        let mut manifest = load_manifest(
770            &mut pager,
771            header.manifest_start,
772            header.manifest_pages,
773            header.manifest_len,
774            header.manifest_gen,
775        )?;
776
777        // === v5→v6 page-encryption migration =============================
778        // Pre-v6 data pages were encrypted under no AAD; v6 binds the home
779        // `page_no` as AAD so a page-transplant attack fails authentication
780        // on read. Re-stage every live record page through `write_page` so
781        // the next flush re-encrypts it under v6 AAD at the same home slot.
782        // Tombstoned entries skip — they're reclaimed by `compact_file`.
783        // Old catalog / ANN / manifest pages stay as orphan ciphertext;
784        // the next flush writes the new runs at fresh slots.
785        let migrated_pages_to_v6 = on_disk_version < 6;
786        if migrated_pages_to_v6 {
787            for e in &catalog {
788                if e.deleted {
789                    continue;
790                }
791                for i in 0..e.page_count as u64 {
792                    let payload = pager.read_page(e.start_page + i, 0)?;
793                    pager.write_page(e.start_page + i, 0, &payload)?;
794                }
795            }
796            pager.set_version(6);
797        }
798
799        // === v6→v7 header-seal migration =================================
800        // v7 adds an AES-GCM seal at the tail of the header page that
801        // authenticates every mutable header field. Pre-v7 files have no
802        // seal — we just bump the version in memory and mark `dirty_catalog`
803        // so the next flush writes a sealed v7 header. Pages are untouched
804        // (page crypto is unchanged from v6).
805        let migrated_header_to_v7 = on_disk_version < 7;
806        if migrated_header_to_v7 {
807            pager.set_version(7);
808        }
809
810        // === v7→v8 cache-directory migration =============================
811        // v8 adds three u64 header fields (cache_start/pages/len) for the
812        // result-cache directory (Phase 10.1). Pre-v8 files have those
813        // three bytes as zero (the on-disk region beyond the v7 seal is
814        // zero-initialized), which is the legal "empty cache directory"
815        // state — no data migration required. We bump the version in
816        // memory and mark dirty_catalog so the next flush writes a
817        // v8-sealed header with the new AAD shape covering the cache
818        // pointer. Pages are untouched.
819        let migrated_header_to_v8 = on_disk_version < 8;
820        if migrated_header_to_v8 {
821            pager.set_version(VERSION);
822        }
823
824        let migrated = migrated_from_v4
825            || migrated_pages_to_v6
826            || migrated_header_to_v7
827            || migrated_header_to_v8;
828        if migrated {
829            // Stamp the version forward in memory; the next flush persists
830            // it via the WAL-committed header frame (and the v7 seal).
831            header.version = VERSION;
832            // Snapshots written under an older format reference page runs
833            // encrypted under the old AAD scheme; this build can't decrypt
834            // them under the new pager. Drop the manifest so the next
835            // flush records a fresh snapshot of the migrated state.
836            // Point-in-time recovery into the pre-migration past is
837            // sacrificed for migration simplicity. Old pages remain on
838            // disk until `compact_file`. (For v6→v7 alone — which doesn't
839            // change page crypto — the old snapshots would technically
840            // still be readable, but dropping them uniformly keeps the
841            // migration policy simple.)
842            manifest.clear();
843        }
844
845        // The ANN index pages on disk were sealed under the *old* AAD scheme
846        // if we migrated pages to v6; force a rewrite at fresh v6-encrypted
847        // slots on the next flush so a future reopen doesn't try to read
848        // them under the new AAD and fail. (Catalog and manifest already
849        // get rewritten via dirty_catalog and the manifest.clear() above.)
850        let dirty_index = migrated_pages_to_v6 && ann.is_some();
851
852        // Load the cache directory (v8+ only). Pre-v8 files have
853        // cache_pages == 0 by header layout, so this trivially yields
854        // an empty directory without touching the disk.
855        let cache_dir = load_cache_directory(
856            &mut pager,
857            header.cache_start,
858            header.cache_pages,
859            header.cache_len,
860            header.cache_gen,
861        )?;
862        let cache_idx = DirectoryIndex::build(&cache_dir);
863        // FMT-9 (a)/(b): the free list and key-slot run (empty pointers on
864        // v8, so these don't touch the disk there).
865        let free = load_free_list(&mut pager, header.free)?;
866        let key_slots = load_key_slots(&mut pager, header.keys)?;
867        let col = VecColumn::from_catalog(&catalog);
868        let recs = RecPages::from_catalog(&catalog);
869        let bm25_manifest = load_bm25_manifest(&mut pager, header.bm25)?;
870        let max_snapshots = if header.version >= VERSION_V9 {
871            V9_DEFAULT_MAX_SNAPSHOTS
872        } else {
873            DEFAULT_MAX_SNAPSHOTS
874        };
875
876        Ok(Mnemo {
877            pager,
878            header,
879            catalog,
880            index,
881            path: absolute(path),
882            dimensions,
883            kdf,
884            dirty_catalog: migrated,
885            ann,
886            dirty_index,
887            // A v5→v6 page migration leaves the index sealed under the old
888            // page AAD, so it must be rewritten on the next flush.
889            index_persist: IndexPersist {
890                forced: dirty_index,
891                ..IndexPersist::default()
892            },
893            ann_unloaded,
894            manifest,
895            // `Mnemo::open` has no [`MnemoConfig`] to read; default the cap
896            // to [`DEFAULT_MAX_SNAPSHOTS`]. Override with
897            // [`Mnemo::set_max_snapshots`] right after open if you need
898            // unlimited retention or a different cap for this handle.
899            max_snapshots,
900            read_only: false,
901            cache_dir,
902            cache_idx,
903            dirty_cache: false,
904            cache_budgets: std::collections::HashMap::new(),
905            cache_flush_policy: CacheFlushPolicy::default(),
906            cache_batch: BatchState::default(),
907            cache_counters: CounterState::default(),
908            embedder: None,
909            fsyncs_last_flush: 0,
910            agent_set: None,
911            key_index: None,
912            superseded: None,
913            layers: None,
914            rekey_cleanup: None,
915            access_delta: None,
916            commit_point: None,
917            lock_note: None,
918            notices: Vec::new(),
919            window_committed: false,
920            shared: false,
921            turn_compress_after: DEFAULT_TURN_COMPRESS_AFTER_SECS,
922            author: None,
923            presence_held: false,
924            clock_offset: 0,
925            legacy_coordination: None,
926            free,
927            pending_free: Vec::new(),
928            free_dirty: false,
929            key_slots,
930            dirty_keys: false,
931            gen_leased: false,
932            col,
933            recs,
934            bm25: Bm25State {
935                manifest: bm25_manifest,
936                ..Bm25State::default()
937            },
938            kw: None,
939            index_layout_override: None,
940            index_repair: false,
941            dirty_rows: std::collections::BTreeSet::new(),
942            delta_chain,
943            delta_rows,
944            catalog_rewrite: false,
945            index_chain: Vec::new(),
946            index_chain_ops: 0,
947            index_rebase: false,
948            index_delta_ops: None,
949            snapshot_cap_explicit: false,
950            direct_writes: false,
951            vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
952        })
953    }
954
955    /// Open an existing database in **read-only** mode. Takes an OS shared
956    /// lock; multiple read-only handles can coexist, but any attempt to
957    /// open the same file read-write elsewhere returns
958    /// [`MnemoError::Locked`]. All mutating methods on the returned handle
959    /// return [`MnemoError::ReadOnly`], including `recall` with
960    /// `track_access(true)`.
961    ///
962    /// Two conditions block a read-only open and return
963    /// [`MnemoError::NeedsWriteOpen`]:
964    ///
965    /// 1. The file has a committed-but-uncheckpointed WAL transaction that
966    ///    would ordinarily be replayed on open. A read-only handle
967    ///    cannot write the recovered pages back.
968    /// 2. The on-disk format version is older than the current
969    ///    `format::VERSION`, requiring an on-disk migration.
970    ///
971    /// In either case, open the file read-write once (which recovers /
972    /// migrates in place), close the handle cleanly, and reopen
973    /// read-only. This is documented in the README's Durability section.
974    pub fn open_read_only(path: impl Into<PathBuf>, passphrase: &str) -> Result<Mnemo> {
975        Self::open_read_only_secret(path, passphrase.as_bytes()).map(passphrase_opened)
976    }
977
978    /// PERF-1 step 7: [`Mnemo::open_read_only`] for a raw-key database.
979    pub fn open_read_only_with_key(
980        path: impl Into<PathBuf>,
981        key: &[u8; crypto::KEY_LEN],
982    ) -> Result<Mnemo> {
983        Self::open_read_only_secret(path, key)
984    }
985
986    /// The embedding width the file at `path` records, read from its header
987    /// (page 0 is sealed, not encrypted): no key, no lock, no KDF. A caller
988    /// that embeds before it takes the lock uses it to build its embedder's
989    /// identity (12.4: slow work first, unlocked). A torn header is an
990    /// error here (a read-write open heals it).
991    pub fn peek_dimensions(path: impl AsRef<std::path::Path>) -> Result<usize> {
992        let mut file = File::open(path.as_ref())?;
993        let mut hbuf = [0u8; PAGE_SIZE];
994        file.read_exact(&mut hbuf)?;
995        Ok(Header::from_page(&hbuf)?.dimensions as usize)
996    }
997
998    /// Whether `key` opens the raw-key file at `path`, decided from its
999    /// header alone: no catalog load, no lock, microseconds. `Ok(false)` is
1000    /// "not this key". Unlike a read-only open, it answers for a file that
1001    /// has a WAL transaction to recover (the state a kill between a commit
1002    /// and its checkpoint leaves), so a caller trying each of its keys in
1003    /// turn isn't stopped by [`MnemoError::NeedsWriteOpen`]. A torn header is
1004    /// judged from the WAL frame that would heal it. Other failures (not a
1005    /// `.mnemo` file, a tampered header, an I/O error) are errors. Added in
1006    /// v0.12.2 (RB-001.23).
1007    pub fn key_opens(
1008        path: impl AsRef<std::path::Path>,
1009        key: &[u8; crypto::KEY_LEN],
1010    ) -> Result<bool> {
1011        let mut file = File::open(path.as_ref())?;
1012        let mut hbuf = [0u8; PAGE_SIZE];
1013        file.seek(SeekFrom::Start(0))?;
1014        file.read_exact(&mut hbuf)?;
1015        let header = match Header::from_page(&hbuf) {
1016            Ok(h) => h,
1017            // A candidate frame only counts when it validates with `key`.
1018            Err(parse_err) => {
1019                return match scan_header_recovery_candidates(&mut file, key, None)? {
1020                    Some(_) => Ok(true),
1021                    None => Err(parse_err),
1022                }
1023            }
1024        };
1025        let kdf = KdfParams {
1026            m_cost: header.m_cost,
1027            t_cost: header.t_cost,
1028            p_cost: header.p_cost,
1029        };
1030        let kek = crypto::derive_kek(key, &header.salt, kdf)?;
1031        let dek = match crypto::unwrap_dek(&kek, &header.dek_nonce, &header.wrapped_dek) {
1032            Ok(dek) => dek,
1033            Err(MnemoError::WrongPassphrase) => return Ok(false),
1034            Err(e) => return Err(e),
1035        };
1036        header.validate_seal(&dek)?;
1037        Ok(true)
1038    }
1039
1040    pub(super) fn open_read_only_secret(path: impl Into<PathBuf>, secret: &[u8]) -> Result<Mnemo> {
1041        let path: PathBuf = path.into();
1042        let file = open_with_lock(&path, /*write=*/ false, Create::No)?;
1043        Self::read_only_from_locked(path, file, secret)
1044    }
1045
1046    /// [`Mnemo::open_read_only`] through 12.4's lock layer: it waits up to
1047    /// `opts.deadline` for a writer (a plain handle, a shared write, a
1048    /// compaction) instead of failing at once with `Locked`, and runs
1049    /// alongside other readers. The handle then holds the shared lock for
1050    /// its life, as any read-only handle does; close it promptly. A `Locked`
1051    /// after the wait names what holds the file when it left a note.
1052    ///
1053    /// Like `open_read_only`, it never recovers anything: a pending WAL or
1054    /// a torn header gives [`MnemoError::NeedsWriteOpen`]. Where shared
1055    /// mode isn't available it tries once, as `open_read_only` does.
1056    pub fn open_read_only_waiting(
1057        path: impl AsRef<Path>,
1058        passphrase: &str,
1059        opts: crate::SharedOptions,
1060    ) -> Result<Mnemo> {
1061        Self::open_read_only_waiting_secret(path.as_ref(), passphrase.as_bytes(), &opts)
1062            .map(passphrase_opened)
1063    }
1064
1065    /// [`Mnemo::open_read_only_waiting`] for a raw-key file.
1066    pub fn open_read_only_waiting_with_key(
1067        path: impl AsRef<Path>,
1068        key: &[u8; crypto::KEY_LEN],
1069        opts: crate::SharedOptions,
1070    ) -> Result<Mnemo> {
1071        Self::open_read_only_waiting_secret(path.as_ref(), key, &opts)
1072    }
1073
1074    fn open_read_only_waiting_secret(
1075        path: &Path,
1076        secret: &[u8],
1077        opts: &crate::SharedOptions,
1078    ) -> Result<Mnemo> {
1079        let path = absolute(path.to_path_buf());
1080        let file = lock_shared(&path, opts)?;
1081        Self::read_only_from_locked(path, file, secret)
1082    }
1083
1084    /// The read-only open's work on a file its caller holds the shared lock
1085    /// on.
1086    fn read_only_from_locked(path: PathBuf, mut file: LockedFile, secret: &[u8]) -> Result<Mnemo> {
1087        let mut hbuf = [0u8; PAGE_SIZE];
1088        file.seek(SeekFrom::Start(0))?;
1089        file.read_exact(&mut hbuf)?;
1090        // A torn header on a read-only open cannot be healed (that requires
1091        // writing recovered frames back). Surface as `NeedsWriteOpen` so the
1092        // caller knows to reopen read-write once. DUR-1 (R-002.1 part 4):
1093        // any `Header::from_page` failure (`BadMagic`,
1094        // `UnsupportedVersion`, `HeaderChecksum`) qualifies — but only
1095        // when the file-wide scan actually finds a valid committed
1096        // header frame to recover from, so a non-mnemo file still
1097        // reports `BadMagic` cleanly. A `validate_seal` failure is NOT
1098        // routed here (Option B: tampering is never auto-healed).
1099        let header = match Header::from_page(&hbuf) {
1100            Ok(h) => h,
1101            Err(parse_err) => {
1102                let recoverable = scan_header_recovery_candidates(&mut file, secret, None)?;
1103                return Err(match (parse_err, recoverable) {
1104                    // RB-004.5 item 2: as for a pending WAL (RB-003.3), a
1105                    // pre-v9 file can't be opened read-write, so the advice
1106                    // names the step that does heal it.
1107                    (_, Some(frames))
1108                        if page_zero_header(&frames).is_some_and(|h| h.version < VERSION_V9) =>
1109                    {
1110                        MnemoError::NeedsWriteOpen {
1111                            reason: "torn header page in a pre-v9 file; run `mnemo compact \
1112                                     <file>` (with `--key-file <key>` for a raw-key file), \
1113                                     which recovers it and converts the file to v9",
1114                        }
1115                    }
1116                    (_, Some(_)) => MnemoError::NeedsWriteOpen {
1117                        reason: "torn header page needs recovery from WAL",
1118                    },
1119                    (e, None) => e,
1120                });
1121            }
1122        };
1123
1124        // Refuse to migrate on read-only opens. v6→v7 is header-only
1125        // (no page writes required), but even that bumps `version` on
1126        // disk and re-seals the header — which needs write access. Keep
1127        // the policy uniform across all sub-version bumps.
1128        // A v4–v7 file needs migrating, which a read-only handle can't do,
1129        // and since v0.13 no read-write handle opens it either: compaction
1130        // converts it to v9.
1131        if header.version < VERSION {
1132            return Err(MnemoError::FormatTooOld {
1133                version: header.version,
1134            });
1135        }
1136
1137        // Refuse if there is a committed-but-uncheckpointed transaction
1138        // waiting for `wal::recover` to fold it into home pages.
1139        if wal::recover(
1140            &mut file,
1141            header.wal_start,
1142            header.wal_pages,
1143            header.wal_seq,
1144        )?
1145        .is_some()
1146        {
1147            // RB-003.3: a pre-v9 file can't be opened read-write any more,
1148            // so the usual advice would send the user in a circle.
1149            // Compaction recovers the WAL and converts the file.
1150            return Err(MnemoError::NeedsWriteOpen {
1151                reason: if header.version < VERSION_V9 {
1152                    "pending WAL recovery in a pre-v9 file; run `mnemo compact <file>` \
1153                     (with `--key-file <key>` for a raw-key file), which recovers it and \
1154                     converts the file to v9"
1155                } else {
1156                    "pending WAL recovery"
1157                },
1158            });
1159        }
1160
1161        let kdf = KdfParams {
1162            m_cost: header.m_cost,
1163            t_cost: header.t_cost,
1164            p_cost: header.p_cost,
1165        };
1166        let kek = crypto::derive_kek(secret, &header.salt, kdf)?;
1167        let dek = crypto::unwrap_dek(&kek, &header.dek_nonce, &header.wrapped_dek)?;
1168        header.validate_seal(&dek)?;
1169
1170        let mut pager = Pager::new(file, dek, header.write_counter, header.version);
1171        let dimensions = header.dimensions as usize;
1172
1173        let catalog = load_catalog(
1174            &mut pager,
1175            header.catalog_start,
1176            header.catalog_pages,
1177            header.catalog_len,
1178            header.catalog_gen,
1179        )?;
1180        // FMT-9c.2: replay the v9 delta chain onto the base catalog.
1181        let (catalog, delta_chain, delta_rows) =
1182            apply_delta_chain(&mut pager, catalog, header.catalog_delta)?;
1183        let index = build_id_index(&catalog);
1184        // PERF-1 step 3: the ANN index loads on first use, not at open.
1185        let ann: Option<IvfPqIndex> = None;
1186        let ann_unloaded = header.index_pages > 0;
1187        let manifest = load_manifest(
1188            &mut pager,
1189            header.manifest_start,
1190            header.manifest_pages,
1191            header.manifest_len,
1192            header.manifest_gen,
1193        )?;
1194        let cache_dir = load_cache_directory(
1195            &mut pager,
1196            header.cache_start,
1197            header.cache_pages,
1198            header.cache_len,
1199            header.cache_gen,
1200        )?;
1201        let cache_idx = DirectoryIndex::build(&cache_dir);
1202        let free = load_free_list(&mut pager, header.free)?;
1203        let key_slots = load_key_slots(&mut pager, header.keys)?;
1204        let col = VecColumn::from_catalog(&catalog);
1205        let recs = RecPages::from_catalog(&catalog);
1206        let bm25_manifest = load_bm25_manifest(&mut pager, header.bm25)?;
1207        let max_snapshots = if header.version >= VERSION_V9 {
1208            V9_DEFAULT_MAX_SNAPSHOTS
1209        } else {
1210            DEFAULT_MAX_SNAPSHOTS
1211        };
1212
1213        Ok(Mnemo {
1214            pager,
1215            header,
1216            catalog,
1217            index,
1218            path: absolute(path),
1219            dimensions,
1220            kdf,
1221            // No mutation is possible; leave both dirty flags false so
1222            // `close()` is a genuine no-op even if we later add an
1223            // auto-flush on drop.
1224            dirty_catalog: false,
1225            ann,
1226            dirty_index: false,
1227            index_persist: IndexPersist::default(),
1228            ann_unloaded,
1229            manifest,
1230            max_snapshots,
1231            read_only: true,
1232            cache_dir,
1233            cache_idx,
1234            dirty_cache: false,
1235            cache_budgets: std::collections::HashMap::new(),
1236            cache_flush_policy: CacheFlushPolicy::default(),
1237            cache_batch: BatchState::default(),
1238            cache_counters: CounterState::default(),
1239            embedder: None,
1240            fsyncs_last_flush: 0,
1241            agent_set: None,
1242            key_index: None,
1243            superseded: None,
1244            layers: None,
1245            rekey_cleanup: None,
1246            access_delta: None,
1247            commit_point: None,
1248            lock_note: None,
1249            notices: Vec::new(),
1250            window_committed: false,
1251            shared: false,
1252            turn_compress_after: DEFAULT_TURN_COMPRESS_AFTER_SECS,
1253            author: None,
1254            presence_held: false,
1255            clock_offset: 0,
1256            legacy_coordination: None,
1257            free,
1258            pending_free: Vec::new(),
1259            free_dirty: false,
1260            key_slots,
1261            dirty_keys: false,
1262            gen_leased: false,
1263            col,
1264            recs,
1265            bm25: Bm25State {
1266                manifest: bm25_manifest,
1267                ..Bm25State::default()
1268            },
1269            kw: None,
1270            index_layout_override: None,
1271            index_repair: false,
1272            dirty_rows: std::collections::BTreeSet::new(),
1273            delta_chain,
1274            delta_rows,
1275            catalog_rewrite: false,
1276            index_chain: Vec::new(),
1277            index_chain_ops: 0,
1278            index_rebase: false,
1279            index_delta_ops: None,
1280            snapshot_cap_explicit: false,
1281            direct_writes: false,
1282            vector_cache_budget: DEFAULT_VECTOR_CACHE_BUDGET,
1283        })
1284    }
1285
1286    /// 13a: stamp `_mnemo.author` = `author` on each new record this handle
1287    /// writes (a fact, a turn, an essence item; an edit in place keeps the
1288    /// record's own). The CLI, the MCP server and the hooks set it from
1289    /// `MNEMO_AGENT`. Unproven until 13.4 signs it. Per handle, not
1290    /// persisted.
1291    pub fn set_author(&mut self, author: Option<String>) {
1292        self.author = author;
1293    }
1294
1295    /// 13a: the author this handle stamps on new records, if any.
1296    pub fn author(&self) -> Option<&str> {
1297        self.author.as_deref()
1298    }
1299
1300    /// FMT-9e: compress v9 thread-turn records once they're older than
1301    /// `secs` (by their `created_at`). The default,
1302    /// [`DEFAULT_TURN_COMPRESS_AFTER_SECS`], is 7 days: recent turns stay
1303    /// plain, so a live session reads them at full speed, and each commit
1304    /// compresses up to 256 turns that have aged past the cutoff. `0`
1305    /// compresses every turn as it's written. Compaction always compresses
1306    /// every turn, and so does a vacuum that moves one. Applies to this
1307    /// handle only (not persisted); a no-op on v8 files, which never
1308    /// compress. Reading never depends on it.
1309    pub fn set_turn_compress_after(&mut self, secs: u64) {
1310        self.turn_compress_after = secs.min(i64::MAX as u64) as i64;
1311    }
1312
1313    /// Override the manifest snapshot cap on this open handle. `0` disables
1314    /// the cap; any positive value keeps the most-recent `max` snapshots and
1315    /// drops the rest on the next flush. See [`MnemoConfig::max_snapshots`].
1316    pub fn set_max_snapshots(&mut self, max: usize) {
1317        self.max_snapshots = max;
1318        // FMT-9c: an explicit count is a hard cap on v9 (see
1319        // `apply_retention`).
1320        self.snapshot_cap_explicit = true;
1321    }
1322
1323    /// 12.3: the salt in this handle's header, which names its keychain
1324    /// entry (the keys note, section 4).
1325    pub(crate) fn header_salt(&self) -> [u8; crypto::SALT_LEN] {
1326        self.header.salt
1327    }
1328
1329    /// 12.3: the salt in page 0 as it is on disk now, read through this
1330    /// handle's own file (a second open would fail against Windows' lock).
1331    /// After a failed rekey it tells which salt is in force.
1332    pub(crate) fn disk_salt(&mut self) -> Result<[u8; crypto::SALT_LEN]> {
1333        let page = self.pager.read_raw(0)?;
1334        Ok(Header::from_page(&page)?.salt)
1335    }
1336
1337    /// 12.3: what this handle has to tell its owner, once each: today, that
1338    /// a passphrase opened a file whose KDF parameters are the raw-key kind
1339    /// (the keys note, section 1, rule 7), with the fix. Empty otherwise.
1340    pub fn notices(&self) -> &[String] {
1341        &self.notices
1342    }
1343
1344    /// Embedding dimensionality this database expects.
1345    pub fn dimensions(&self) -> usize {
1346        self.dimensions
1347    }
1348
1349    /// Number of live (non-deleted) memories.
1350    pub fn len(&self) -> usize {
1351        self.catalog.iter().filter(|e| !e.deleted).count()
1352    }
1353
1354    /// True if the database holds no live memories.
1355    pub fn is_empty(&self) -> bool {
1356        self.len() == 0
1357    }
1358
1359    // --- internal page/record helpers -------------------------------------
1360}
1361
1362/// 12.3 (the keys note, section 1, rule 7): the notice for a file a
1363/// passphrase opened whose KDF parameters are the raw-key kind, if it is one.
1364pub(crate) fn passphrase_floor_notice(path: &Path, kdf: KdfParams) -> Option<String> {
1365    kdf.below_passphrase_floor().then(|| {
1366        format!(
1367            "{} is protected by a passphrase on raw-key KDF parameters ({} KiB, {} pass), \
1368             which makes each guess of it cheap; `mnemo rekey` or `mnemo compact` raises \
1369             the parameters",
1370            path.display(),
1371            kdf.m_cost,
1372            kdf.t_cost
1373        )
1374    })
1375}
1376
1377/// A handle a passphrase just opened, with [`passphrase_floor_notice`] added.
1378fn passphrase_opened(mut db: Mnemo) -> Mnemo {
1379    if let Some(n) = passphrase_floor_notice(&db.path, db.kdf) {
1380        db.notices.push(n);
1381    }
1382    db
1383}