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