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
208fn read_page0(file: &mut File) -> std::io::Result<[u8; PAGE_SIZE]> {
209    let mut page = [0u8; PAGE_SIZE];
210    file.seek(SeekFrom::Start(0))?;
211    file.read_exact(&mut page)?;
212    Ok(page)
213}
214
215/// After catching up: go on, or take the exclusive lock first.
216enum Next {
217    Ready,
218    NeedExclusive,
219}
220
221/// A brain opened in shared mode (12.4): see [`Mnemo::open_shared`].
222///
223/// Every call goes through [`SharedMnemo::read`] or [`SharedMnemo::write`],
224/// which give the closure the handle for one window on the file:
225///
226/// ```no_run
227/// # use mnemo_engine::{Memory, MemoryType, Mnemo, SharedOptions, RecallRequest};
228/// # fn main() -> mnemo_engine::Result<()> {
229/// let mut brain = Mnemo::open_shared("team.mnemo", "passphrase", SharedOptions::default())?;
230/// let id = brain.write(|db| db.remember(Memory::new("we ship on Fridays", MemoryType::Semantic, vec![0.1, 0.2])))?;
231/// let hits = brain.read(|db| db.recall(&RecallRequest::new(vec![0.1, 0.2]).top_k(5)))?;
232/// # let _ = (id, hits); Ok(()) }
233/// ```
234///
235/// - **A read** runs under the shared lock, on a read-only handle. A
236///   recall's or a cache hit's access statistics are kept and applied with
237///   this handle's next write; they're dropped at [`SharedMnemo::close`].
238/// - **A write** runs under the exclusive lock and commits before the
239///   window ends. If it fails before the commit point, nothing was stored,
240///   for a closure that doesn't commit by itself. A closure that does (it
241///   calls `flush`, or a method that commits, such as `commit_deltas` or
242///   `restore_to`) and then fails gets [`MnemoError::MaybeStored`], saying
243///   part of the window is in the file. If the window's own commit fails
244///   after its commit point, the handle finishes the commit itself and
245///   returns `Ok`, or returns [`MnemoError::MaybeStored`]. If the file was
246///   renamed away during the commit, [`MnemoError::ReplacedDuringWrite`].
247///   Keep to one engine call per window where you can.
248/// - **Access statistics** a failed write window applied are dropped when
249///   its commit fails; they're statistics, and the next hits count again.
250/// - **Settings** that act on the whole file (snapshot retention, cache
251///   budgets, the cache flush policy, turn compression) are refused in
252///   v0.14 with [`MnemoError::Unsupported`], and so is `rekey` inside a
253///   closure (use [`SharedMnemo::rekey`], which also updates the secret the
254///   handle keeps). The page cache's size, the vector cache budget and the
255///   embedder (however it was set) are kept across reloads.
256/// - **A cancel** ([`SharedMnemo::set_cancel`]) reaches only a call that is
257///   waiting for a lock; once a call holds the lock it runs to its end.
258pub struct SharedMnemo {
259    locks: BrainLocks,
260    opts: SharedOptions,
261    path: PathBuf,
262    secret: Zeroizing<Vec<u8>>,
263    db: Option<Mnemo>,
264    /// `None` means "reload at the next call" (12.4 protocol step 7).
265    stamp: Option<Stamp>,
266    delta: AccessDelta,
267    embedder: Option<Arc<dyn Embedder>>,
268    reloads: u64,
269    /// What the last [`SharedMnemo::rekey`] couldn't scrub.
270    rekey_cleanup: Option<String>,
271}
272
273impl std::fmt::Debug for SharedMnemo {
274    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
275        f.debug_struct("SharedMnemo")
276            .field("path", &self.path)
277            .field("loaded", &self.db.is_some())
278            .field("reloads", &self.reloads)
279            .finish()
280    }
281}
282
283impl SharedMnemo {
284    fn open(path: &Path, secret: &[u8], opts: SharedOptions) -> Result<SharedMnemo> {
285        let locks = BrainLocks::new(path, &opts)?;
286        let mut s = SharedMnemo {
287            locks,
288            opts,
289            path: absolute(path.to_path_buf()),
290            secret: Zeroizing::new(secret.to_vec()),
291            db: None,
292            stamp: None,
293            delta: AccessDelta::default(),
294            embedder: None,
295            reloads: 0,
296            rekey_cleanup: None,
297        };
298        // Load now, so a wrong secret or an old format fails at open.
299        s.read(|_| Ok(()))?;
300        Ok(s)
301    }
302
303    /// Run `f` on the handle under the file's shared lock, after catching up
304    /// with any other process's commits. The handle is read-only inside;
305    /// recall's default access tracking works and is applied with this
306    /// handle's next write.
307    pub fn read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
308        self.window(LockKind::Shared, |s| s.run_read(f))
309    }
310
311    /// Run `f` on the handle under the file's exclusive lock, after catching
312    /// up, and commit before the lock is released. See [`SharedMnemo`] for
313    /// what each failure means.
314    ///
315    /// A closure that commits part of its work itself and then fails, or
316    /// then changes a setting, gets [`MnemoError::MaybeStored`]: the earlier
317    /// commit is in the file.
318    pub fn write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
319        self.window(LockKind::Exclusive, |s| s.run_write(f))
320    }
321
322    /// Attach an embedder (as [`Mnemo::set_embedder`]). It's kept across
323    /// reloads. When the file already records this embedder's identity,
324    /// this is a read window and writes nothing; otherwise the identity is
325    /// recorded in a write window.
326    pub fn set_embedder<E: Embedder + 'static>(&mut self, embedder: E) -> Result<()> {
327        let identity = embedder.identity();
328        let needs_write = self.read(move |db| {
329            if db.embedder_would_record(&identity)? {
330                return Ok(Some(embedder));
331            }
332            db.set_embedder(embedder)?;
333            Ok(None)
334        })?;
335        if let Some(embedder) = needs_write {
336            self.write(|db| db.set_embedder(embedder))?;
337        }
338        Ok(())
339    }
340
341    /// Change the passphrase (as [`Mnemo::rekey`], in a write window), and
342    /// replace the secret the handle keeps once the new one is in force, so
343    /// the handle can still follow a compaction or recover the file
344    /// afterwards. An error leaves the old secret in force and kept, unless
345    /// it says the file may open with either.
346    pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
347        self.rekey_secret(new_passphrase.as_bytes(), SecretKind::Passphrase, kdf)
348    }
349
350    /// [`SharedMnemo::rekey`] to a raw 256-bit key (as
351    /// [`Mnemo::rekey_with_key`]).
352    pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
353        self.rekey_secret(new_key, SecretKind::Key, KdfParams::raw_key())
354    }
355
356    /// After a successful [`SharedMnemo::rekey`], what couldn't be scrubbed
357    /// of the old key wrap (see [`Mnemo::rekey_cleanup_error`]).
358    pub fn rekey_cleanup_error(&self) -> Option<&str> {
359        self.rekey_cleanup.as_deref()
360    }
361
362    fn rekey_secret(&mut self, secret: &[u8], kind: SecretKind, kdf: KdfParams) -> Result<()> {
363        // The rekey window applies no statistics, so its only commit is the
364        // rekey's and its errors are the rekey's own; the next write applies
365        // them.
366        let held_back = std::mem::take(&mut self.delta);
367        let mut in_force = None;
368        let r = self.write(|db| {
369            db.rekey_unchecked(secret, kind, kdf, None)?;
370            in_force = Some(db.rekey_cleanup.clone());
371            Ok(())
372        });
373        self.delta = held_back;
374        if let Some(cleanup) = in_force {
375            self.secret = Zeroizing::new(secret.to_vec());
376            self.rekey_cleanup = cleanup;
377        }
378        r
379    }
380
381    /// Give the handle a new cancel token for its later calls, or none
382    /// (RB-007.1). A cancelled token stays cancelled, so after a cancel the
383    /// handle needs a new one (or `None`) to wait for a lock again. A cancel
384    /// reaches only a call that is waiting for a lock.
385    pub fn set_cancel(&mut self, token: Option<CancelToken>) {
386        self.opts.cancel = token;
387    }
388
389    /// The embedder attached to the handle, if any (shared, so a binding can
390    /// embed outside a window and then call [`SharedMnemo::write`]).
391    pub fn embedder_arc(&self) -> Option<Arc<dyn Embedder>> {
392        self.embedder.clone()
393    }
394
395    /// The warnings to show once: a sidecar directory that can't be used, a
396    /// synced folder, an allowed network filesystem.
397    pub fn notices(&self) -> &[String] {
398        self.locks.notices()
399    }
400
401    /// The handle's options: those it was opened with, and the cancel token
402    /// [`SharedMnemo::set_cancel`] gave it last.
403    pub fn options(&self) -> &SharedOptions {
404        &self.opts
405    }
406
407    /// Close the handle. It holds no lock between calls, so this only drops
408    /// what it kept: the secret (zeroized) and the access statistics no
409    /// write has applied yet.
410    pub fn close(self) -> Result<()> {
411        Ok(())
412    }
413
414    /// **Not a stable API** (failpoints builds only). How many times the
415    /// handle has rebuilt its state from the file.
416    #[cfg(any(test, feature = "failpoints"))]
417    #[doc(hidden)]
418    pub fn __reloads(&self) -> u64 {
419        self.reloads
420    }
421
422    /// **Not a stable API** (failpoints builds only). The page cache's
423    /// occupancy and capacity.
424    #[cfg(any(test, feature = "failpoints"))]
425    #[doc(hidden)]
426    pub fn __page_cache(&self) -> (usize, usize) {
427        self.db.as_ref().map_or((0, 0), |d| d.pager.cache_stats())
428    }
429
430    /// **Not a stable API** (failpoints builds only). The handle's state as
431    /// it stands, without a window (no lock, no catch-up): for tests that
432    /// look at what a failed call left in memory. No file is attached, so
433    /// only calls that stay in memory may be made; one that reads or
434    /// writes the file panics.
435    #[cfg(any(test, feature = "failpoints"))]
436    #[doc(hidden)]
437    pub fn __state(&mut self) -> Option<&mut Mnemo> {
438        self.db.as_mut()
439    }
440
441    /// One window: lock, catch up, run, unlock. One [`Call`], so one
442    /// deadline and one cancel token, covers every lock it takes.
443    fn window<R>(&mut self, kind: LockKind, run: impl FnOnce(&mut Self) -> Result<R>) -> Result<R> {
444        let mut call = Call::new(self.opts.deadline, self.opts.cancel.as_ref());
445        let mut lock = kind;
446        let held = loop {
447            let mut held = match self.locks.acquire(lock, &mut call) {
448                Ok(h) => h,
449                // A read that has to heal the file, which this process can
450                // only read.
451                Err(MnemoError::Io(e))
452                    if lock != kind && e.kind() == std::io::ErrorKind::PermissionDenied =>
453                {
454                    return Err(MnemoError::NeedsWriteOpen {
455                        reason: HEAL_NEEDS_WRITE,
456                    })
457                }
458                Err(e) => return Err(e),
459            };
460            let file = held.take_file();
461            match self.catch_up(lock, file)? {
462                Next::Ready => break held,
463                // A pending WAL or a torn page 0 under the shared lock:
464                // heal it under the exclusive one, then carry on.
465                Next::NeedExclusive => lock = LockKind::Exclusive,
466            }
467        };
468        // The pager now holds the call's locked file. Release it however
469        // `run` ends: a closure that panics, caught by the caller (UniFFI
470        // catches panics at its boundary, and so do thread pools and
471        // `catch_unwind`), must not leave the handle holding the lock. So
472        // the unwind is caught here, the lock released, and the panic
473        // resumed. A write window has cleared its stamp before running the
474        // closure, so the handle's next call reloads.
475        let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(self)));
476        // The lock-info note (if any) goes before the unlock.
477        drop(held);
478        if let Some(db) = self.db.as_mut() {
479            drop(db.pager.detach_file());
480            // An embedder set inside a closure is kept across reloads too
481            // (RB-007.8 item 4).
482            self.embedder = db.embedder.clone();
483        }
484        match r {
485            Ok(r) => r,
486            Err(panic) => {
487                // Whatever the closure left half done in memory, read or
488                // write, is reloaded by the next call (RB-007.8 item 6).
489                self.stamp = None;
490                std::panic::resume_unwind(panic)
491            }
492        }
493    }
494
495    /// 12.4 protocol steps 5 and 6 (the identity check of step 4 ran in the
496    /// lock layer): leave `self.db` current, holding `file`.
497    fn catch_up(&mut self, lock: LockKind, mut file: LockedFile) -> Result<Next> {
498        let header = match read_page0(&mut file)
499            .map_err(MnemoError::Io)
500            .and_then(|p| Header::from_page(&p))
501        {
502            Ok(h) => h,
503            // A torn page 0: the scan that heals it reads the whole file and
504            // runs the KDF per candidate, so never under the shared lock.
505            Err(_) if lock == LockKind::Shared => return Ok(Next::NeedExclusive),
506            Err(_) => return self.load(file),
507        };
508        let pending = wal::recover(
509            &mut file,
510            header.wal_start,
511            header.wal_pages,
512            header.wal_seq,
513        )?
514        .is_some();
515        if pending {
516            if lock == LockKind::Shared {
517                return Ok(Next::NeedExclusive);
518            }
519            // Replay, then always reload: the replay moved page 0 past the
520            // handle's state.
521            return self.load(file);
522        }
523        let stamp = Stamp::of(&file, &header);
524        if let (Some(db), Some(held)) = (self.db.as_mut(), self.stamp) {
525            if held == stamp {
526                db.pager.attach_file(file);
527                return Ok(Next::Ready);
528            }
529        }
530        // Another commit (the seal verifies under the key the handle
531        // holds): rebuild from the file without the KDF.
532        if let Some(old) = &self.db {
533            if header.validate_seal(old.pager.dek()).is_ok() {
534                let dek = Zeroizing::new(*old.pager.dek());
535                let kdf = KdfParams {
536                    m_cost: header.m_cost,
537                    t_cost: header.t_cost,
538                    p_cost: header.p_cost,
539                };
540                let new = Mnemo::from_locked(self.path.clone(), file, header, dek, kdf, false)?;
541                self.install(new);
542                return Ok(Next::Ready);
543            }
544        }
545        // The seal doesn't verify under the held key (a compaction's new
546        // data key, a file copied over this one) or nothing is loaded yet:
547        // open it with the kept secret, which returns the specific error
548        // (`WrongPassphrase`, `HeaderTampered`) if that fails too.
549        self.load(file)
550    }
551
552    /// The full open on the call's locked file (heal, replay), then install
553    /// it.
554    fn load(&mut self, file: LockedFile) -> Result<Next> {
555        let new = self.reopen(file)?;
556        self.install(new);
557        Ok(Next::Ready)
558    }
559
560    /// Open the call's locked file as `open` does (heal a torn page 0,
561    /// replay a pending WAL), with the data key the handle holds when the
562    /// header it would recover to verifies under it (no KDF), and the kept
563    /// secret otherwise (RB-007.2): a rekey by another process changes the
564    /// secret but not the data key.
565    fn reopen(&self, file: LockedFile) -> Result<Mnemo> {
566        let held = self.db.as_ref().map(|d| Zeroizing::new(*d.pager.dek()));
567        Mnemo::load_locked_with(
568            self.path.clone(),
569            file,
570            &self.secret,
571            held.as_deref(),
572            false,
573        )
574    }
575
576    /// Take `new` as the handle's state: carry over what is per-process (the
577    /// page cache's size, the vector cache budget, the embedder), and stamp
578    /// it.
579    fn install(&mut self, mut new: Mnemo) {
580        if let Some(old) = &self.db {
581            new.pager.set_cache_capacity(old.pager.cache_stats().1);
582            new.set_vector_cache_budget(old.vector_cache_budget);
583        }
584        if let Some(e) = &self.embedder {
585            new.embedder = Some(e.clone());
586        }
587        new.shared = true;
588        self.stamp = Some(Stamp::of(new.pager.file(), &new.header));
589        self.db = Some(new);
590        self.reloads += 1;
591    }
592
593    fn run_read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
594        let db = self.db.as_mut().expect("loaded by the window");
595        db.read_only = true;
596        db.access_delta = Some(std::mem::take(&mut self.delta));
597        let before = FileSettings::of(db);
598        let r = f(db);
599        db.read_only = false;
600        self.delta = db.access_delta.take().unwrap_or_default();
601        if FileSettings::of(db) != before {
602            self.stamp = None;
603            return Err(settings_refused());
604        }
605        r
606    }
607
608    fn run_write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
609        // Cleared before anything touches the handle's memory, set again
610        // only from a successful commit: an error, or a panic, leaves the
611        // next call to reload (protocol step 7).
612        self.stamp = None;
613        let db = self.db.as_mut().expect("loaded by the window");
614        db.read_only = false;
615        db.access_delta = None;
616        db.commit_point = None;
617        db.window_committed = false;
618        // No lease carries over from an earlier window. Every place that
619        // seals a page takes the lease first when it's missing
620        // (`ensure_gen_lease`), so every page this window seals carries a
621        // generation no other writer has used, even when windows interleave
622        // and one fails before its commit; and a window that seals nothing
623        // commits nothing (RB-007.6).
624        db.gen_leased = false;
625        let delta = std::mem::take(&mut self.delta);
626        db.apply_access_delta(&delta);
627        let before = FileSettings::of(db);
628        let r = f(db).map_err(in_shared_window);
629        let db = self.db.as_mut().expect("loaded by the window");
630        let r = match r {
631            Ok(r) => r,
632            // A commit inside the closure finished (RB-007.5), or got past
633            // its commit point, before the error: it may be in the file.
634            Err(e) if db.window_committed => return Err(part_stored(e)),
635            Err(e) if db.commit_point.is_some() => {
636                return Err(MnemoError::MaybeStored(e.to_string()))
637            }
638            Err(e) => {
639                self.delta = delta;
640                return Err(e);
641            }
642        };
643        if FileSettings::of(db) != before {
644            if db.window_committed || db.commit_point.is_some() {
645                return Err(part_stored(format!(
646                    "{SETTINGS_KEPT}, so the setting wasn't applied"
647                )));
648            }
649            self.delta = delta;
650            return Err(settings_refused());
651        }
652        let committed_before = db.window_committed;
653        #[cfg(any(test, feature = "failpoints"))]
654        crate::__failpoints::run_before_shared_commit();
655        if let Err(e) = db.flush().map_err(in_shared_window) {
656            match self.finish_failed_commit(e) {
657                Ok(()) => {}
658                Err(e @ MnemoError::MaybeStored(_)) => return Err(e),
659                Err(e) if committed_before => return Err(part_stored(e)),
660                Err(e) => return Err(e),
661            }
662        }
663        #[cfg(any(test, feature = "failpoints"))]
664        crate::__failpoints::run_after_shared_commit();
665        // Protocol step 8: the path must still name the file just written.
666        let db = self.db.as_ref().expect("loaded");
667        if !is_file_at(db.pager.file(), &db.path)? {
668            return Err(MnemoError::ReplacedDuringWrite {
669                path: db.path.clone(),
670            });
671        }
672        self.stamp = Some(Stamp::of(db.pager.file(), &db.header));
673        Ok(r)
674    }
675
676    /// A commit failed (protocol step 7). Before the WAL's commit point,
677    /// nothing was stored: return the error. After it, finish the commit
678    /// from the WAL (the same replay an open does) and return `Ok` if the
679    /// transaction is in the file, or [`MnemoError::MaybeStored`] if that
680    /// can't be found out.
681    fn finish_failed_commit(&mut self, e: MnemoError) -> Result<()> {
682        let db = self.db.as_mut().expect("loaded");
683        let Some(txn) = db.commit_point.take() else {
684            return Err(e);
685        };
686        let Some(mut file) = db.pager.detach_file() else {
687            return Err(MnemoError::MaybeStored(e.to_string()));
688        };
689        // Replay a pending transaction here, through the write failpoint,
690        // so a test can fail this step too; `load_locked` then finds the
691        // file current (or heals a torn page 0 itself).
692        let replay = (|| -> Result<()> {
693            let Ok(header) = read_page0(&mut file)
694                .map_err(MnemoError::Io)
695                .and_then(|p| Header::from_page(&p))
696            else {
697                return Ok(());
698            };
699            if let Some(frames) = wal::recover(
700                &mut file,
701                header.wal_start,
702                header.wal_pages,
703                header.wal_seq,
704            )? {
705                for (page_no, bytes) in &frames {
706                    crate::pager::__failpoint_check()?;
707                    file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
708                    file.write_all(bytes)?;
709                }
710                file.sync_all()?;
711                crate::bump_fsync();
712            }
713            Ok(())
714        })();
715        if let Err(e2) = replay {
716            return Err(MnemoError::MaybeStored(format!(
717                "{e}; finishing the commit failed too: {e2}"
718            )));
719        }
720        match self.reopen(file) {
721            Ok(new) => {
722                let stored = new.header.wal_seq >= txn;
723                self.install(new);
724                if stored {
725                    Ok(())
726                } else {
727                    // The commit never became durable: nothing was stored,
728                    // and the handle now holds the file as it is.
729                    self.stamp = None;
730                    Err(e)
731                }
732            }
733            Err(e2) => Err(MnemoError::MaybeStored(format!(
734                "{e}; reading the file back failed: {e2}"
735            ))),
736        }
737    }
738}
739
740/// A commit's pre-write identity check (`Mnemo::ensure_not_replaced`) inside
741/// a write window: the rename came after the window's own identity check
742/// (protocol step 4), from something renaming without the lock (an older
743/// build's compaction). Nothing was written, and the stamp is already
744/// cleared, so the next call follows the new file: say that instead of the
745/// plain handle's "reopen it".
746fn in_shared_window(e: MnemoError) -> MnemoError {
747    match e {
748        MnemoError::Replaced { path, missing, .. } => MnemoError::Replaced {
749            path,
750            shared: true,
751            missing,
752        },
753        e => e,
754    }
755}