mnemo_engine/lib.rs
1//! # Mnemo
2//!
3//! Mnemo is an **encrypted, single-file, portable agent-memory engine**.
4//!
5//! A whole memory store — vectors, content, metadata, and the multi-signal
6//! recall machinery an agent needs — lives in one file you can copy, back up,
7//! or hand to another process. The file is encrypted at rest with a two-tier
8//! key hierarchy: an Argon2id key-encryption key (KEK) derived from a
9//! passphrase wraps a random data-encryption key (DEK), and the DEK encrypts
10//! every page with AES-256-GCM.
11//!
12//! ## Quick start
13//!
14//! ```no_run
15//! use mnemo_engine::{Mnemo, MnemoConfig, Memory, MemoryType, RecallRequest};
16//!
17//! # fn main() -> mnemo_engine::Result<()> {
18//! let cfg = MnemoConfig { dimensions: 3, ..Default::default() };
19//! let mut db = Mnemo::create("agent.mnemo", "correct horse battery", cfg)?;
20//!
21//! db.remember(
22//! Memory::new("the user prefers dark mode", MemoryType::Semantic, vec![0.1, 0.2, 0.9])
23//! .with_agent("assistant-1")
24//! .with_importance(0.8),
25//! )?;
26//! db.flush()?;
27//!
28//! let hits = db.recall(&RecallRequest::new(vec![0.1, 0.2, 0.9]).top_k(5))?;
29//! for h in hits {
30//! println!("{:.3} {}", h.score, h.memory.content);
31//! }
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! ## What is and is not built
37//!
38//! This crate implements a real, tested core: the encrypted single-file
39//! storage engine, the crypto layer, the agent-memory model, multi-signal
40//! recall, an IVF+PQ approximate-nearest-neighbour index, a write-ahead log,
41//! snapshot-based point-in-time recovery, a bounded LRU page cache, and the
42//! [`Session`] conversation wrapper. Exact brute-force search remains
43//! available as the ground-truth baseline; a built index makes
44//! [`Mnemo::recall`] sub-linear. Each [`Mnemo::flush`] is one atomic,
45//! WAL-committed transaction and a restorable snapshot — [`Mnemo::restore_to`]
46//! rewinds the database to any past transaction. Python and TypeScript
47//! language bindings are the one documented roadmap item — see the README.
48
49#![forbid(unsafe_code)]
50#![warn(missing_docs)]
51// Since step 5a (MSRV 1.92, now 1.94): `as_chunks` (stable since 1.88) is within the
52// MSRV, so clippy suggests it for every constant-size `chunks_exact`. Those
53// are the hot kernels (PQ distance tables, fp16 vectors, the WAL checksum);
54// rewriting them waits for a change that measures them with the benches.
55// `unknown_lints` first, so a clippy older than the lint (before 1.100)
56// doesn't fail on its name.
57#![allow(unknown_lints)]
58#![allow(clippy::chunks_exact_to_as_chunks)]
59
60/// 12.3 step 5 (v0.15): the built-in embedder (snowflake-arctic-embed-xs on
61/// candle), behind the `embed-candle` feature.
62#[cfg(feature = "embed-candle")]
63pub mod builtin;
64mod cache;
65mod crypto;
66mod embed;
67mod embed_cmd;
68mod error;
69mod format;
70mod freelist;
71mod ident;
72mod index;
73pub mod keys;
74mod keyslot;
75pub mod mcp;
76mod memory;
77mod pager;
78mod result_cache;
79mod session;
80mod shared;
81mod store;
82mod text;
83mod transcript;
84mod veccol;
85mod wal;
86
87#[cfg(feature = "embed-candle")]
88pub use builtin::BuiltinEmbedder;
89pub use crypto::{KdfParams, SecretKind};
90pub use embed::{Embedder, EmbedderIdentity};
91pub use embed_cmd::{EmbedCmd, DEFAULT_EMBED_TIMEOUT};
92pub use error::{MnemoError, Result};
93pub use index::{IndexConfig, IndexInfo};
94pub use memory::{
95 status as essence_status, CommitBatch, CommitReport, EssenceOp, EssenceOpKind, EssenceScope,
96 EssenceSection, ExportedTurn, Filter, FilterTerm, IngestReport, KeyScope, KeyedMemory, Memory,
97 MemoryPatch, MemoryType, Metric, Scope, ScoreWeights, ThreadTurn, TurnPolicy, WriteOutcome,
98 CONTINUATION_TIMELINE_ENTRIES, ESSENCE_DEFAULT_RENDER_BYTES, ESSENCE_SECTION_MAX_BYTES,
99 ESSENCE_TIMELINE_MAX_BYTES, ESSENCE_TRANSITIONS, FINDING_TRANSITIONS, MNEMO_META_CONTINUES,
100 MNEMO_META_INVALID_AT, MNEMO_META_KEY, MNEMO_META_KIND, MNEMO_META_KIND_ESSENCE,
101 MNEMO_META_KIND_THREAD_LINK, MNEMO_META_KIND_TURN, MNEMO_META_LENGTH, MNEMO_META_NS,
102 MNEMO_META_PART, MNEMO_META_REFS, MNEMO_META_ROLE, MNEMO_META_SECTION, MNEMO_META_SEQ,
103 MNEMO_META_SHA256, MNEMO_META_STATUS, MNEMO_META_STATUS_HISTORY, MNEMO_META_SUPERSEDED_BY,
104 MNEMO_META_SUPERSEDES, MNEMO_META_THREAD, MNEMO_META_TURN_ID, MNEMO_META_UPDATED_AT,
105 TASK_TRANSITIONS, THREAD_TOOL_RESULT_TRUNCATE_BYTES, THREAD_TURN_CHUNK_BYTES,
106};
107pub use result_cache::{
108 CacheBudget, CacheFlushPolicy, CachePutOpts, CacheStats, CachedValue, SemanticCachePutOpts,
109 DEFAULT_BATCH_MAX_AGE, DEFAULT_BATCH_MAX_DIRTY, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES,
110 DEFAULT_SEMANTIC_THRESHOLD,
111};
112pub use session::{Role, Session, Turn};
113pub use shared::{CancelToken, SharedOptions};
114#[doc(hidden)]
115#[cfg(feature = "dev-hooks")]
116pub use store::BudgetReport;
117pub use store::{
118 CloseError, CompactReport, Mnemo, MnemoConfig, RecallMode, RecallRequest, RecallResponse,
119 RecallResult, ReembedReport, SharedMnemo, SnapshotInfo, Stats, StatsSummary, VerifyReport,
120 DEFAULT_KEYWORD_WEIGHT, DEFAULT_TEXT_KEYWORD_WEIGHT, DEFAULT_TURN_COMPRESS_AFTER_SECS,
121 DEFAULT_VECTOR_CACHE_BUDGET, INDEX_PERSIST_EVERY_CHANGES, INDEX_PERSIST_EVERY_COMMITS,
122 V9_ANN_MIN_FACTS, V9_RERANK_PER_HIT,
123};
124pub use text::{KeywordIndex, KeywordTokenizer};
125pub use transcript::{read_transcript, TranscriptFormat};
126
127/// Re-export of [`ulid::Ulid`], the identifier type used for memories.
128pub use ulid::Ulid;
129
130// --- Fsync counter -----------------------------------------------------
131//
132// Instrumentation plumbing for the Phase 6 top-3 cost #2 fix: the
133// planner wants to know how many `sync_all` calls each `flush()` issues
134// before deciding whether to batch any of them. Every fsync call site
135// bumps a thread-local counter; `Mnemo::flush` snapshots it before and
136// after, exposing the delta on `Stats::fsyncs_last_flush`. Thread-local
137// so handles on separate threads don't poison each other's counts; the
138// engine's one-writer-at-a-time locking means a single handle sees a
139// coherent stream.
140
141mod fsync_counter {
142 use std::cell::Cell;
143
144 thread_local! {
145 static COUNT: Cell<u64> = const { Cell::new(0) };
146 }
147
148 /// Call once per `sync_all`.
149 pub(crate) fn bump() {
150 COUNT.with(|c| c.set(c.get().wrapping_add(1)));
151 }
152
153 /// Monotonic counter snapshot for this thread.
154 pub(crate) fn count() -> u64 {
155 COUNT.with(|c| c.get())
156 }
157}
158
159pub(crate) use fsync_counter::{bump as bump_fsync, count as fsync_count};
160
161/// Build-time cryptographic backend information.
162///
163/// Populated at compile time from the active `cfg` flags. On ARMv8
164/// builds compiled with `--cfg aes_armv8 --cfg polyval_armv8` (set by
165/// the repo's `.cargo/config.toml` and both CI workflows) the `aes`
166/// and `polyval` crates emit hardware AES + PMULL instructions; without
167/// those flags they fall back to a constant-time software path that
168/// runs at roughly 5× the cost per page.
169///
170/// Published through [`build_info`], exposed by `mnemo info` on the
171/// CLI and `mnemo.build_info()` from the Python binding. The point is
172/// verification — nobody should have to profile a release build to find
173/// out whether it's running software AES.
174#[derive(Debug, Clone, Copy, PartialEq, Eq)]
175pub struct BuildInfo {
176 /// Package version (`CARGO_PKG_VERSION`), e.g. `"0.5.1"`.
177 pub version: &'static str,
178 /// Target triple this binary was built for, e.g.
179 /// `"aarch64-apple-darwin"`.
180 pub target: &'static str,
181 /// Human-readable AES backend. One of:
182 /// - `"armv8 hardware"` — ARM with `cfg(aes_armv8)`
183 /// - `"armv8 software"` — ARM without the cfg; constant-time fallback
184 /// - `"x86_64 AES-NI (runtime detect)"` — x86_64 with runtime
185 /// AES-NI detection in the `aes` crate
186 /// - `"portable software"` — any other target
187 pub aes_backend: &'static str,
188 /// Human-readable PMULL/CLMUL backend used by GHASH (part of AES-GCM).
189 /// Same shape as `aes_backend` but for `polyval`.
190 pub polyval_backend: &'static str,
191}
192
193/// Report this build's cryptographic backend configuration.
194///
195/// Cheap — all fields are `&'static str` populated at compile time.
196/// Safe to call from a hot path if, for some reason, that's useful.
197pub fn build_info() -> BuildInfo {
198 BuildInfo {
199 version: env!("CARGO_PKG_VERSION"),
200 target: TARGET_TRIPLE,
201 aes_backend: aes_backend_name(),
202 polyval_backend: polyval_backend_name(),
203 }
204}
205
206/// Target triple baked in via the `TARGET` env var that `cargo` sets
207/// for the host compile. Falls back to `"unknown"` if the var isn't
208/// set at build time (shouldn't happen under cargo, but a build.rs-free
209/// implementation keeps this crate build-script-free, so we use a
210/// cfg-based dispatch as the second-best).
211const TARGET_TRIPLE: &str = {
212 // `env!("TARGET")` isn't set by cargo for crates; it's set by rustc
213 // only for `std` builds. We approximate from `target_arch` /
214 // `target_os` cfgs so this stays build-script-free. Good enough
215 // for an info line; precise triples are a `cargo` or build.rs job.
216 if cfg!(all(target_arch = "aarch64", target_os = "macos")) {
217 "aarch64-apple-darwin"
218 } else if cfg!(all(target_arch = "aarch64", target_os = "linux")) {
219 "aarch64-unknown-linux-gnu"
220 } else if cfg!(all(target_arch = "x86_64", target_os = "macos")) {
221 "x86_64-apple-darwin"
222 } else if cfg!(all(target_arch = "x86_64", target_os = "linux")) {
223 "x86_64-unknown-linux-gnu"
224 } else if cfg!(all(target_arch = "x86_64", target_os = "windows")) {
225 "x86_64-pc-windows-msvc"
226 } else {
227 "unknown"
228 }
229};
230
231const fn aes_backend_name() -> &'static str {
232 if cfg!(aes_armv8) {
233 "armv8 hardware"
234 } else if cfg!(target_arch = "aarch64") {
235 // Software fallback is the dangerous case this whole mechanism
236 // exists to surface — flag it clearly so `mnemo info` makes it
237 // easy to notice a build picked up the slow path by mistake.
238 "armv8 software (constant-time fallback)"
239 } else if cfg!(target_arch = "x86_64") {
240 // `aes` 0.8.4 on x86_64 picks AES-NI vs the software path at
241 // runtime via the `cpufeatures` crate, so we can't tell from
242 // cfg alone which path a given invocation takes. In practice
243 // every x86_64 CPU shipped since ~2010 has AES-NI.
244 "x86_64 AES-NI (runtime detect)"
245 } else {
246 "portable software"
247 }
248}
249
250const fn polyval_backend_name() -> &'static str {
251 if cfg!(polyval_armv8) {
252 "armv8 PMULL hardware"
253 } else if cfg!(target_arch = "aarch64") {
254 "armv8 software (constant-time fallback)"
255 } else if cfg!(target_arch = "x86_64") {
256 "x86_64 CLMUL (runtime detect)"
257 } else {
258 "portable software"
259 }
260}
261
262/// **Not a stable API** (`dev-hooks` builds only): how many `sync_all`
263/// calls this thread has made, for step 5's bench to count a write's
264/// fsyncs.
265#[cfg(feature = "dev-hooks")]
266#[doc(hidden)]
267pub fn __fsync_count() -> u64 {
268 fsync_count()
269}
270
271/// Test-only crash-injection surface used by the Phase 1.3 proptest
272/// (`mnemo/tests/proptest_store.rs`). Compiled in under `cfg(test)`
273/// and the `failpoints` feature only; absent from release builds.
274///
275/// **Not part of the stable public API.** The double-underscore
276/// convention makes the "internal" contract obvious at the call site.
277#[cfg(any(test, feature = "failpoints"))]
278#[doc(hidden)]
279pub mod __failpoints {
280 /// Arm the pager and WAL commit path to fail on the Nth
281 /// subsequent write. `n = 0` fails the very next write; `n = -1`
282 /// (or any negative) disables. One-shot — disarms on trigger.
283 ///
284 /// Every write is checked before the byte hits the file, so a
285 /// triggered failure is guaranteed torn-BEFORE, never
286 /// torn-AFTER — critical for the "either pre-flush or post-flush"
287 /// invariant the property test asserts.
288 pub fn set_writes_until_fail(n: i64) {
289 crate::pager::failpoints::set_writes_until_fail(n)
290 }
291
292 /// Like [`set_writes_until_fail`], but `count` writes in a row fail.
293 pub fn set_writes_until_fail_n(n: i64, count: u32) {
294 crate::pager::failpoints::set_writes_until_fail_n(n, count)
295 }
296
297 /// Fail exactly the writes numbered in `ns` (from 0, counting from this
298 /// call), consecutive or not; an empty set disarms it.
299 pub fn set_writes_failing(ns: &[u64]) {
300 crate::pager::failpoints::set_writes_failing(ns)
301 }
302
303 /// How many writes this thread has made since the last
304 /// [`set_writes_failing`].
305 pub fn writes_seen() -> u64 {
306 crate::pager::failpoints::writes_seen()
307 }
308
309 thread_local! {
310 static AFTER_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
311 const { std::cell::RefCell::new(None) };
312 static BEFORE_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
313 const { std::cell::RefCell::new(None) };
314 }
315
316 /// Run `f` once, inside this thread's next shared-mode write, after the
317 /// window's closure and before the window's commit (so after the
318 /// window's identity check, 12.4 protocol step 4). Lets a test rename a
319 /// file over the path the way an older build's compaction can.
320 pub fn before_next_shared_commit(f: impl FnOnce() + 'static) {
321 BEFORE_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
322 }
323
324 pub(crate) fn run_before_shared_commit() {
325 if let Some(f) = BEFORE_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
326 f();
327 }
328 }
329
330 /// Run `f` once, inside this thread's next shared-mode write, after its
331 /// commit and before the identity check that follows (12.4 protocol
332 /// step 8). Lets a test rename a file over the path at that moment.
333 pub fn after_next_shared_commit(f: impl FnOnce() + 'static) {
334 AFTER_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
335 }
336
337 pub(crate) fn run_after_shared_commit() {
338 if let Some(f) = AFTER_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
339 f();
340 }
341 }
342
343 thread_local! {
344 static NEXT_TEMP_NAME: std::cell::RefCell<Option<std::path::PathBuf>> =
345 const { std::cell::RefCell::new(None) };
346 }
347
348 /// Make the next temp file name this thread asks for (compaction,
349 /// `export_encrypted`, `export_rekeyed`) be `path`, once; the attempts
350 /// after it are generated as usual. Lets a test plant a file or a
351 /// symlink at the exact name the engine is about to use.
352 pub fn set_next_temp_name(path: impl Into<std::path::PathBuf>) {
353 NEXT_TEMP_NAME.with(|n| *n.borrow_mut() = Some(path.into()));
354 }
355
356 pub(crate) fn take_next_temp_name() -> Option<std::path::PathBuf> {
357 NEXT_TEMP_NAME.with(|n| n.borrow_mut().take())
358 }
359
360 thread_local! {
361 static SHARED_MAIN_TRIES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
362 static SHARED_REPLACED: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
363 }
364
365 /// How many times this thread's shared-mode calls have tried the main
366 /// lock (each open, lock and identity check counts once).
367 pub fn shared_main_tries() -> u64 {
368 SHARED_MAIN_TRIES.with(|c| c.get())
369 }
370
371 pub(crate) fn count_shared_main_try() {
372 SHARED_MAIN_TRIES.with(|c| c.set(c.get() + 1));
373 }
374
375 /// Make this thread's next `n` shared-mode tries at the main lock find
376 /// the file replaced (as if a compaction renamed a new file over the
377 /// path between the open and the lock each time). `0` disarms.
378 pub fn set_shared_replaced(n: u64) {
379 SHARED_REPLACED.with(|c| c.set(n));
380 }
381
382 thread_local! {
383 static EUID_OVERRIDE: std::cell::Cell<Option<u32>> = const { std::cell::Cell::new(None) };
384 }
385
386 /// Make this thread's file-owner checks (the dead compaction temp
387 /// files' cleanup) compare against `uid` instead of the effective uid,
388 /// so a test can see a file as another user's without root. `None`
389 /// restores the real check.
390 pub fn set_euid_override(uid: Option<u32>) {
391 EUID_OVERRIDE.with(|c| c.set(uid));
392 }
393
394 // Read by the Unix owner check only.
395 #[cfg(unix)]
396 pub(crate) fn euid_override() -> Option<u32> {
397 EUID_OVERRIDE.with(|c| c.get())
398 }
399
400 thread_local! {
401 static PATH_CHECK_FAILURES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
402 }
403
404 /// Make this thread's next `n` checks that a handle's path still names
405 /// its open file fail with a permission error (RB-008.2), as when the
406 /// process has lost access to the path. `0` disarms.
407 pub fn set_path_check_failures(n: u64) {
408 PATH_CHECK_FAILURES.with(|c| c.set(n));
409 }
410
411 /// How many armed path-check failures this thread has left.
412 pub fn path_check_failures_left() -> u64 {
413 PATH_CHECK_FAILURES.with(|c| c.get())
414 }
415
416 pub(crate) fn take_path_check_failure() -> bool {
417 PATH_CHECK_FAILURES.with(|c| {
418 let n = c.get();
419 if n > 0 {
420 c.set(n - 1);
421 }
422 n > 0
423 })
424 }
425
426 pub(crate) fn take_shared_replaced() -> bool {
427 SHARED_REPLACED.with(|c| {
428 let n = c.get();
429 if n > 0 {
430 c.set(n - 1);
431 }
432 n > 0
433 })
434 }
435}
436
437/// 12.4 step 2a: the shared lock layer, reached directly by its tests
438/// (`tests/shared_lock.rs`) until `Mnemo::open_shared` (step 2b) wraps it.
439/// Compiled in under `cfg(test)` and the `failpoints` feature only.
440///
441/// **Not part of the stable public API.**
442#[cfg(any(test, feature = "failpoints"))]
443#[doc(hidden)]
444pub mod __shared {
445 use std::path::{Path, PathBuf};
446
447 use crate::shared::{BrainLocks, Call, Held, LockKind};
448 use crate::{Result, SharedOptions};
449
450 /// The sidecar directory's suffix and its two file names.
451 pub const SUFFIX: &str = crate::shared::testing::SUFFIX;
452 pub const INTENT: &str = crate::shared::testing::INTENT;
453 pub const LOCK_INFO: &str = crate::shared::testing::LOCK_INFO;
454 /// LOCK-2's valve file name.
455 pub const VALVE: &str = crate::shared::testing::VALVE;
456
457 /// Whether this build refuses shared mode (Windows, Rust before 1.85).
458 pub const WINDOWS_OLD_RENAME: bool = crate::shared::WINDOWS_OLD_RENAME;
459
460 /// `<brain>.mnemo-shared` for a resolved brain path.
461 pub fn sidecar_path(brain: &Path) -> PathBuf {
462 crate::shared::testing::sidecar_path(brain)
463 }
464
465 /// The macOS synced-folder rule, as a pure function.
466 pub fn classify_synced(path: &Path, home: &Path) -> Option<String> {
467 crate::shared::testing::classify_synced(path, home)
468 }
469
470 /// Whether a Linux `statfs` magic number is allowed.
471 pub fn linux_fs_allowed(magic: u32) -> bool {
472 crate::shared::testing::linux_fs_allowed(magic)
473 }
474
475 /// The lock layer for one brain.
476 #[derive(Debug)]
477 pub struct Locks(BrainLocks);
478
479 impl Locks {
480 pub fn new(path: &Path, opts: &SharedOptions) -> Result<Self> {
481 BrainLocks::new(path, opts).map(Locks)
482 }
483 /// A plain long operation's layer, which never creates the sidecar.
484 pub fn for_plain(path: &Path, opts: &SharedOptions) -> Result<Self> {
485 BrainLocks::for_plain(path, opts).map(Locks)
486 }
487 /// LOCK-2: how many times this layer's writers took the valve.
488 pub fn valve_takes(&self) -> u64 {
489 self.0.valve_takes()
490 }
491 pub fn shared(&mut self, opts: &SharedOptions) -> Result<Lock> {
492 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
493 self.0.acquire(LockKind::Shared, &mut call).map(Lock)
494 }
495 pub fn exclusive(&mut self, opts: &SharedOptions) -> Result<Lock> {
496 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
497 self.0.acquire(LockKind::Exclusive, &mut call).map(Lock)
498 }
499 pub fn has_sidecar(&self) -> bool {
500 self.0.has_sidecar()
501 }
502 pub fn sidecar_path(&self) -> Option<PathBuf> {
503 self.0.sidecar_path().map(Path::to_path_buf)
504 }
505 pub fn notices(&self) -> Vec<String> {
506 self.0.notices().to_vec()
507 }
508 }
509
510 /// One call's main lock; dropping it unlocks.
511 pub struct Lock(Held);
512
513 impl Lock {
514 pub fn announce(&mut self, op: &str) {
515 self.0.announce(op)
516 }
517 pub fn file(&self) -> &std::fs::File {
518 self.0.file()
519 }
520 }
521}
522
523/// WAL entry points for the PERF-1 allocation test
524/// (`tests/wal_recover_alloc.rs`), which needs its own global allocator and
525/// so can't live in this `forbid(unsafe_code)` crate. Not a stable API.
526#[doc(hidden)]
527pub mod __wal {
528 /// Page size of the WAL region.
529 pub const PAGE_SIZE: usize = crate::format::PAGE_SIZE;
530
531 /// One WAL frame: a home page number and its page image.
532 pub type Frame = (u64, Vec<u8>);
533
534 /// Bytes a transaction of `n` page frames occupies.
535 pub fn txn_byte_len(n: usize) -> u64 {
536 crate::wal::txn_byte_len(n, PAGE_SIZE)
537 }
538
539 /// Commit `frames` as transaction `txn_id` at the start of a region.
540 pub fn commit(
541 file: &mut std::fs::File,
542 wal_pages: u64,
543 txn_id: u64,
544 frames: &[Frame],
545 ) -> crate::Result<()> {
546 crate::wal::commit(file, 0, wal_pages, txn_id, frames)
547 }
548
549 /// Run open-time recovery over a region starting at page 0; returns the
550 /// frames to replay, if any.
551 pub fn recover(
552 file: &mut std::fs::File,
553 wal_pages: u64,
554 wal_seq: u64,
555 ) -> crate::Result<Option<Vec<Frame>>> {
556 crate::wal::recover(file, 0, wal_pages, wal_seq)
557 }
558}
559
560/// Internal parse surfaces exposed for cargo-fuzz targets (Phase 1.2).
561///
562/// **Not part of the stable public API.** Each function feeds an
563/// arbitrary byte slice into a parse/decode path that a hostile
564/// `.mnemo` file (or a hostile MCP client) can send us, and returns
565/// `Result<()>` so a fuzz target only asserts "no panic." Marked
566/// `#[doc(hidden)]` so `cargo doc` doesn't advertise it; do not import
567/// from application code.
568#[doc(hidden)]
569pub mod __fuzz {
570 /// Parse a `.mnemo` header page (page 0, plaintext) from arbitrary
571 /// bytes. This is the pre-passphrase attack surface — a hostile
572 /// file hits it before any DEK exists.
573 pub fn parse_header(bytes: &[u8]) -> crate::Result<()> {
574 crate::format::Header::from_page(bytes).map(|_| ())
575 }
576
577 /// Replay the WAL scan over an arbitrary byte region. Delegates
578 /// to [`crate::wal::recover_bytes`]; a corrupt / truncated /
579 /// adversarial region must return `Err` or `Ok(None/Some(_))`,
580 /// never panic.
581 pub fn wal_recover_bytes(region: &[u8], wal_seq: u64) -> crate::Result<()> {
582 crate::wal::recover_bytes(region, wal_seq).map(|_| ())
583 }
584
585 /// Decode a `Memory` record body from arbitrary bytes.
586 pub fn decode_memory(bytes: &[u8]) -> crate::Result<()> {
587 rmp_serde::from_slice::<crate::Memory>(bytes)
588 .map(|_| ())
589 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
590 }
591
592 /// FMT-9e: decode a v9 `Memory` record body from arbitrary bytes: a
593 /// zstd frame (a compressed thread turn) is decompressed first, under
594 /// the same content-size bound the store applies.
595 pub fn decode_v9_memory(bytes: &[u8]) -> crate::Result<()> {
596 let plain = crate::store::plain_record(bytes)?;
597 rmp_serde::from_slice::<crate::Memory>(&plain)
598 .map(|_| ())
599 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
600 }
601
602 /// Decode a `CacheEntry` record body from arbitrary bytes. Type is
603 /// `pub(crate)`, so this wrapper hides it behind a unit return.
604 pub fn decode_cache_entry(bytes: &[u8]) -> crate::Result<()> {
605 rmp_serde::from_slice::<crate::result_cache::CacheEntry>(bytes)
606 .map(|_| ())
607 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
608 }
609
610 /// Decode a cache-directory page-run body (a `Vec<CacheDirectoryEntry>`)
611 /// from arbitrary bytes.
612 pub fn decode_cache_directory(bytes: &[u8]) -> crate::Result<()> {
613 rmp_serde::from_slice::<Vec<crate::result_cache::CacheDirectoryEntry>>(bytes)
614 .map(|_| ())
615 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
616 }
617
618 /// Parse a single MCP stdio JSON-RPC request line. Malformed
619 /// input returns `Err(String)`; the fuzz target only asserts
620 /// no panic and that the server would not die on this line.
621 pub fn parse_mcp_request_line(line: &str) -> Result<(), String> {
622 crate::mcp::__fuzz_parse_request_line(line)
623 }
624}