Skip to main content

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;
71pub mod guide;
72mod ident;
73mod index;
74pub mod keys;
75mod keyslot;
76pub mod mcp;
77mod memory;
78mod pager;
79pub mod redact;
80mod result_cache;
81mod session;
82mod shared;
83mod store;
84mod text;
85mod transcript;
86mod veccol;
87mod wal;
88
89#[cfg(feature = "embed-candle")]
90pub use builtin::BuiltinEmbedder;
91pub use crypto::{KdfParams, SecretKind};
92pub use embed::{Embedder, EmbedderIdentity};
93pub use embed_cmd::{EmbedCmd, DEFAULT_EMBED_TIMEOUT};
94pub use error::{MnemoError, Result};
95pub use index::{IndexConfig, IndexInfo};
96/// 13a: the coordination kinds and the reserved keys a caller may set.
97pub use memory::{
98    check_caller_key, is_caller_key, is_coordination, valid_agent_id, CALLER_KEYS,
99    COORDINATION_KINDS, MNEMO_META_AS_OF, MNEMO_META_AUTHOR, MNEMO_META_DEFAULT_AGENT,
100    MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_MESSAGE, MNEMO_META_KIND_PRESENCE, MNEMO_META_KIND_TASK,
101    MNEMO_META_REVIEW_BY, MNEMO_META_VISIBILITY, VISIBILITY_LEVELS,
102};
103/// 13a (13.5, 13.6): visibility and freshness.
104pub use memory::{date_of, stale_after, stale_since, visibility_of, VisibilitySet};
105/// 13a (13.1): messages between agents.
106pub use memory::{
107    delivery, MESSAGE_ACKED, MESSAGE_ACKED_KEEP_SECS, MESSAGE_BODY_MAX, MESSAGE_PAIR_CARRY_SECS,
108    MESSAGE_SUBJECT_MAX, MESSAGE_UNREAD, MNEMO_META_ACKED_AT, MNEMO_META_CONVERSATION,
109    MNEMO_META_DELIVERY, MNEMO_META_FROM, MNEMO_META_HOPS, MNEMO_META_TO,
110};
111/// v0.18.0 (13a step 8b): review findings.
112pub use memory::{
113    finding_status, FINDING_BODY_MAX, FINDING_CATEGORIES, FINDING_PRIORITIES, FINDING_TITLE_MAX,
114    MNEMO_META_BATCH, MNEMO_META_CATEGORY, MNEMO_META_FINDING_ID, MNEMO_META_KIND_FINDING,
115    MNEMO_META_PRIORITY, MNEMO_META_TRIAGE, MNEMO_META_TRIAGED_BY, MNEMO_META_VERIFIED_BY,
116    MNEMO_META_VERIFIED_REF,
117};
118pub use memory::{
119    status as essence_status, CommitBatch, CommitReport, EssenceOp, EssenceOpKind, EssenceScope,
120    EssenceSection, ExportedTurn, Filter, FilterTerm, IngestReport, KeyScope, KeyedMemory, Memory,
121    MemoryPatch, MemoryType, Metric, Scope, ScoreWeights, ThreadTurn, TurnPolicy, WriteOutcome,
122    CONTINUATION_TIMELINE_ENTRIES, ESSENCE_DEFAULT_RENDER_BYTES, ESSENCE_SECTION_MAX_BYTES,
123    ESSENCE_TIMELINE_MAX_BYTES, ESSENCE_TRANSITIONS, FINDING_TRANSITIONS, MNEMO_META_CONTINUES,
124    MNEMO_META_INVALID_AT, MNEMO_META_KEY, MNEMO_META_KIND, MNEMO_META_KIND_ESSENCE,
125    MNEMO_META_KIND_THREAD_LINK, MNEMO_META_KIND_TURN, MNEMO_META_LENGTH, MNEMO_META_MARKERS_ONLY,
126    MNEMO_META_NS, MNEMO_META_PART, MNEMO_META_REFS, MNEMO_META_ROLE, MNEMO_META_SECTION,
127    MNEMO_META_SEQ, MNEMO_META_SHA256, MNEMO_META_STATUS, MNEMO_META_STATUS_HISTORY,
128    MNEMO_META_SUPERSEDED_BY, MNEMO_META_SUPERSEDES, MNEMO_META_THREAD, MNEMO_META_TURN_ID,
129    MNEMO_META_UPDATED_AT, TASK_TRANSITIONS, THREAD_TOOL_RESULT_TRUNCATE_BYTES,
130    THREAD_TURN_CHUNK_BYTES,
131};
132/// 13a (13.1): tasks.
133pub use memory::{
134    task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_OWNER, MNEMO_META_PRE_APPROVED,
135    MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_CLAIM_WARN_SECS, TASK_DONE_EXPORT_KEEP_SECS,
136    TASK_SLUG_MAX,
137};
138/// 13a (13.3): claims and presence.
139pub use memory::{
140    CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
141    PRESENCE_EVERY_SECS,
142};
143/// 13a (13.1b): the wake-up guardrails.
144pub use memory::{
145    HOP_CAP, MNEMO_META_WAKE_PAUSED, PAIR_BURST, PAIR_BURST_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
146};
147pub use result_cache::{
148    CacheBudget, CacheFlushPolicy, CachePutOpts, CacheStats, CachedValue, SemanticCachePutOpts,
149    DEFAULT_BATCH_MAX_AGE, DEFAULT_BATCH_MAX_DIRTY, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES,
150    DEFAULT_SEMANTIC_THRESHOLD,
151};
152pub use session::{Role, Session, Turn};
153pub use shared::{sidecar_notes, CancelToken, SharedOptions};
154#[doc(hidden)]
155#[cfg(feature = "dev-hooks")]
156pub use store::BudgetReport;
157pub use store::{
158    slug_of, Alive, Claim, ClaimOutcome, ClaimStatus, KindCounts, Message, NewWork, Presence,
159    Stale, Task, TaskClaim, TaskLost, TaskOutcome, TaskSpec, TaskTaken, Wake,
160};
161/// v0.18.0 (13a step 8b): review findings.
162pub use store::{valid_finding_id, Finding, FindingFilter, FindingSpec};
163pub use store::{
164    CloseError, CompactReport, IndexCheck, Mnemo, MnemoConfig, RecallMode, RecallRequest,
165    RecallResponse, RecallResult, ReembedReport, SharedMnemo, SnapshotInfo, Stats, StatsSummary,
166    VerifyReport, DEFAULT_KEYWORD_WEIGHT, DEFAULT_TEXT_KEYWORD_WEIGHT,
167    DEFAULT_TURN_COMPRESS_AFTER_SECS, DEFAULT_VECTOR_CACHE_BUDGET, INDEX_PERSIST_EVERY_CHANGES,
168    INDEX_PERSIST_EVERY_COMMITS, V9_ANN_MIN_FACTS, V9_RERANK_PER_HIT,
169};
170pub use text::{KeywordIndex, KeywordTokenizer};
171pub use transcript::{
172    read_transcript, read_transcript_with, ToolResults, TranscriptFormat, TranscriptOptions,
173};
174
175/// Re-export of [`ulid::Ulid`], the identifier type used for memories.
176pub use ulid::Ulid;
177
178// --- Fsync counter -----------------------------------------------------
179//
180// Instrumentation plumbing for the Phase 6 top-3 cost #2 fix: the
181// planner wants to know how many `sync_all` calls each `flush()` issues
182// before deciding whether to batch any of them. Every fsync call site
183// bumps a thread-local counter; `Mnemo::flush` snapshots it before and
184// after, exposing the delta on `Stats::fsyncs_last_flush`. Thread-local
185// so handles on separate threads don't poison each other's counts; the
186// engine's one-writer-at-a-time locking means a single handle sees a
187// coherent stream.
188
189mod fsync_counter {
190    use std::cell::Cell;
191
192    thread_local! {
193        static COUNT: Cell<u64> = const { Cell::new(0) };
194    }
195
196    /// Call once per `sync_all`.
197    pub(crate) fn bump() {
198        COUNT.with(|c| c.set(c.get().wrapping_add(1)));
199    }
200
201    /// Monotonic counter snapshot for this thread.
202    pub(crate) fn count() -> u64 {
203        COUNT.with(|c| c.get())
204    }
205}
206
207pub(crate) use fsync_counter::{bump as bump_fsync, count as fsync_count};
208
209/// Build-time cryptographic backend information.
210///
211/// Populated at compile time from the active `cfg` flags. On ARMv8
212/// builds compiled with `--cfg aes_armv8 --cfg polyval_armv8` (set by
213/// the repo's `.cargo/config.toml` and both CI workflows) the `aes`
214/// and `polyval` crates emit hardware AES + PMULL instructions; without
215/// those flags they fall back to a constant-time software path that
216/// runs at roughly 5× the cost per page.
217///
218/// Published through [`build_info`], exposed by `mnemo info` on the
219/// CLI and `mnemo.build_info()` from the Python binding. The point is
220/// verification — nobody should have to profile a release build to find
221/// out whether it's running software AES.
222#[derive(Debug, Clone, Copy, PartialEq, Eq)]
223pub struct BuildInfo {
224    /// Package version (`CARGO_PKG_VERSION`), e.g. `"0.5.1"`.
225    pub version: &'static str,
226    /// Target triple this binary was built for, e.g.
227    /// `"aarch64-apple-darwin"`.
228    pub target: &'static str,
229    /// Human-readable AES backend. One of:
230    /// - `"armv8 hardware"` — ARM with `cfg(aes_armv8)`
231    /// - `"armv8 software"` — ARM without the cfg; constant-time fallback
232    /// - `"x86_64 AES-NI (runtime detect)"` — x86_64 with runtime
233    ///   AES-NI detection in the `aes` crate
234    /// - `"portable software"` — any other target
235    pub aes_backend: &'static str,
236    /// Human-readable PMULL/CLMUL backend used by GHASH (part of AES-GCM).
237    /// Same shape as `aes_backend` but for `polyval`.
238    pub polyval_backend: &'static str,
239}
240
241/// Report this build's cryptographic backend configuration.
242///
243/// Cheap — all fields are `&'static str` populated at compile time.
244/// Safe to call from a hot path if, for some reason, that's useful.
245pub fn build_info() -> BuildInfo {
246    BuildInfo {
247        version: env!("CARGO_PKG_VERSION"),
248        target: TARGET_TRIPLE,
249        aes_backend: aes_backend_name(),
250        polyval_backend: polyval_backend_name(),
251    }
252}
253
254/// Target triple baked in via the `TARGET` env var that `cargo` sets
255/// for the host compile. Falls back to `"unknown"` if the var isn't
256/// set at build time (shouldn't happen under cargo, but a build.rs-free
257/// implementation keeps this crate build-script-free, so we use a
258/// cfg-based dispatch as the second-best).
259const TARGET_TRIPLE: &str = {
260    // `env!("TARGET")` isn't set by cargo for crates; it's set by rustc
261    // only for `std` builds. We approximate from `target_arch` /
262    // `target_os` cfgs so this stays build-script-free. Good enough
263    // for an info line; precise triples are a `cargo` or build.rs job.
264    if cfg!(all(target_arch = "aarch64", target_os = "macos")) {
265        "aarch64-apple-darwin"
266    } else if cfg!(all(target_arch = "aarch64", target_os = "linux")) {
267        "aarch64-unknown-linux-gnu"
268    } else if cfg!(all(target_arch = "x86_64", target_os = "macos")) {
269        "x86_64-apple-darwin"
270    } else if cfg!(all(target_arch = "x86_64", target_os = "linux")) {
271        "x86_64-unknown-linux-gnu"
272    } else if cfg!(all(target_arch = "x86_64", target_os = "windows")) {
273        "x86_64-pc-windows-msvc"
274    } else {
275        "unknown"
276    }
277};
278
279const fn aes_backend_name() -> &'static str {
280    if cfg!(aes_armv8) {
281        "armv8 hardware"
282    } else if cfg!(target_arch = "aarch64") {
283        // Software fallback is the dangerous case this whole mechanism
284        // exists to surface — flag it clearly so `mnemo info` makes it
285        // easy to notice a build picked up the slow path by mistake.
286        "armv8 software (constant-time fallback)"
287    } else if cfg!(target_arch = "x86_64") {
288        // `aes` 0.8.4 on x86_64 picks AES-NI vs the software path at
289        // runtime via the `cpufeatures` crate, so we can't tell from
290        // cfg alone which path a given invocation takes. In practice
291        // every x86_64 CPU shipped since ~2010 has AES-NI.
292        "x86_64 AES-NI (runtime detect)"
293    } else {
294        "portable software"
295    }
296}
297
298const fn polyval_backend_name() -> &'static str {
299    if cfg!(polyval_armv8) {
300        "armv8 PMULL hardware"
301    } else if cfg!(target_arch = "aarch64") {
302        "armv8 software (constant-time fallback)"
303    } else if cfg!(target_arch = "x86_64") {
304        "x86_64 CLMUL (runtime detect)"
305    } else {
306        "portable software"
307    }
308}
309
310/// **Not a stable API** (`dev-hooks` builds only): how many `sync_all`
311/// calls this thread has made, for step 5's bench to count a write's
312/// fsyncs.
313#[cfg(feature = "dev-hooks")]
314#[doc(hidden)]
315pub fn __fsync_count() -> u64 {
316    fsync_count()
317}
318
319/// Test-only crash-injection surface used by the Phase 1.3 proptest
320/// (`mnemo/tests/proptest_store.rs`). Compiled in under `cfg(test)`
321/// and the `failpoints` feature only; absent from release builds.
322///
323/// **Not part of the stable public API.** The double-underscore
324/// convention makes the "internal" contract obvious at the call site.
325#[cfg(any(test, feature = "failpoints"))]
326#[doc(hidden)]
327pub mod __failpoints {
328    /// Arm the pager and WAL commit path to fail on the Nth
329    /// subsequent write. `n = 0` fails the very next write; `n = -1`
330    /// (or any negative) disables. One-shot — disarms on trigger.
331    ///
332    /// Every write is checked before the byte hits the file, so a
333    /// triggered failure is guaranteed torn-BEFORE, never
334    /// torn-AFTER — critical for the "either pre-flush or post-flush"
335    /// invariant the property test asserts.
336    pub fn set_writes_until_fail(n: i64) {
337        crate::pager::failpoints::set_writes_until_fail(n)
338    }
339
340    /// Like [`set_writes_until_fail`], but `count` writes in a row fail.
341    pub fn set_writes_until_fail_n(n: i64, count: u32) {
342        crate::pager::failpoints::set_writes_until_fail_n(n, count)
343    }
344
345    /// Fail exactly the writes numbered in `ns` (from 0, counting from this
346    /// call), consecutive or not; an empty set disarms it.
347    pub fn set_writes_failing(ns: &[u64]) {
348        crate::pager::failpoints::set_writes_failing(ns)
349    }
350
351    /// How many writes this thread has made since the last
352    /// [`set_writes_failing`].
353    pub fn writes_seen() -> u64 {
354        crate::pager::failpoints::writes_seen()
355    }
356
357    /// v0.19.1: make the next `count` reads that cover page `page` fail
358    /// with an I/O error, in any thread; `count = 0` disarms it. It's
359    /// process-wide, so a test that arms it runs in a binary of its own.
360    pub fn set_page_read_fails(page: u64, count: u32) {
361        crate::pager::failpoints::set_page_read_fails(page, count)
362    }
363
364    thread_local! {
365        static AFTER_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
366            const { std::cell::RefCell::new(None) };
367        static BEFORE_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
368            const { std::cell::RefCell::new(None) };
369    }
370
371    /// Run `f` once, inside this thread's next shared-mode write, after the
372    /// window's closure and before the window's commit (so after the
373    /// window's identity check, 12.4 protocol step 4). Lets a test rename a
374    /// file over the path the way an older build's compaction can.
375    pub fn before_next_shared_commit(f: impl FnOnce() + 'static) {
376        BEFORE_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
377    }
378
379    pub(crate) fn run_before_shared_commit() {
380        if let Some(f) = BEFORE_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
381            f();
382        }
383    }
384
385    /// Run `f` once, inside this thread's next shared-mode write, after its
386    /// commit and before the identity check that follows (12.4 protocol
387    /// step 8). Lets a test rename a file over the path at that moment.
388    pub fn after_next_shared_commit(f: impl FnOnce() + 'static) {
389        AFTER_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
390    }
391
392    pub(crate) fn run_after_shared_commit() {
393        if let Some(f) = AFTER_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
394            f();
395        }
396    }
397
398    thread_local! {
399        static NEXT_TEMP_NAME: std::cell::RefCell<Option<std::path::PathBuf>> =
400            const { std::cell::RefCell::new(None) };
401    }
402
403    /// Make the next temp file name this thread asks for (compaction,
404    /// `export_encrypted`, `export_rekeyed`) be `path`, once; the attempts
405    /// after it are generated as usual. Lets a test plant a file or a
406    /// symlink at the exact name the engine is about to use.
407    pub fn set_next_temp_name(path: impl Into<std::path::PathBuf>) {
408        NEXT_TEMP_NAME.with(|n| *n.borrow_mut() = Some(path.into()));
409    }
410
411    pub(crate) fn take_next_temp_name() -> Option<std::path::PathBuf> {
412        NEXT_TEMP_NAME.with(|n| n.borrow_mut().take())
413    }
414
415    thread_local! {
416        static SHARED_MAIN_TRIES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
417        static SHARED_REPLACED: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
418    }
419
420    /// How many times this thread's shared-mode calls have tried the main
421    /// lock (each open, lock and identity check counts once).
422    pub fn shared_main_tries() -> u64 {
423        SHARED_MAIN_TRIES.with(|c| c.get())
424    }
425
426    pub(crate) fn count_shared_main_try() {
427        SHARED_MAIN_TRIES.with(|c| c.set(c.get() + 1));
428    }
429
430    /// Make this thread's next `n` shared-mode tries at the main lock find
431    /// the file replaced (as if a compaction renamed a new file over the
432    /// path between the open and the lock each time). `0` disarms.
433    pub fn set_shared_replaced(n: u64) {
434        SHARED_REPLACED.with(|c| c.set(n));
435    }
436
437    thread_local! {
438        static EUID_OVERRIDE: std::cell::Cell<Option<u32>> = const { std::cell::Cell::new(None) };
439    }
440
441    /// Make this thread's file-owner checks (the dead compaction temp
442    /// files' cleanup) compare against `uid` instead of the effective uid,
443    /// so a test can see a file as another user's without root. `None`
444    /// restores the real check.
445    pub fn set_euid_override(uid: Option<u32>) {
446        EUID_OVERRIDE.with(|c| c.set(uid));
447    }
448
449    // Read by the Unix owner check only.
450    #[cfg(unix)]
451    pub(crate) fn euid_override() -> Option<u32> {
452        EUID_OVERRIDE.with(|c| c.get())
453    }
454
455    thread_local! {
456        static PATH_CHECK_FAILURES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
457    }
458
459    /// Make this thread's next `n` checks that a handle's path still names
460    /// its open file fail with a permission error (RB-008.2), as when the
461    /// process has lost access to the path. `0` disarms.
462    pub fn set_path_check_failures(n: u64) {
463        PATH_CHECK_FAILURES.with(|c| c.set(n));
464    }
465
466    /// How many armed path-check failures this thread has left.
467    pub fn path_check_failures_left() -> u64 {
468        PATH_CHECK_FAILURES.with(|c| c.get())
469    }
470
471    pub(crate) fn take_path_check_failure() -> bool {
472        PATH_CHECK_FAILURES.with(|c| {
473            let n = c.get();
474            if n > 0 {
475                c.set(n - 1);
476            }
477            n > 0
478        })
479    }
480
481    pub(crate) fn take_shared_replaced() -> bool {
482        SHARED_REPLACED.with(|c| {
483            let n = c.get();
484            if n > 0 {
485                c.set(n - 1);
486            }
487            n > 0
488        })
489    }
490}
491
492/// 12.4 step 2a: the shared lock layer, reached directly by its tests
493/// (`tests/shared_lock.rs`) until `Mnemo::open_shared` (step 2b) wraps it.
494/// Compiled in under `cfg(test)` and the `failpoints` feature only.
495///
496/// **Not part of the stable public API.**
497#[cfg(any(test, feature = "failpoints"))]
498#[doc(hidden)]
499pub mod __shared {
500    use std::path::{Path, PathBuf};
501
502    use crate::shared::{BrainLocks, Call, Held, LockKind};
503    use crate::{Result, SharedOptions};
504
505    /// The sidecar directory's suffix and its two file names.
506    pub const SUFFIX: &str = crate::shared::testing::SUFFIX;
507    pub const INTENT: &str = crate::shared::testing::INTENT;
508    pub const LOCK_INFO: &str = crate::shared::testing::LOCK_INFO;
509    /// LOCK-2's valve file name.
510    pub const VALVE: &str = crate::shared::testing::VALVE;
511
512    /// Whether this build refuses shared mode (Windows, Rust before 1.85).
513    pub const WINDOWS_OLD_RENAME: bool = crate::shared::WINDOWS_OLD_RENAME;
514
515    /// `<brain>.mnemo-shared` for a resolved brain path.
516    pub fn sidecar_path(brain: &Path) -> PathBuf {
517        crate::shared::testing::sidecar_path(brain)
518    }
519
520    /// The macOS synced-folder rule, as a pure function.
521    pub fn classify_synced(path: &Path, home: &Path) -> Option<String> {
522        crate::shared::testing::classify_synced(path, home)
523    }
524
525    /// Whether a Linux `statfs` magic number is allowed.
526    pub fn linux_fs_allowed(magic: u32) -> bool {
527        crate::shared::testing::linux_fs_allowed(magic)
528    }
529
530    /// The lock layer for one brain.
531    #[derive(Debug)]
532    pub struct Locks(BrainLocks);
533
534    impl Locks {
535        pub fn new(path: &Path, opts: &SharedOptions) -> Result<Self> {
536            BrainLocks::new(path, opts).map(Locks)
537        }
538        /// A plain long operation's layer, which never creates the sidecar.
539        pub fn for_plain(path: &Path, opts: &SharedOptions) -> Result<Self> {
540            BrainLocks::for_plain(path, opts).map(Locks)
541        }
542        /// LOCK-2: how many times this layer's writers took the valve.
543        pub fn valve_takes(&self) -> u64 {
544            self.0.valve_takes()
545        }
546        pub fn shared(&mut self, opts: &SharedOptions) -> Result<Lock> {
547            let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
548            self.0.acquire(LockKind::Shared, &mut call).map(Lock)
549        }
550        pub fn exclusive(&mut self, opts: &SharedOptions) -> Result<Lock> {
551            let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
552            self.0.acquire(LockKind::Exclusive, &mut call).map(Lock)
553        }
554        pub fn has_sidecar(&self) -> bool {
555            self.0.has_sidecar()
556        }
557        pub fn sidecar_path(&self) -> Option<PathBuf> {
558            self.0.sidecar_path().map(Path::to_path_buf)
559        }
560        pub fn notices(&self) -> Vec<String> {
561            self.0.notices().to_vec()
562        }
563    }
564
565    /// One call's main lock; dropping it unlocks.
566    pub struct Lock(Held);
567
568    impl Lock {
569        pub fn announce(&mut self, op: &str) {
570            self.0.announce(op)
571        }
572        pub fn file(&self) -> &std::fs::File {
573            self.0.file()
574        }
575    }
576}
577
578/// WAL entry points for the PERF-1 allocation test
579/// (`tests/wal_recover_alloc.rs`), which needs its own global allocator and
580/// so can't live in this `forbid(unsafe_code)` crate. Not a stable API.
581#[doc(hidden)]
582pub mod __wal {
583    /// Page size of the WAL region.
584    pub const PAGE_SIZE: usize = crate::format::PAGE_SIZE;
585
586    /// One WAL frame: a home page number and its page image.
587    pub type Frame = (u64, Vec<u8>);
588
589    /// Bytes a transaction of `n` page frames occupies.
590    pub fn txn_byte_len(n: usize) -> u64 {
591        crate::wal::txn_byte_len(n, PAGE_SIZE)
592    }
593
594    /// Commit `frames` as transaction `txn_id` at the start of a region.
595    pub fn commit(
596        file: &mut std::fs::File,
597        wal_pages: u64,
598        txn_id: u64,
599        frames: &[Frame],
600    ) -> crate::Result<()> {
601        crate::wal::commit(file, 0, wal_pages, txn_id, frames)
602    }
603
604    /// Run open-time recovery over a region starting at page 0; returns the
605    /// frames to replay, if any.
606    pub fn recover(
607        file: &mut std::fs::File,
608        wal_pages: u64,
609        wal_seq: u64,
610    ) -> crate::Result<Option<Vec<Frame>>> {
611        crate::wal::recover(file, 0, wal_pages, wal_seq)
612    }
613}
614
615/// Internal parse surfaces exposed for cargo-fuzz targets (Phase 1.2).
616///
617/// **Not part of the stable public API.** Each function feeds an
618/// arbitrary byte slice into a parse/decode path that a hostile
619/// `.mnemo` file (or a hostile MCP client) can send us, and returns
620/// `Result<()>` so a fuzz target only asserts "no panic." Marked
621/// `#[doc(hidden)]` so `cargo doc` doesn't advertise it; do not import
622/// from application code.
623#[doc(hidden)]
624pub mod __fuzz {
625    /// Parse a `.mnemo` header page (page 0, plaintext) from arbitrary
626    /// bytes. This is the pre-passphrase attack surface — a hostile
627    /// file hits it before any DEK exists.
628    pub fn parse_header(bytes: &[u8]) -> crate::Result<()> {
629        crate::format::Header::from_page(bytes).map(|_| ())
630    }
631
632    /// Replay the WAL scan over an arbitrary byte region. Delegates
633    /// to [`crate::wal::recover_bytes`]; a corrupt / truncated /
634    /// adversarial region must return `Err` or `Ok(None/Some(_))`,
635    /// never panic.
636    pub fn wal_recover_bytes(region: &[u8], wal_seq: u64) -> crate::Result<()> {
637        crate::wal::recover_bytes(region, wal_seq).map(|_| ())
638    }
639
640    /// Decode a `Memory` record body from arbitrary bytes.
641    pub fn decode_memory(bytes: &[u8]) -> crate::Result<()> {
642        rmp_serde::from_slice::<crate::Memory>(bytes)
643            .map(|_| ())
644            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
645    }
646
647    /// FMT-9e: decode a v9 `Memory` record body from arbitrary bytes: a
648    /// zstd frame (a compressed thread turn) is decompressed first, under
649    /// the same content-size bound the store applies.
650    pub fn decode_v9_memory(bytes: &[u8]) -> crate::Result<()> {
651        let plain = crate::store::plain_record(bytes)?;
652        rmp_serde::from_slice::<crate::Memory>(&plain)
653            .map(|_| ())
654            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
655    }
656
657    /// Decode a `CacheEntry` record body from arbitrary bytes. Type is
658    /// `pub(crate)`, so this wrapper hides it behind a unit return.
659    pub fn decode_cache_entry(bytes: &[u8]) -> crate::Result<()> {
660        rmp_serde::from_slice::<crate::result_cache::CacheEntry>(bytes)
661            .map(|_| ())
662            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
663    }
664
665    /// Decode a cache-directory page-run body (a `Vec<CacheDirectoryEntry>`)
666    /// from arbitrary bytes.
667    pub fn decode_cache_directory(bytes: &[u8]) -> crate::Result<()> {
668        rmp_serde::from_slice::<Vec<crate::result_cache::CacheDirectoryEntry>>(bytes)
669            .map(|_| ())
670            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
671    }
672
673    /// RB-015.2 (v0.19.1): decode a v9 index run body in layout 2 (the
674    /// bytes after its layout byte) from arbitrary bytes. When it decodes,
675    /// the index is queried, changed and written again, and what it writes
676    /// must decode: none of it may panic.
677    pub fn decode_index_layout2(bytes: &[u8]) -> crate::Result<()> {
678        let idx = crate::index::IvfPqIndex::read_layout2(&mut &bytes[..], bytes.len() as u64)?;
679        exercise_index(idx)
680    }
681
682    /// RB-015.2: [`decode_index_layout2`] on a valid layout-2 body (a small
683    /// index built once) with `edits` applied, so the fuzzer starts from a
684    /// well-formed run. Each 3 bytes are a little-endian `u16` offset (taken
685    /// modulo the body's length) and a byte XORed in there; a last byte or
686    /// two cut the body to that fraction of its length (out of 256 or 65536).
687    pub fn mutate_index_layout2(edits: &[u8]) -> crate::Result<()> {
688        static BASE: std::sync::OnceLock<Vec<u8>> = std::sync::OnceLock::new();
689        let base = BASE.get_or_init(|| {
690            let vecs: Vec<(u128, Vec<f32>)> = (0..300u32)
691                .map(|i| {
692                    let x = i as f32;
693                    (
694                        i as u128 + 1,
695                        vec![
696                            1.0 + (x * 0.37).sin(),
697                            (x * 0.11).cos(),
698                            (x * 0.07).sin(),
699                            0.5,
700                        ],
701                    )
702                })
703                .collect();
704            let items: Vec<(u128, &[f32])> = vecs.iter().map(|(i, v)| (*i, v.as_slice())).collect();
705            let idx = crate::index::IvfPqIndex::build(4, &items, crate::IndexConfig::default())
706                .expect("the seed index builds");
707            let mut out = Vec::new();
708            idx.write_layout2(&mut out);
709            out
710        });
711        let mut body = base.clone();
712        let mut chunks = edits.chunks_exact(3);
713        for e in chunks.by_ref() {
714            let at = u16::from_le_bytes([e[0], e[1]]) as usize % body.len();
715            body[at] ^= e[2];
716        }
717        match chunks.remainder() {
718            [c] => body.truncate(body.len() * *c as usize / 256),
719            [a, b] => body.truncate(body.len() * u16::from_le_bytes([*a, *b]) as usize / 65536),
720            _ => {}
721        }
722        decode_index_layout2(&body)
723    }
724
725    fn exercise_index(mut idx: crate::index::IvfPqIndex) -> crate::Result<()> {
726        let dims = idx.dims();
727        if dims == 0 || dims > 4096 {
728            return Ok(());
729        }
730        let q = vec![0.5f32; dims];
731        let _ = idx.query(&q, None, None);
732        let first = idx.ids().next();
733        idx.add(u128::MAX - 1, &q);
734        if let Some(id) = first {
735            idx.remove(id);
736        }
737        let _ = idx.query(&q, Some(2), Some(8));
738        let mut out = Vec::new();
739        idx.write_layout2(&mut out);
740        crate::index::IvfPqIndex::read_layout2(&mut &out[..], out.len() as u64)
741            .expect("an index this build wrote decodes again");
742        Ok(())
743    }
744
745    /// Parse a single MCP stdio JSON-RPC request line. Malformed
746    /// input returns `Err(String)`; the fuzz target only asserts
747    /// no panic and that the server would not die on this line.
748    pub fn parse_mcp_request_line(line: &str) -> Result<(), String> {
749        crate::mcp::__fuzz_parse_request_line(line)
750    }
751}