mentedb_storage/lib.rs
1//! MenteDB Storage Engine: page-based storage with WAL and buffer pool.
2//!
3//! This crate implements the low-level storage engine:
4//! - **Page manager**: file-backed 64KB pages with free-list allocation
5//! - **Write-ahead log (WAL)**: append-only, CRC-checked, LZ4-compressed entries
6//! - **Buffer pool**: fixed-capacity page cache with CLOCK eviction
7//! - **Storage engine**: unified facade for memory node persistence
8//!
9//! # Concurrency
10//!
11//! Multiple processes can open the same database directory simultaneously.
12//! Writes are serialized via `flock(2)` on the WAL file; reads are lock-free.
13//! In-memory state (page count, LSN counter) is refreshed from disk under the
14//! flock so no process acts on stale data.
15//!
16//! # Example
17//!
18//! ```no_run
19//! use mentedb_storage::StorageEngine;
20//! use mentedb_core::{MemoryNode, memory::MemoryType, types::AgentId};
21//!
22//! let engine = StorageEngine::open("/tmp/mentedb-data".as_ref())?;
23//!
24//! let node = MemoryNode::new(
25//! AgentId::new(),
26//! MemoryType::Episodic,
27//! "The user prefers Rust".to_string(),
28//! vec![0.1, 0.2, 0.3],
29//! );
30//!
31//! let page_id = engine.store_memory(&node)?;
32//! let loaded = engine.load_memory(page_id)?;
33//! assert_eq!(loaded.content, "The user prefers Rust");
34//!
35//! engine.checkpoint()?;
36//! engine.close()?;
37//! # Ok::<(), mentedb_core::error::MenteError>(())
38//! ```
39
40/// Snapshot backup utilities.
41pub mod backup;
42/// Fixed capacity page cache with CLOCK eviction.
43pub mod buffer;
44/// Unified storage facade for memory persistence.
45pub mod engine;
46/// File backed 16KB page manager with free list allocation.
47pub mod page;
48/// Append only write ahead log with CRC checks and LZ4 compression.
49pub mod wal;
50
51// Re-export key types at crate root for convenience.
52pub use buffer::BufferPool;
53pub use engine::StorageEngine;
54pub use page::{PAGE_DATA_SIZE, PAGE_SIZE, Page, PageHeader, PageId, PageType};
55pub use wal::{Lsn, Wal, WalEntry, WalEntryType};