Skip to main content

mnemo_engine/store/
shared.rs

1//! 12.4 shared mode's handle (v0.14.0 step 2b): [`SharedMnemo`], from
2//! [`Mnemo::open_shared`]. The design is `docs/design/12.4-shared-access.md`,
3//! "The protocol" steps 4 to 8, "Catching up" (the full reload) and "Writes
4//! that only this handle makes".
5//!
6//! A shared handle holds no lock and no descriptor on the brain between
7//! calls. Each call is a **window** on the file:
8//! 1. take the lock through the lock layer (`crate::shared`): shared for
9//!    [`SharedMnemo::read`], exclusive for [`SharedMnemo::write`];
10//! 2. catch up: compare the header's seal (and, on Unix, the file's
11//!    identity) with the stamp of the state the handle holds, and reload
12//!    if they differ. A pending WAL or a torn page 0 takes the exclusive
13//!    lock first, then replays or heals, then reloads;
14//! 3. run the caller's closure on the handle: read-only for a read, with
15//!    access statistics kept as a delta; for a write, the stamp is cleared
16//!    first, the generation lease is reset (the first page the window seals
17//!    takes a fresh one), the delta is applied, and the window commits
18//!    before it lets go;
19//! 4. unlock and close.
20
21use std::collections::HashMap;
22use std::sync::Arc;
23
24use zeroize::Zeroizing;
25
26use super::*;
27use crate::shared::{BrainLocks, Call, CancelToken, LockKind, SharedOptions};
28
29/// Access statistics a shared handle saw while it held only the shared lock
30/// (recall hits, cache hits): applied with the handle's next commit, and
31/// dropped at close (12.4 design note, "Writes that only this handle
32/// makes").
33#[derive(Clone, Debug, Default)]
34pub(crate) struct AccessDelta {
35    /// Memory id → (hits, latest hit).
36    memories: HashMap<u128, (u32, i64)>,
37    /// (namespace, key hash) → (hits, latest hit).
38    cache: HashMap<(String, [u8; 32]), (u32, i64)>,
39}
40
41impl AccessDelta {
42    pub(crate) fn memory_hit(&mut self, id: u128, at: i64) {
43        let e = self.memories.entry(id).or_insert((0, at));
44        e.0 = e.0.saturating_add(1);
45        e.1 = e.1.max(at);
46    }
47
48    pub(crate) fn cache_hit(&mut self, namespace: &str, key_hash: [u8; 32], at: i64) {
49        let e = self
50            .cache
51            .entry((namespace.to_string(), key_hash))
52            .or_insert((0, at));
53        e.0 = e.0.saturating_add(1);
54        e.1 = e.1.max(at);
55    }
56}
57
58impl Mnemo {
59    /// Open the brain at `path` in **shared mode** (12.4): several
60    /// processes, sessions and tools can use one file at once. The handle
61    /// takes the file's lock for each call and holds nothing between calls.
62    ///
63    /// The file must exist and be v9; shared mode never creates one. It's
64    /// refused on a network or synced filesystem unless
65    /// [`SharedOptions::allow_network_fs`], and on Windows builds made with
66    /// Rust before 1.85 ([`MnemoError::Unsupported`]).
67    ///
68    /// The handle **keeps its secret** for its whole life, because every
69    /// compaction gives the file a new data key: without the secret, a
70    /// handle couldn't follow a `mnemo compact`. The passphrase is zeroized
71    /// when the handle drops.
72    ///
73    /// Use [`SharedMnemo::read`] and [`SharedMnemo::write`] to call the
74    /// handle's methods. Rust API only for now; the Python, CLI and MCP
75    /// surfaces come later.
76    pub fn open_shared(
77        path: impl AsRef<Path>,
78        passphrase: &str,
79        opts: SharedOptions,
80    ) -> Result<SharedMnemo> {
81        let mut s = SharedMnemo::open(path.as_ref(), passphrase.as_bytes(), opts)?;
82        // 12.3 (the keys note, section 1, rule 7).
83        let kdf = s.read(|db| Ok(db.kdf_params()))?;
84        if let Some(n) = super::open::passphrase_floor_notice(&s.path, kdf) {
85            s.locks.notice(n);
86        }
87        Ok(s)
88    }
89
90    /// [`Mnemo::open_shared`] for a raw-key file.
91    pub fn open_shared_with_key(
92        path: impl AsRef<Path>,
93        key: &[u8; crypto::KEY_LEN],
94        opts: SharedOptions,
95    ) -> Result<SharedMnemo> {
96        SharedMnemo::open(path.as_ref(), key, opts)
97    }
98
99    /// Apply a shared handle's statistics delta to the catalog and the cache
100    /// directory, marking them dirty for this window's commit.
101    fn apply_access_delta(&mut self, d: &AccessDelta) {
102        for (id, (n, at)) in &d.memories {
103            if let Some(idx) = self.index.get(*id, &self.catalog) {
104                self.touch(idx);
105                let e = &mut self.catalog[idx];
106                e.access_count = e.access_count.saturating_add(*n);
107                e.accessed_at = e.accessed_at.max(*at);
108                self.dirty_catalog = true;
109            }
110        }
111        for ((ns, key), (n, at)) in &d.cache {
112            for e in self.cache_dir.iter_mut() {
113                if !e.deleted && e.namespace == *ns && e.key_hash == *key {
114                    e.access_count = e.access_count.saturating_add(*n);
115                    e.accessed_at = e.accessed_at.max(*at);
116                    self.dirty_cache = true;
117                }
118            }
119        }
120    }
121}
122
123/// The settings that decide what a commit does to the whole file. In v0.14
124/// a shared handle keeps the defaults and refuses a change.
125#[derive(PartialEq, Debug)]
126struct FileSettings {
127    max_snapshots: usize,
128    snapshot_cap_explicit: bool,
129    turn_compress_after: i64,
130    /// The per-namespace budgets themselves, sorted: a changed value is a
131    /// change, not only an added or removed namespace.
132    cache_budgets: Vec<(String, usize, u64)>,
133    cache_flush_policy: String,
134}
135
136impl FileSettings {
137    fn of(db: &Mnemo) -> Self {
138        FileSettings {
139            max_snapshots: db.max_snapshots,
140            snapshot_cap_explicit: db.snapshot_cap_explicit,
141            turn_compress_after: db.turn_compress_after,
142            cache_budgets: {
143                let mut b: Vec<_> = db
144                    .cache_budgets
145                    .iter()
146                    .map(|(ns, b)| (ns.clone(), b.max_entries, b.max_bytes))
147                    .collect();
148                b.sort();
149                b
150            },
151            cache_flush_policy: format!("{:?}", db.cache_flush_policy),
152        }
153    }
154}
155
156const SETTINGS_KEPT: &str = "a shared-mode handle keeps the file's default settings in v0.14 \
157     (snapshot retention, cache budgets, the cache flush policy, turn compression): every \
158     process's commits would apply one handle's setting to the whole file";
159
160fn settings_refused() -> MnemoError {
161    MnemoError::Unsupported(format!("{SETTINGS_KEPT}. Nothing was changed"))
162}
163
164/// RB-007.5: the window's closure committed part of its work itself (a
165/// `flush`, or a method that commits, such as `commit_deltas`) before `e`.
166fn part_stored(e: impl std::fmt::Display) -> MnemoError {
167    MnemoError::MaybeStored(format!(
168        "{e}; an earlier commit in this window is in the file, so part of the window \
169         was stored"
170    ))
171}
172
173/// A read had to heal the file (a pending WAL, a torn page 0) and this
174/// process can't open it for writing (RB-007.8 item 5).
175const HEAL_NEEDS_WRITE: &str = "the file has a pending WAL or a torn header to recover, \
176     and this process can't write to it";
177
178/// What tells a shared handle that the file changed (12.4 protocol step 5):
179/// the header's seal, which gets a fresh random nonce on every header
180/// write, with the file's identity as the quick first test on Unix.
181#[derive(Clone, Copy, PartialEq, Eq, Debug)]
182struct Stamp {
183    identity: Option<(u64, u64)>,
184    seal: Option<([u8; crypto::NONCE_LEN], [u8; crypto::TAG_LEN])>,
185}
186
187impl Stamp {
188    fn of(file: &File, header: &Header) -> Self {
189        Stamp {
190            identity: identity(file),
191            seal: header.seal_nonce.zip(header.seal_tag),
192        }
193    }
194}
195
196#[cfg(unix)]
197fn identity(file: &File) -> Option<(u64, u64)> {
198    use std::os::unix::fs::MetadataExt;
199    file.metadata().ok().map(|m| (m.dev(), m.ino()))
200}
201
202/// Off Unix the seal alone tells (std has no stable file index there).
203#[cfg(not(unix))]
204fn identity(_file: &File) -> Option<(u64, u64)> {
205    None
206}
207
208impl Mnemo {
209    /// 13a (R-010.6): a stamp of the file's committed state, read without
210    /// the key and without a lock: page 0's seal, with the file's identity,
211    /// length and modification time (so a write the seal doesn't cover yet,
212    /// like a WAL a crash left, changes it too). Two equal stamps mean
213    /// nothing was committed between them. `None` when it can't be read (a
214    /// page 0 torn by a write in progress, say): then read the file.
215    pub fn file_stamp(path: &Path) -> Option<String> {
216        let mut f = File::open(path).ok()?;
217        let page = read_page0(&mut f).ok()?;
218        let h = Header::from_page(&page).ok()?;
219        let (nonce, tag) = (h.seal_nonce?, h.seal_tag?);
220        let m = f.metadata().ok()?;
221        let mtime = m
222            .modified()
223            .ok()
224            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
225            .map_or(0, |d| d.as_nanos());
226        let hex = |b: &[u8]| b.iter().map(|x| format!("{x:02x}")).collect::<String>();
227        let id = identity(&f).map_or("-".to_string(), |(d, i)| format!("{d}.{i}"));
228        Some(format!(
229            "{}{}.{id}.{}.{mtime}",
230            hex(&nonce),
231            hex(&tag),
232            m.len()
233        ))
234    }
235}
236
237fn read_page0(file: &mut File) -> std::io::Result<[u8; PAGE_SIZE]> {
238    let mut page = [0u8; PAGE_SIZE];
239    file.seek(SeekFrom::Start(0))?;
240    file.read_exact(&mut page)?;
241    Ok(page)
242}
243
244/// After catching up: go on, or take the exclusive lock first.
245enum Next {
246    Ready,
247    NeedExclusive,
248}
249
250/// A brain opened in shared mode (12.4): see [`Mnemo::open_shared`].
251///
252/// Every call goes through [`SharedMnemo::read`] or [`SharedMnemo::write`],
253/// which give the closure the handle for one window on the file:
254///
255/// ```no_run
256/// # use mnemo_engine::{Memory, MemoryType, Mnemo, SharedOptions, RecallRequest};
257/// # fn main() -> mnemo_engine::Result<()> {
258/// let mut brain = Mnemo::open_shared("team.mnemo", "passphrase", SharedOptions::default())?;
259/// let id = brain.write(|db| db.remember(Memory::new("we ship on Fridays", MemoryType::Semantic, vec![0.1, 0.2])))?;
260/// let hits = brain.read(|db| db.recall(&RecallRequest::new(vec![0.1, 0.2]).top_k(5)))?;
261/// # let _ = (id, hits); Ok(()) }
262/// ```
263///
264/// - **A read** runs under the shared lock, on a read-only handle. A
265///   recall's or a cache hit's access statistics are kept and applied with
266///   this handle's next write; they're dropped at [`SharedMnemo::close`].
267/// - **A write** runs under the exclusive lock and commits before the
268///   window ends. If it fails before the commit point, nothing was stored,
269///   for a closure that doesn't commit by itself. A closure that does (it
270///   calls `flush`, or a method that commits, such as `commit_deltas` or
271///   `restore_to`) and then fails gets [`MnemoError::MaybeStored`], saying
272///   part of the window is in the file. If the window's own commit fails
273///   after its commit point, the handle finishes the commit itself and
274///   returns `Ok`, or returns [`MnemoError::MaybeStored`]. If the file was
275///   renamed away during the commit, [`MnemoError::ReplacedDuringWrite`].
276///   Keep to one engine call per window where you can.
277/// - **Access statistics** a failed write window applied are dropped when
278///   its commit fails; they're statistics, and the next hits count again.
279/// - **Settings** that act on the whole file (snapshot retention, cache
280///   budgets, the cache flush policy, turn compression) are refused in
281///   v0.14 with [`MnemoError::Unsupported`], and so is `rekey` inside a
282///   closure (use [`SharedMnemo::rekey`], which also updates the secret the
283///   handle keeps). The page cache's size, the vector cache budget and the
284///   embedder (however it was set) are kept across reloads.
285/// - **A cancel** ([`SharedMnemo::set_cancel`]) reaches only a call that is
286///   waiting for a lock; once a call holds the lock it runs to its end.
287pub struct SharedMnemo {
288    locks: BrainLocks,
289    opts: SharedOptions,
290    path: PathBuf,
291    secret: Zeroizing<Vec<u8>>,
292    db: Option<Mnemo>,
293    /// `None` means "reload at the next call" (12.4 protocol step 7).
294    stamp: Option<Stamp>,
295    delta: AccessDelta,
296    embedder: Option<Arc<dyn Embedder>>,
297    /// 13a: the author stamped on new records, kept across reloads.
298    author: Option<String>,
299    /// 13a (13.3): the author's presence lock, held for the handle's life.
300    presence: Option<crate::shared::PresenceLock>,
301    reloads: u64,
302    /// What the last [`SharedMnemo::rekey`] couldn't scrub.
303    rekey_cleanup: Option<String>,
304}
305
306impl std::fmt::Debug for SharedMnemo {
307    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
308        f.debug_struct("SharedMnemo")
309            .field("path", &self.path)
310            .field("loaded", &self.db.is_some())
311            .field("reloads", &self.reloads)
312            .finish()
313    }
314}
315
316impl SharedMnemo {
317    fn open(path: &Path, secret: &[u8], opts: SharedOptions) -> Result<SharedMnemo> {
318        let locks = BrainLocks::new(path, &opts)?;
319        let mut s = SharedMnemo {
320            locks,
321            opts,
322            path: absolute(path.to_path_buf()),
323            secret: Zeroizing::new(secret.to_vec()),
324            db: None,
325            stamp: None,
326            delta: AccessDelta::default(),
327            embedder: None,
328            author: None,
329            presence: None,
330            reloads: 0,
331            rekey_cleanup: None,
332        };
333        // Load now, so a wrong secret or an old format fails at open.
334        s.read(|_| Ok(()))?;
335        Ok(s)
336    }
337
338    /// Run `f` on the handle under the file's shared lock, after catching up
339    /// with any other process's commits. The handle is read-only inside;
340    /// recall's default access tracking works and is applied with this
341    /// handle's next write.
342    pub fn read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
343        self.window(LockKind::Shared, |s| s.run_read(f))
344    }
345
346    /// Run `f` on the handle under the file's exclusive lock, after catching
347    /// up, and commit before the lock is released. See [`SharedMnemo`] for
348    /// what each failure means.
349    ///
350    /// A closure that commits part of its work itself and then fails, or
351    /// then changes a setting, gets [`MnemoError::MaybeStored`]: the earlier
352    /// commit is in the file.
353    pub fn write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
354        self.window(LockKind::Exclusive, |s| s.run_write(f))
355    }
356
357    /// 13a: the author stamped as `_mnemo.author` on each new record (as
358    /// [`Mnemo::set_author`]), kept across reloads. Writes nothing.
359    pub fn set_author(&mut self, author: Option<String>) {
360        if let Some(db) = self.db.as_mut() {
361            db.author = author.clone();
362        }
363        self.author = author;
364    }
365
366    /// 13a (13.3): hold this handle's author's presence lock for the
367    /// handle's life, in the sidecar directory, so [`Mnemo::who`] sees the
368    /// agent as alive and its claims may lapse early once its process is
369    /// gone. Only a long-lived process should (the MCP server); a hook or a
370    /// CLI call never does. It never touches the brain's own lock. Needs an
371    /// author ([`SharedMnemo::set_author`]) and a usable sidecar directory.
372    pub fn hold_presence(&mut self) -> Result<()> {
373        let agent = self.author.clone().ok_or_else(|| {
374            MnemoError::Invalid("a presence lock needs an agent (set_author)".into())
375        })?;
376        let lock = crate::shared::PresenceLock::take(&self.path, &agent)
377            .map_err(|e| MnemoError::Invalid(format!("can't take the presence lock: {e}")))?;
378        self.presence = Some(lock);
379        if let Some(db) = self.db.as_mut() {
380            db.presence_held = true;
381        }
382        Ok(())
383    }
384
385    /// Attach an embedder (as [`Mnemo::set_embedder`]). It's kept across
386    /// reloads. When the file already records this embedder's identity,
387    /// this is a read window and writes nothing; otherwise the identity is
388    /// recorded in a write window.
389    pub fn set_embedder<E: Embedder + 'static>(&mut self, embedder: E) -> Result<()> {
390        let identity = embedder.identity();
391        let needs_write = self.read(move |db| {
392            if db.embedder_would_record(&identity)? {
393                return Ok(Some(embedder));
394            }
395            db.set_embedder(embedder)?;
396            Ok(None)
397        })?;
398        if let Some(embedder) = needs_write {
399            self.write(|db| db.set_embedder(embedder))?;
400        }
401        Ok(())
402    }
403
404    /// Change the passphrase (as [`Mnemo::rekey`], in a write window), and
405    /// replace the secret the handle keeps once the new one is in force, so
406    /// the handle can still follow a compaction or recover the file
407    /// afterwards. An error leaves the old secret in force and kept, unless
408    /// it says the file may open with either.
409    pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
410        self.rekey_secret(new_passphrase.as_bytes(), SecretKind::Passphrase, kdf)
411    }
412
413    /// [`SharedMnemo::rekey`] to a raw 256-bit key (as
414    /// [`Mnemo::rekey_with_key`]).
415    pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
416        self.rekey_secret(new_key, SecretKind::Key, KdfParams::raw_key())
417    }
418
419    /// After a successful [`SharedMnemo::rekey`], what couldn't be scrubbed
420    /// of the old key wrap (see [`Mnemo::rekey_cleanup_error`]).
421    pub fn rekey_cleanup_error(&self) -> Option<&str> {
422        self.rekey_cleanup.as_deref()
423    }
424
425    fn rekey_secret(&mut self, secret: &[u8], kind: SecretKind, kdf: KdfParams) -> Result<()> {
426        // The rekey window applies no statistics, so its only commit is the
427        // rekey's and its errors are the rekey's own; the next write applies
428        // them.
429        let held_back = std::mem::take(&mut self.delta);
430        let mut in_force = None;
431        let r = self.write(|db| {
432            db.rekey_unchecked(secret, kind, kdf, None)?;
433            in_force = Some(db.rekey_cleanup.clone());
434            Ok(())
435        });
436        self.delta = held_back;
437        if let Some(cleanup) = in_force {
438            self.secret = Zeroizing::new(secret.to_vec());
439            self.rekey_cleanup = cleanup;
440        }
441        r
442    }
443
444    /// Give the handle a new cancel token for its later calls, or none
445    /// (RB-007.1). A cancelled token stays cancelled, so after a cancel the
446    /// handle needs a new one (or `None`) to wait for a lock again. A cancel
447    /// reaches only a call that is waiting for a lock.
448    pub fn set_cancel(&mut self, token: Option<CancelToken>) {
449        self.opts.cancel = token;
450    }
451
452    /// The embedder attached to the handle, if any (shared, so a binding can
453    /// embed outside a window and then call [`SharedMnemo::write`]).
454    pub fn embedder_arc(&self) -> Option<Arc<dyn Embedder>> {
455        self.embedder.clone()
456    }
457
458    /// The warnings to show once: a sidecar directory that can't be used, a
459    /// synced folder, an allowed network filesystem.
460    pub fn notices(&self) -> &[String] {
461        self.locks.notices()
462    }
463
464    /// The handle's options: those it was opened with, and the cancel token
465    /// [`SharedMnemo::set_cancel`] gave it last.
466    pub fn options(&self) -> &SharedOptions {
467        &self.opts
468    }
469
470    /// Close the handle. It holds no lock between calls, so this only drops
471    /// what it kept: the secret (zeroized) and the access statistics no
472    /// write has applied yet.
473    pub fn close(self) -> Result<()> {
474        Ok(())
475    }
476
477    /// **Not a stable API** (failpoints builds only). How many times the
478    /// handle has rebuilt its state from the file.
479    #[cfg(any(test, feature = "failpoints"))]
480    #[doc(hidden)]
481    pub fn __reloads(&self) -> u64 {
482        self.reloads
483    }
484
485    /// **Not a stable API** (failpoints builds only). The page cache's
486    /// occupancy and capacity.
487    #[cfg(any(test, feature = "failpoints"))]
488    #[doc(hidden)]
489    pub fn __page_cache(&self) -> (usize, usize) {
490        self.db.as_ref().map_or((0, 0), |d| d.pager.cache_stats())
491    }
492
493    /// **Not a stable API** (failpoints builds only). The handle's state as
494    /// it stands, without a window (no lock, no catch-up): for tests that
495    /// look at what a failed call left in memory. No file is attached, so
496    /// only calls that stay in memory may be made; one that reads or
497    /// writes the file panics.
498    #[cfg(any(test, feature = "failpoints"))]
499    #[doc(hidden)]
500    pub fn __state(&mut self) -> Option<&mut Mnemo> {
501        self.db.as_mut()
502    }
503
504    /// One window: lock, catch up, run, unlock. One [`Call`], so one
505    /// deadline and one cancel token, covers every lock it takes.
506    fn window<R>(&mut self, kind: LockKind, run: impl FnOnce(&mut Self) -> Result<R>) -> Result<R> {
507        // 13a: the presence lock re-checked by identity on every call.
508        if let Some(p) = self.presence.as_mut() {
509            p.refresh();
510        }
511        let mut call = Call::new(self.opts.deadline, self.opts.cancel.as_ref());
512        let mut lock = kind;
513        let held = loop {
514            let mut held = match self.locks.acquire(lock, &mut call) {
515                Ok(h) => h,
516                // A read that has to heal the file, which this process can
517                // only read.
518                Err(MnemoError::Io(e))
519                    if lock != kind && e.kind() == std::io::ErrorKind::PermissionDenied =>
520                {
521                    return Err(MnemoError::NeedsWriteOpen {
522                        reason: HEAL_NEEDS_WRITE,
523                    })
524                }
525                Err(e) => return Err(e),
526            };
527            let file = held.take_file();
528            match self.catch_up(lock, file)? {
529                Next::Ready => break held,
530                // A pending WAL or a torn page 0 under the shared lock:
531                // heal it under the exclusive one, then carry on.
532                Next::NeedExclusive => lock = LockKind::Exclusive,
533            }
534        };
535        // The pager now holds the call's locked file. Release it however
536        // `run` ends: a closure that panics, caught by the caller (UniFFI
537        // catches panics at its boundary, and so do thread pools and
538        // `catch_unwind`), must not leave the handle holding the lock. So
539        // the unwind is caught here, the lock released, and the panic
540        // resumed. A write window has cleared its stamp before running the
541        // closure, so the handle's next call reloads.
542        let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(self)));
543        // RB-015.1: what the handle met inside the call (a damaged index)
544        // joins the notices, once.
545        if let Some(db) = &self.db {
546            for n in db.notices() {
547                self.locks.notice(n.clone());
548            }
549        }
550        // The lock-info note (if any) goes before the unlock.
551        drop(held);
552        if let Some(db) = self.db.as_mut() {
553            drop(db.pager.detach_file());
554            // An embedder set inside a closure is kept across reloads too
555            // (RB-007.8 item 4).
556            self.embedder = db.embedder.clone();
557        }
558        match r {
559            Ok(r) => r,
560            Err(panic) => {
561                // Whatever the closure left half done in memory, read or
562                // write, is reloaded by the next call (RB-007.8 item 6).
563                self.stamp = None;
564                std::panic::resume_unwind(panic)
565            }
566        }
567    }
568
569    /// 12.4 protocol steps 5 and 6 (the identity check of step 4 ran in the
570    /// lock layer): leave `self.db` current, holding `file`.
571    fn catch_up(&mut self, lock: LockKind, mut file: LockedFile) -> Result<Next> {
572        let header = match read_page0(&mut file)
573            .map_err(MnemoError::Io)
574            .and_then(|p| Header::from_page(&p))
575        {
576            Ok(h) => h,
577            // A torn page 0: the scan that heals it reads the whole file and
578            // runs the KDF per candidate, so never under the shared lock.
579            Err(_) if lock == LockKind::Shared => return Ok(Next::NeedExclusive),
580            Err(_) => return self.load(file),
581        };
582        let pending = wal::recover(
583            &mut file,
584            header.wal_start,
585            header.wal_pages,
586            header.wal_seq,
587        )?
588        .is_some();
589        if pending {
590            if lock == LockKind::Shared {
591                return Ok(Next::NeedExclusive);
592            }
593            // Replay, then always reload: the replay moved page 0 past the
594            // handle's state.
595            return self.load(file);
596        }
597        let stamp = Stamp::of(&file, &header);
598        if let (Some(db), Some(held)) = (self.db.as_mut(), self.stamp) {
599            if held == stamp {
600                db.pager.attach_file(file);
601                return Ok(Next::Ready);
602            }
603        }
604        // Another commit (the seal verifies under the key the handle
605        // holds): rebuild from the file without the KDF.
606        if let Some(old) = &self.db {
607            if header.validate_seal(old.pager.dek()).is_ok() {
608                let dek = Zeroizing::new(*old.pager.dek());
609                let kdf = KdfParams {
610                    m_cost: header.m_cost,
611                    t_cost: header.t_cost,
612                    p_cost: header.p_cost,
613                };
614                let new = Mnemo::from_locked(self.path.clone(), file, header, dek, kdf, false)?;
615                self.install(new);
616                return Ok(Next::Ready);
617            }
618        }
619        // The seal doesn't verify under the held key (a compaction's new
620        // data key, a file copied over this one) or nothing is loaded yet:
621        // open it with the kept secret, which returns the specific error
622        // (`WrongPassphrase`, `HeaderTampered`) if that fails too.
623        self.load(file)
624    }
625
626    /// The full open on the call's locked file (heal, replay), then install
627    /// it.
628    fn load(&mut self, file: LockedFile) -> Result<Next> {
629        let new = self.reopen(file)?;
630        self.install(new);
631        Ok(Next::Ready)
632    }
633
634    /// Open the call's locked file as `open` does (heal a torn page 0,
635    /// replay a pending WAL), with the data key the handle holds when the
636    /// header it would recover to verifies under it (no KDF), and the kept
637    /// secret otherwise (RB-007.2): a rekey by another process changes the
638    /// secret but not the data key.
639    fn reopen(&self, file: LockedFile) -> Result<Mnemo> {
640        let held = self.db.as_ref().map(|d| Zeroizing::new(*d.pager.dek()));
641        Mnemo::load_locked_with(
642            self.path.clone(),
643            file,
644            &self.secret,
645            held.as_deref(),
646            false,
647        )
648    }
649
650    /// Take `new` as the handle's state: carry over what is per-process (the
651    /// page cache's size, the vector cache budget, the embedder), and stamp
652    /// it.
653    fn install(&mut self, mut new: Mnemo) {
654        if let Some(old) = &self.db {
655            new.pager.set_cache_capacity(old.pager.cache_stats().1);
656            new.set_vector_cache_budget(old.vector_cache_budget);
657        }
658        if let Some(e) = &self.embedder {
659            new.embedder = Some(e.clone());
660        }
661        new.author = self.author.clone();
662        new.presence_held = self.presence.is_some();
663        new.shared = true;
664        self.stamp = Some(Stamp::of(new.pager.file(), &new.header));
665        self.db = Some(new);
666        self.reloads += 1;
667    }
668
669    fn run_read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
670        let db = self.db.as_mut().expect("loaded by the window");
671        db.read_only = true;
672        db.access_delta = Some(std::mem::take(&mut self.delta));
673        let before = FileSettings::of(db);
674        let r = f(db);
675        db.read_only = false;
676        self.delta = db.access_delta.take().unwrap_or_default();
677        if FileSettings::of(db) != before {
678            self.stamp = None;
679            return Err(settings_refused());
680        }
681        r
682    }
683
684    fn run_write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
685        // Cleared before anything touches the handle's memory, set again
686        // only from a successful commit: an error, or a panic, leaves the
687        // next call to reload (protocol step 7).
688        self.stamp = None;
689        let db = self.db.as_mut().expect("loaded by the window");
690        db.read_only = false;
691        db.access_delta = None;
692        db.commit_point = None;
693        db.window_committed = false;
694        // No lease carries over from an earlier window. Every place that
695        // seals a page takes the lease first when it's missing
696        // (`ensure_gen_lease`), so every page this window seals carries a
697        // generation no other writer has used, even when windows interleave
698        // and one fails before its commit; and a window that seals nothing
699        // commits nothing (RB-007.6).
700        db.gen_leased = false;
701        let delta = std::mem::take(&mut self.delta);
702        db.apply_access_delta(&delta);
703        let before = FileSettings::of(db);
704        let r = f(db).map_err(in_shared_window);
705        let db = self.db.as_mut().expect("loaded by the window");
706        let r = match r {
707            Ok(r) => r,
708            // A commit inside the closure finished (RB-007.5), or got past
709            // its commit point, before the error: it may be in the file.
710            Err(e) if db.window_committed => return Err(part_stored(e)),
711            Err(e) if db.commit_point.is_some() => {
712                return Err(MnemoError::MaybeStored(e.to_string()))
713            }
714            Err(e) => {
715                self.delta = delta;
716                return Err(e);
717            }
718        };
719        if FileSettings::of(db) != before {
720            if db.window_committed || db.commit_point.is_some() {
721                return Err(part_stored(format!(
722                    "{SETTINGS_KEPT}, so the setting wasn't applied"
723                )));
724            }
725            self.delta = delta;
726            return Err(settings_refused());
727        }
728        let committed_before = db.window_committed;
729        #[cfg(any(test, feature = "failpoints"))]
730        crate::__failpoints::run_before_shared_commit();
731        if let Err(e) = db.flush().map_err(in_shared_window) {
732            match self.finish_failed_commit(e) {
733                Ok(()) => {}
734                Err(e @ MnemoError::MaybeStored(_)) => return Err(e),
735                Err(e) if committed_before => return Err(part_stored(e)),
736                Err(e) => return Err(e),
737            }
738        }
739        #[cfg(any(test, feature = "failpoints"))]
740        crate::__failpoints::run_after_shared_commit();
741        // Protocol step 8: the path must still name the file just written.
742        let db = self.db.as_ref().expect("loaded");
743        if !is_file_at(db.pager.file(), &db.path)? {
744            return Err(MnemoError::ReplacedDuringWrite {
745                path: db.path.clone(),
746            });
747        }
748        self.stamp = Some(Stamp::of(db.pager.file(), &db.header));
749        Ok(r)
750    }
751
752    /// A commit failed (protocol step 7). Before the WAL's commit point,
753    /// nothing was stored: return the error. After it, finish the commit
754    /// from the WAL (the same replay an open does) and return `Ok` if the
755    /// transaction is in the file, or [`MnemoError::MaybeStored`] if that
756    /// can't be found out.
757    fn finish_failed_commit(&mut self, e: MnemoError) -> Result<()> {
758        let db = self.db.as_mut().expect("loaded");
759        let Some(txn) = db.commit_point.take() else {
760            return Err(e);
761        };
762        let Some(mut file) = db.pager.detach_file() else {
763            return Err(MnemoError::MaybeStored(e.to_string()));
764        };
765        // Replay a pending transaction here, through the write failpoint,
766        // so a test can fail this step too; `load_locked` then finds the
767        // file current (or heals a torn page 0 itself).
768        let replay = (|| -> Result<()> {
769            let Ok(header) = read_page0(&mut file)
770                .map_err(MnemoError::Io)
771                .and_then(|p| Header::from_page(&p))
772            else {
773                return Ok(());
774            };
775            if let Some(frames) = wal::recover(
776                &mut file,
777                header.wal_start,
778                header.wal_pages,
779                header.wal_seq,
780            )? {
781                for (page_no, bytes) in &frames {
782                    crate::pager::__failpoint_check()?;
783                    file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
784                    file.write_all(bytes)?;
785                }
786                file.sync_all()?;
787                crate::bump_fsync();
788            }
789            Ok(())
790        })();
791        if let Err(e2) = replay {
792            return Err(MnemoError::MaybeStored(format!(
793                "{e}; finishing the commit failed too: {e2}"
794            )));
795        }
796        match self.reopen(file) {
797            Ok(new) => {
798                let stored = new.header.wal_seq >= txn;
799                self.install(new);
800                if stored {
801                    Ok(())
802                } else {
803                    // The commit never became durable: nothing was stored,
804                    // and the handle now holds the file as it is.
805                    self.stamp = None;
806                    Err(e)
807                }
808            }
809            Err(e2) => Err(MnemoError::MaybeStored(format!(
810                "{e}; reading the file back failed: {e2}"
811            ))),
812        }
813    }
814}
815
816/// A commit's pre-write identity check (`Mnemo::ensure_not_replaced`) inside
817/// a write window: the rename came after the window's own identity check
818/// (protocol step 4), from something renaming without the lock (an older
819/// build's compaction). Nothing was written, and the stamp is already
820/// cleared, so the next call follows the new file: say that instead of the
821/// plain handle's "reopen it".
822fn in_shared_window(e: MnemoError) -> MnemoError {
823    match e {
824        MnemoError::Replaced { path, missing, .. } => MnemoError::Replaced {
825            path,
826            shared: true,
827            missing,
828        },
829        e => e,
830    }
831}