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