mnemo-engine 0.4.0__tar.gz → 0.4.1__tar.gz

{mnemo_engine-0.4.0 → mnemo_engine-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnemo-engine
-Version: 0.4.0
+Version: 0.4.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -155,11 +155,22 @@ its own agent.
 | `cache_stats(namespace=None)` | Result-cache stats: `{entries, bytes, hits, misses, hit_rate, evictions}` |
 | `cache_put_semantic(namespace, key, vector, value, model, content_type="text", ttl_secs=None)` | Semantic cache put (Phase 10.2) — vector must match db dimensions |
 | `cache_get_semantic(namespace, query, model, threshold=0.97)` | Top-1 cosine over the namespace's vectored entries whose `model` matches |
+| `set_cache_flush_policy(policy, max_dirty=None, max_age_secs=None)` | `policy="strict"` (default; every put durable on return) or `"batched"` (engine auto-flushes at `max_dirty` puts or `max_age_secs` seconds). Under `batched`, `cache_put` and friends no longer force an eager flush — call `db.flush()` yourself if you need it before a specific boundary |
+| `set_cache_budget(namespace, max_entries, max_bytes)` | Per-namespace LRU cap (defaults 10 000 entries / 64 MiB). On the next `cache_put` the LRU is evicted until both limits are satisfied |
 | `set_max_snapshots(max)` | Override the snapshot-manifest retention cap (default 256; `0` disables) |
+| `memories()` | Enumerate every live (non-deleted, non-expired) memory as a list of dicts |
+| `dimensions()` | Embedding dimensionality this database was created with (also on `stats()["dimensions"]`) |
+| `rekey(new_passphrase, fast=False)` | Change the passphrase. Re-derives the KEK and re-wraps the DEK; encrypted pages are not rewritten (O(1) in db size). `fast=True` uses the cheap-Argon2 test params — omit for production |
 | `stats()` | Summary statistics |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
+Plus one module-level function:
+
+| Function | Purpose |
+|---|---|
+| `mnemo.compact_file(path, passphrase)` | Rewrite the file out-of-place, dropping tombstoned and expired memories and reclaiming stale pages. Caller's own handle must be closed first. Returns `{"before": int, "after": int}` |
+
 `Session` methods: `add_turn(turn)`, `recall(query, top_k=10, memory_types=None)`,
 `close()`, `discard()`, `id()`, `agent()`, `turn_ids()`, `turn_count()`; also a
 context manager (exiting consolidates).

{mnemo_engine-0.4.0 → mnemo_engine-0.4.1}/README.md

@@ -141,11 +141,22 @@ its own agent.
 | `cache_stats(namespace=None)` | Result-cache stats: `{entries, bytes, hits, misses, hit_rate, evictions}` |
 | `cache_put_semantic(namespace, key, vector, value, model, content_type="text", ttl_secs=None)` | Semantic cache put (Phase 10.2) — vector must match db dimensions |
 | `cache_get_semantic(namespace, query, model, threshold=0.97)` | Top-1 cosine over the namespace's vectored entries whose `model` matches |
+| `set_cache_flush_policy(policy, max_dirty=None, max_age_secs=None)` | `policy="strict"` (default; every put durable on return) or `"batched"` (engine auto-flushes at `max_dirty` puts or `max_age_secs` seconds). Under `batched`, `cache_put` and friends no longer force an eager flush — call `db.flush()` yourself if you need it before a specific boundary |
+| `set_cache_budget(namespace, max_entries, max_bytes)` | Per-namespace LRU cap (defaults 10 000 entries / 64 MiB). On the next `cache_put` the LRU is evicted until both limits are satisfied |
 | `set_max_snapshots(max)` | Override the snapshot-manifest retention cap (default 256; `0` disables) |
+| `memories()` | Enumerate every live (non-deleted, non-expired) memory as a list of dicts |
+| `dimensions()` | Embedding dimensionality this database was created with (also on `stats()["dimensions"]`) |
+| `rekey(new_passphrase, fast=False)` | Change the passphrase. Re-derives the KEK and re-wraps the DEK; encrypted pages are not rewritten (O(1) in db size). `fast=True` uses the cheap-Argon2 test params — omit for production |
 | `stats()` | Summary statistics |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
+Plus one module-level function:
+
+| Function | Purpose |
+|---|---|
+| `mnemo.compact_file(path, passphrase)` | Rewrite the file out-of-place, dropping tombstoned and expired memories and reclaiming stale pages. Caller's own handle must be closed first. Returns `{"before": int, "after": int}` |
+
 `Session` methods: `add_turn(turn)`, `recall(query, top_k=10, memory_types=None)`,
 `close()`, `discard()`, `id()`, `agent()`, `turn_ids()`, `turn_count()`; also a
 context manager (exiting consolidates).

{mnemo_engine-0.4.0 → mnemo_engine-0.4.1}/mnemo/Cargo.lock

@@ -120,6 +120,21 @@ version = "1.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8c3c1a368f70d6cf7302d78f8f7093da241fb8e8807c05cc9e51a125895a6d5b"
 
+[[package]]
+name = "bit-set"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0700ddab506f33b20a03b13996eccd309a48e5ff77d0d95926aa0210fb4e95f1"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
+
 [[package]]
 name = "bitflags"
 version = "2.11.1"
@@ -293,6 +308,12 @@ version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "fs4"
 version = "0.9.1"
@@ -399,6 +420,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
 [[package]]
 name = "libc"
 version = "0.2.186"
@@ -415,6 +442,12 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.15"
@@ -429,13 +462,14 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "mnemo-engine"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "aes-gcm",
  "argon2",
  "base64ct",
  "clap",
  "fs4",
+ "proptest",
  "rand",
  "rmp",
  "rmp-serde",
@@ -451,7 +485,7 @@ dependencies = [
 
 [[package]]
 name = "mnemo-node"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "mnemo-engine",
  "napi",
@@ -523,6 +557,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
 dependencies = [
  "autocfg",
+ "libm",
 ]
 
 [[package]]
@@ -596,6 +631,32 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proptest"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4c2511913b88df1637da85cc8d96ec8e43a3f8bb8ccb71ee1ac240d6f3df58d"
+dependencies = [
+ "bit-set",
+ "bit-vec",
+ "bitflags",
+ "lazy_static",
+ "num-traits",
+ "rand",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -607,9 +668,9 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.8.5"
+version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
  "libc",
  "rand_chacha",
@@ -635,6 +696,15 @@ dependencies = [
  "getrandom",
 ]
 
+[[package]]
+name = "rand_xorshift"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d25bf25ec5ae4a3f1b92f929810509a2f53d7dca2f50b794ff57e3face536c8f"
+dependencies = [
+ "rand_core",
+]
+
 [[package]]
 name = "regex"
 version = "1.12.3"
@@ -726,6 +796,18 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error",
+ "tempfile",
+ "wait-timeout",
+]
+
 [[package]]
 name = "ryu"
 version = "1.0.23"
@@ -860,6 +942,12 @@ dependencies = [
  "web-time",
 ]
 
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -894,6 +982,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"

{mnemo_engine-0.4.0 → mnemo_engine-0.4.1}/mnemo/Cargo.toml

@@ -6,7 +6,7 @@
 # below stay `mnemo`, so consumers still write `use mnemo::...` and invoke
 # `mnemo` on the command line after `cargo add mnemo-engine`.
 name = "mnemo-engine"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2021"
 rust-version = "1.75"
 description = "Encrypted, single-file, portable agent memory engine with multi-signal recall, sessions, snapshots, and an IVF+PQ index"
@@ -55,7 +55,14 @@ base64ct = "=1.6.0"
 ulid = { version = "=1.1.3", features = ["serde"] }
 thiserror = "=1.0.64"
 zeroize = "=1.8.1"
-rand = "=0.8.5"
+# Pinned `=0.8.6` (patch bump from 0.8.5) to close RUSTSEC-2026-0097,
+# an unsoundness that only triggers under a very narrow config —
+# custom `log::Log` impl reentrantly calling `rand::rng()` on
+# `ThreadRng` mid-reseed — which mnemo does not do. The engine
+# never touches `log`, and no CLI code paths reach `ThreadRng` from
+# a logger. Upgrading anyway is the least-surprising thing to do
+# and satisfies the `advisories` check without an ignore.
+rand = "=0.8.6"
 clap = { version = "=4.4.18", features = ["derive"] }
 # Used by the `mnemo` CLI binary only — `passphrase()` calls it when stdin
 # is a TTY to read the passphrase without echo. The library never touches
@@ -77,6 +84,19 @@ sha2 = "=0.10.8"
 
 [dev-dependencies]
 tempfile = "=3.10.1"
+# Property-based testing (Phase 1.3). Pinned exactly; `=1.5.0`'s MSRV
+# is Rust 1.65, well under our 1.75 floor. Kept as a dev-dep only —
+# it does not appear in the shipped library dependency set.
+proptest = "=1.5.0"
+
+[features]
+# When enabled, exposes crash-injection hooks used by the Phase 1.3
+# proptest under `mnemo::__failpoints::*`. Always enabled during
+# `cargo test` via `#[cfg(test)]`; the feature is here so an external
+# fault-injection consumer (or a future integration test in a sibling
+# crate) can opt into the same hooks without touching this crate's
+# tests. Not for production use — never enable in a release build.
+failpoints = []
 
 [profile.release]
 lto = true

mnemo_engine-0.4.1/mnemo/deny.toml

@@ -0,0 +1,131 @@
+# cargo-deny configuration (Phase 1.4).
+#
+# Runs in CI on every PR via `cargo deny check` in `mnemo/`. Three
+# checks matter here:
+#   1. `advisories` — cross-references the RustSec advisory DB and
+#      fails on any unpatched vulnerability affecting a dep in the
+#      lockfile.
+#   2. `licenses` — allowlist of OSI-approved licenses compatible
+#      with the Apache-2.0 the mnemo crate itself is published under.
+#      Anything unlisted requires an explicit `exceptions` entry.
+#   3. `bans` — currently informational (`multiple-versions = "warn"`)
+#      to catch transitive duplication without blocking merges while
+#      we enumerate the necessary skip set. Follow-up PR will
+#      tighten to `deny` once CI has surfaced the real exception
+#      list.
+#
+# Run locally with:
+#     cd mnemo && cargo deny check
+#
+# For just one check:
+#     cargo deny check advisories
+#     cargo deny check licenses
+#     cargo deny check bans
+
+# ---------------------------------------------------------------------
+# Graph configuration — what crates the checks apply to.
+# ---------------------------------------------------------------------
+
+[graph]
+# Empty `targets` means "check all crates for all target triples the
+# lockfile references." Since mnemo compiles on Linux/macOS/Windows
+# x86_64+aarch64, restricting to a single target would hide license /
+# advisory hits on platform-specific transitives (e.g. `windows-sys`
+# on Windows only).
+targets = []
+all-features = false
+no-default-features = false
+
+[output]
+# Group violations by feature depth; keeps the diagnostic readable
+# on the multi-page transitive graph typical of a Rust crate.
+feature-depth = 1
+
+# ---------------------------------------------------------------------
+# Advisory DB — RustSec vulnerability + yanked-crate check.
+# ---------------------------------------------------------------------
+
+[advisories]
+version = 2
+db-path = "~/.cargo/advisory-db"
+db-urls = ["https://github.com/rustsec/advisory-db"]
+# `yanked` fires when Cargo.lock pins a version the author later
+# yanked from crates.io. `warn` first so we notice; upgrade to
+# `deny` once we've picked up a clean baseline.
+yanked = "warn"
+# Time-boxed / justified exceptions to the advisory check. Every
+# entry must carry a `reason` — a future worker reading this file
+# should be able to tell why the ignore was granted without leaving
+# the config.
+ignore = [
+    # `paste 1.0.15` — dtolnay archived the repo (RUSTSEC-2024-0436,
+    # "unmaintained"). NOT a vulnerability. It is pulled transitively
+    # by `rmp` / `rmp-serde` (our MessagePack layer) which have no
+    # migration path today. The advisory itself suggests `pastey` as
+    # a drop-in fork; that migration lives in `rmp`, not here. Revisit
+    # when `rmp-serde` ships a release that swaps to `pastey`.
+    { id = "RUSTSEC-2024-0436", reason = "paste (unmaintained) is a transitive dep of rmp-serde; no upstream migration path yet — track via rmp-serde issue tracker" },
+]
+
+# ---------------------------------------------------------------------
+# Licenses — SPDX allowlist. Anything not listed → build fails.
+# ---------------------------------------------------------------------
+
+[licenses]
+version = 2
+# Kept minimal — the mnemo dep graph in practice only ships crates
+# under Apache-2.0, MIT, BSD-3-Clause, and Unicode-3.0 (the newer
+# SPDX variant `unicode-ident` uses). Apache-2.0 WITH LLVM-exception
+# covers the `rustix` family. Adding an unused allow is not a security
+# hole but it's noise — cargo-deny prints an "unmatched license
+# allowance" warning for each, and drift in the allowlist becomes
+# hard to notice. Extend this list only when a new dep actually
+# ships under something not already here.
+allow = [
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "MIT",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "Unicode-3.0",
+]
+# Threshold for guessing a license from a LICENSE file's text when
+# the crate omits SPDX metadata. Default 0.8 is conservative — lower
+# it only if a specific crate needs a `[[licenses.clarify]]` entry.
+confidence-threshold = 0.8
+# Per-crate license overrides go here if a crate ships an unusual
+# LICENSE mix cargo-deny can't parse. Empty at PR 9 landing;
+# expand as CI surfaces cases.
+exceptions = []
+
+# ---------------------------------------------------------------------
+# Bans — duplicate versions, wildcard deps, per-crate allow/deny.
+# ---------------------------------------------------------------------
+
+[bans]
+# `warn` for now: transitive graphs commonly duplicate `syn 1/2`,
+# `regex-syntax 0.6/0.8`, `bitflags 1/2`, `windows-sys 0.4x/0.5x`
+# during migrations. First green CI run will list the actual
+# duplicates; follow-up PR flips to `deny` with the enumerated
+# `skip` entries.
+multiple-versions = "warn"
+wildcards = "allow"
+highlight = "all"
+workspace-default-features = "allow"
+external-default-features = "allow"
+allow = []
+deny = []
+skip = []
+skip-tree = []
+
+# ---------------------------------------------------------------------
+# Sources — where crates may come from.
+# ---------------------------------------------------------------------
+
+[sources]
+unknown-registry = "warn"
+unknown-git = "warn"
+# Only crates.io. No git deps in mnemo (all pinned to `=x.y.z` per
+# AGENTS.md), so this stays tight.
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+allow-git = []

mnemo_engine-0.4.1/mnemo/src/lib.rs

@@ -0,0 +1,158 @@
+//! # Mnemo
+//!
+//! Mnemo is an **encrypted, single-file, portable agent-memory engine**.
+//!
+//! A whole memory store — vectors, content, metadata, and the multi-signal
+//! recall machinery an agent needs — lives in one file you can copy, back up,
+//! or hand to another process. The file is encrypted at rest with a two-tier
+//! key hierarchy: an Argon2id key-encryption key (KEK) derived from a
+//! passphrase wraps a random data-encryption key (DEK), and the DEK encrypts
+//! every page with AES-256-GCM.
+//!
+//! ## Quick start
+//!
+//! ```no_run
+//! use mnemo::{Mnemo, MnemoConfig, Memory, MemoryType, RecallRequest};
+//!
+//! # fn main() -> mnemo::Result<()> {
+//! let cfg = MnemoConfig { dimensions: 3, ..Default::default() };
+//! let mut db = Mnemo::create("agent.mnemo", "correct horse battery", cfg)?;
+//!
+//! db.remember(
+//!     Memory::new("the user prefers dark mode", MemoryType::Semantic, vec![0.1, 0.2, 0.9])
+//!         .with_agent("assistant-1")
+//!         .with_importance(0.8),
+//! )?;
+//! db.flush()?;
+//!
+//! let hits = db.recall(&RecallRequest::new(vec![0.1, 0.2, 0.9]).top_k(5))?;
+//! for h in hits {
+//!     println!("{:.3}  {}", h.score, h.memory.content);
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## What is and is not built
+//!
+//! This crate implements a real, tested core: the encrypted single-file
+//! storage engine, the crypto layer, the agent-memory model, multi-signal
+//! recall, an IVF+PQ approximate-nearest-neighbour index, a write-ahead log,
+//! snapshot-based point-in-time recovery, a bounded LRU page cache, and the
+//! [`Session`] conversation wrapper. Exact brute-force search remains
+//! available as the ground-truth baseline; a built index makes
+//! [`Mnemo::recall`] sub-linear. Each [`Mnemo::flush`] is one atomic,
+//! WAL-committed transaction and a restorable snapshot — [`Mnemo::restore_to`]
+//! rewinds the database to any past transaction. Python and TypeScript
+//! language bindings are the one documented roadmap item — see the README.
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+mod cache;
+mod crypto;
+mod error;
+mod format;
+mod index;
+pub mod mcp;
+mod memory;
+mod pager;
+mod result_cache;
+mod session;
+mod store;
+mod wal;
+
+pub use crypto::KdfParams;
+pub use error::{MnemoError, Result};
+pub use index::{IndexConfig, IndexInfo};
+pub use memory::{Memory, MemoryType, Metric, Scope, ScoreWeights};
+pub use result_cache::{
+    CacheBudget, CacheFlushPolicy, CachePutOpts, CacheStats, CachedValue, SemanticCachePutOpts,
+    DEFAULT_BATCH_MAX_AGE, DEFAULT_BATCH_MAX_DIRTY, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES,
+    DEFAULT_SEMANTIC_THRESHOLD,
+};
+pub use session::{Role, Session, Turn};
+pub use store::{
+    CompactReport, Mnemo, MnemoConfig, RecallRequest, RecallResult, SnapshotInfo, Stats,
+};
+
+/// Re-export of [`ulid::Ulid`], the identifier type used for memories.
+pub use ulid::Ulid;
+
+/// Test-only crash-injection surface used by the Phase 1.3 proptest
+/// (`mnemo/tests/proptest_store.rs`). Compiled in under `cfg(test)`
+/// and the `failpoints` feature only; absent from release builds.
+///
+/// **Not part of the stable public API.** The double-underscore
+/// convention makes the "internal" contract obvious at the call site.
+#[cfg(any(test, feature = "failpoints"))]
+#[doc(hidden)]
+pub mod __failpoints {
+    /// Arm the pager and WAL commit path to fail on the Nth
+    /// subsequent write. `n = 0` fails the very next write; `n = -1`
+    /// (or any negative) disables. One-shot — disarms on trigger.
+    ///
+    /// Every write is checked before the byte hits the file, so a
+    /// triggered failure is guaranteed torn-BEFORE, never
+    /// torn-AFTER — critical for the "either pre-flush or post-flush"
+    /// invariant the property test asserts.
+    pub fn set_writes_until_fail(n: i64) {
+        crate::pager::failpoints::set_writes_until_fail(n)
+    }
+}
+
+/// Internal parse surfaces exposed for cargo-fuzz targets (Phase 1.2).
+///
+/// **Not part of the stable public API.** Each function feeds an
+/// arbitrary byte slice into a parse/decode path that a hostile
+/// `.mnemo` file (or a hostile MCP client) can send us, and returns
+/// `Result<()>` so a fuzz target only asserts "no panic." Marked
+/// `#[doc(hidden)]` so `cargo doc` doesn't advertise it; do not import
+/// from application code.
+#[doc(hidden)]
+pub mod __fuzz {
+    /// Parse a `.mnemo` header page (page 0, plaintext) from arbitrary
+    /// bytes. This is the pre-passphrase attack surface — a hostile
+    /// file hits it before any DEK exists.
+    pub fn parse_header(bytes: &[u8]) -> crate::Result<()> {
+        crate::format::Header::from_page(bytes).map(|_| ())
+    }
+
+    /// Replay the WAL scan over an arbitrary byte region. Delegates
+    /// to [`crate::wal::recover_bytes`]; a corrupt / truncated /
+    /// adversarial region must return `Err` or `Ok(None/Some(_))`,
+    /// never panic.
+    pub fn wal_recover_bytes(region: &[u8], wal_seq: u64) -> crate::Result<()> {
+        crate::wal::recover_bytes(region, wal_seq).map(|_| ())
+    }
+
+    /// Decode a `Memory` record body from arbitrary bytes.
+    pub fn decode_memory(bytes: &[u8]) -> crate::Result<()> {
+        rmp_serde::from_slice::<crate::Memory>(bytes)
+            .map(|_| ())
+            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
+    }
+
+    /// Decode a `CacheEntry` record body from arbitrary bytes. Type is
+    /// `pub(crate)`, so this wrapper hides it behind a unit return.
+    pub fn decode_cache_entry(bytes: &[u8]) -> crate::Result<()> {
+        rmp_serde::from_slice::<crate::result_cache::CacheEntry>(bytes)
+            .map(|_| ())
+            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
+    }
+
+    /// Decode a cache-directory page-run body (a `Vec<CacheDirectoryEntry>`)
+    /// from arbitrary bytes.
+    pub fn decode_cache_directory(bytes: &[u8]) -> crate::Result<()> {
+        rmp_serde::from_slice::<Vec<crate::result_cache::CacheDirectoryEntry>>(bytes)
+            .map(|_| ())
+            .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
+    }
+
+    /// Parse a single MCP stdio JSON-RPC request line. Malformed
+    /// input returns `Err(String)`; the fuzz target only asserts
+    /// no panic and that the server would not die on this line.
+    pub fn parse_mcp_request_line(line: &str) -> Result<(), String> {
+        crate::mcp::__fuzz_parse_request_line(line)
+    }
+}

{mnemo_engine-0.4.0 → mnemo_engine-0.4.1}/mnemo/src/mcp.rs

@@ -60,6 +60,17 @@ const PROTOCOL_VERSION: &str = "2025-06-18";
 /// Environment variable that supplies the database passphrase.
 const PASSPHRASE_ENV: &str = "MNEMO_PASSPHRASE";
 
+/// Fuzz-target helper: parse a single JSON-RPC line as a `Request` and
+/// discard. Panic-free — malformed input returns `Err(String)`, valid
+/// requests return `Ok(())`. Exposed only via `crate::__fuzz`; not part
+/// of the stable public API.
+#[doc(hidden)]
+pub fn __fuzz_parse_request_line(line: &str) -> std::result::Result<(), String> {
+    serde_json::from_str::<Request>(line)
+        .map(|_| ())
+        .map_err(|e| e.to_string())
+}
+
 // --- JSON-RPC 2.0 wire types ---------------------------------------------
 
 /// Incoming JSON-RPC 2.0 request or notification (a notification is a