# MMDB — Claude Code Project Guide
## What is this project?
MMDB is a pure-Rust LSM-Tree key-value storage engine, optimized as the backend for [vsdb](https://github.com/rust-util-collections/vsdb). It implements leveled compaction, WAL-based crash recovery, MVCC snapshots, and lock-free reads via `ArcSwap<SuperVersion>`.
## Build & Test
```bash
make all # fmt + lint + test
make test # cargo test && cargo test --release
make lint # cargo clippy --all-targets -- -D warnings (matches CI)
make bench # cargo bench (criterion)
cargo test --test integration # integration tests only
cargo test --test crash_recovery
cargo test --test e2e_scenarios
cargo test --test proptest_db
```
MSRV: Rust 1.89 (edition 2024)
## Architecture
| Write path | `src/db.rs` | Group commit: WAL → MemTable |
| Read path | `src/db.rs` | Lock-free via `ArcSwap<SuperVersion>` |
| MemTable | `src/memtable/` | Lock-free skiplist (single-writer, multi-reader) |
| WAL | `src/wal/` | Crash recovery, block-based records with CRC32 |
| SST | `src/sst/` | Prefix-compressed blocks, bloom filters, LZ4/Zstd |
| Iterator | `src/iterator/` | Heap merge, range tombstones, bidirectional |
| Compaction | `src/compaction/leveled.rs` | Leveled strategy, sub-compaction parallelism |
| Manifest | `src/manifest/` | VersionSet, atomic version edits |
| Cache | `src/cache/` | Block cache (moka SegmentedCache via BlockCachePool), table handle cache |
## Skills
Project skills live under `.claude/skills/<name>/SKILL.md` and are
user-invocable only.
- `/x-review` — deep regression analysis of recent changes
- `/x-fix` — fix audit backlog: resolve `docs/audit.md` → self-review → commit
- `/x-commit` — self-reviewing commit: review uncommitted changes → fix → commit
- `/x-overhaul` — full codebase overhaul: review all → fix → commit
Supporting documentation in `.claude/docs/`:
- `workflow-policy.md` — shared worktree safety and one-issue-one-commit policy
- `technical-patterns.md` — cataloged bug patterns for LSM-Tree/Rust
- `review-core.md` — systematic review methodology + canonical Subsystem Map (file → subsystem → pattern guide)
- `false-positive-guide.md` — rules for filtering spurious findings
- `commit-protocol.md` — canonical atomic validate → commit → final version + release tag procedure
- `patterns/` — per-subsystem review guides (compaction, iterator, WAL, SST, memtable, manifest, cache, concurrency, unsafe-audit)
Audit registry: `docs/audit.md` (project root) — auto-managed by `/x-review` and `/x-fix`; it separates actionable Open findings, accepted Won't Fix risks, and disproven Rejected claims.
## Conventions
- All clippy warnings are errors (CI enforced)
- **No `#[allow(...)]`** — fix warnings at the source, never suppress them
- **Prefer imports over inline paths** — avoid `std::foo::Bar::new()` inline in function bodies when the same path appears 3+ times in a file; add `use std::foo;` at file top (or `use std::foo::Bar;`) instead. Function-body `use` statements (scoped imports) are fine and don't count as inline paths. 1-2 inline uses of common `std::` items are acceptable.
- **Grouped imports** — merge common prefixes: `use std::sync::{Arc, Mutex};`
- **Doc-code alignment** — public API changes must update corresponding docs
- `parking_lot` for Mutex/RwLock (non-reentrant, no poisoning)
- Typed errors: `Error`/`ErrorKind` in `src/error.rs` (hand-rolled, no thiserror/ruc); propagate with `.ctx()` / `.with_ctx(|| ..)` — each hop records `file:line:column` via `#[track_caller]`
- `tracing` for logging
- Tests use `tempfile` for isolated DB directories
- Feature `test-utils` exposes `DB::simulate_crash()` for durability tests
- Unsafe code is concentrated in the skiplist, group-commit/file-lock paths, and the SST readahead syscall; derive the live inventory and follow `.claude/docs/patterns/unsafe-audit.md`
- Only the curated re-exports in `src/lib.rs` are public API; all modules are private — internal refactors are not breaking changes
- **No Co-Authored-By in commits** — never add `Co-Authored-By:` or similar trailers to commit messages; project commits are authored only by the human contributor