salamander-db 0.1.0__tar.gz

salamander_db-0.1.0/Cargo.toml

@@ -0,0 +1,12 @@
+[workspace]
+resolver = "2"
+members = ["salamander", "salamander-demo"]
+# The Python extension is built by maturin, not the main gate — it links
+# libpython and only makes sense inside a Python build. Excluding it keeps
+# `cargo build/test/clippy` at the root pure Rust.
+exclude = ["salamander-py"]
+
+[workspace.package]
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/rdelprete/salamander-db"

salamander_db-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: salamander-db
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Summary: SQLite for event-sourced state — Python bindings for salamander-db.
+Keywords: event-sourcing,embedded,database,agent
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/rdelprete/salamander-db
+
+# salamander-db (Python)
+
+Native Python bindings for [salamander-db](../) — **SQLite for event-sourced
+state**. This is a compiled extension (via [PyO3](https://pyo3.rs) +
+[maturin](https://www.maturin.rs)), so it embeds the engine *in your process*
+exactly like Python's built-in `sqlite3` module wraps `libsqlite3`: you open
+one handle and reuse it. No server, no subprocess.
+
+The binding is a translation layer over the safe, non-generic Rust `Engine`.
+Database ownership and cross-thread sequencing live in the core; Python does
+not contain storage, replay, branching, or projection algorithms.
+
+```python
+import salamander
+
+db = salamander.open("./mem", commit_every_count=8)   # one in-process handle
+db.append("session-1", {"kind": "user_msg", "text": "hi"})
+db.append("session-1", {"kind": "tool_call", "tool": "grep", "args": {"q": "500"}})
+db.commit()
+
+for ev in db.replay("session-1"):
+    print(ev["offset"], ev["body"])          # -> plain dicts, nested fields intact
+```
+
+The open handle owns the single-writer lock, any registered views, and the
+group-commit state — which is why it must be long-lived and in-process, not
+re-created per call.
+
+## Build it
+
+Requires a Rust toolchain and Python ≥ 3.9.
+
+```bash
+python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install maturin pytest
+maturin develop -m salamander-py/Cargo.toml          # compiles + installs into the venv
+python examples/py/quickstart.py
+python -m pytest examples/py/test_roundtrip.py -v
+```
+
+On a very new Python that the pinned PyO3 doesn't recognize yet, prefix the
+build with `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` (the abi3 stable ABI is
+forward-compatible).
+
+## API
+
+| Python | Engine |
+|---|---|
+| `salamander.open(path, commit_every_bytes=, commit_every_count=, commit_every_millis=)` | `JsonDb::open_with_policy` |
+| `db.append(namespace, event: dict) -> int` | `append` (payload = JSON) |
+| `db.append_branch(branch, namespace, event) -> int` | append to an engine branch |
+| `db.commit() -> int` | `commit` (fsync) |
+| `db.head() -> int` | `head` |
+| `db.uncommitted_count() -> int` | group-commit tally |
+| `db.replay(namespace, start=0, end=None) -> list[dict]` | `replay` (literal) |
+| `db.register_view(name, key, indexes={}, where_field=, where_value=)` | register an `IndexedView` |
+| `db.view(name) -> View` | typed query handle |
+| `db.deregister_view(name) -> bool` | `deregister` |
+| `db.fork(namespace, at) -> str` | create branch (returns branch name) |
+| `db.history(namespace) -> list[dict]` | default-branch replay |
+| `db.branch_history(branch, namespace) -> list[dict]` | inherited branch replay |
+
+`View` handles support `.get(key)`, `.by(index, key)`, `.range(lo, hi)`,
+`.prefix(p)`, `.len()`.
+
+Payloads are any JSON-able Python value (`dict`/`list`/`str`/`int`/`float`/
+`bool`/`None`), converted to/from `serde_json::Value` at the boundary. Views
+are declared by field name (primary `key`, `indexes` mapping name→field, an
+optional `where_field`/`where_value` filter) — no per-event Python callback
+crosses the FFI boundary.
+
+A LangGraph checkpointer that survives process restarts ships in
+[`examples/py/`](../examples/py); an MCP server is on the
+[roadmap](../ROADMAP.md). Branch lifecycle and ancestry use the same engine
+catalog as Rust:
+
+```python
+ancestry = db.branch_ancestry(branch_name)  # root-first metadata dictionaries
+archived = db.archive_branch(branch_name)  # history remains readable
+```
+

salamander_db-0.1.0/README.md

@@ -0,0 +1,80 @@
+# salamander-db (Python)
+
+Native Python bindings for [salamander-db](../) — **SQLite for event-sourced
+state**. This is a compiled extension (via [PyO3](https://pyo3.rs) +
+[maturin](https://www.maturin.rs)), so it embeds the engine *in your process*
+exactly like Python's built-in `sqlite3` module wraps `libsqlite3`: you open
+one handle and reuse it. No server, no subprocess.
+
+The binding is a translation layer over the safe, non-generic Rust `Engine`.
+Database ownership and cross-thread sequencing live in the core; Python does
+not contain storage, replay, branching, or projection algorithms.
+
+```python
+import salamander
+
+db = salamander.open("./mem", commit_every_count=8)   # one in-process handle
+db.append("session-1", {"kind": "user_msg", "text": "hi"})
+db.append("session-1", {"kind": "tool_call", "tool": "grep", "args": {"q": "500"}})
+db.commit()
+
+for ev in db.replay("session-1"):
+    print(ev["offset"], ev["body"])          # -> plain dicts, nested fields intact
+```
+
+The open handle owns the single-writer lock, any registered views, and the
+group-commit state — which is why it must be long-lived and in-process, not
+re-created per call.
+
+## Build it
+
+Requires a Rust toolchain and Python ≥ 3.9.
+
+```bash
+python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install maturin pytest
+maturin develop -m salamander-py/Cargo.toml          # compiles + installs into the venv
+python examples/py/quickstart.py
+python -m pytest examples/py/test_roundtrip.py -v
+```
+
+On a very new Python that the pinned PyO3 doesn't recognize yet, prefix the
+build with `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` (the abi3 stable ABI is
+forward-compatible).
+
+## API
+
+| Python | Engine |
+|---|---|
+| `salamander.open(path, commit_every_bytes=, commit_every_count=, commit_every_millis=)` | `JsonDb::open_with_policy` |
+| `db.append(namespace, event: dict) -> int` | `append` (payload = JSON) |
+| `db.append_branch(branch, namespace, event) -> int` | append to an engine branch |
+| `db.commit() -> int` | `commit` (fsync) |
+| `db.head() -> int` | `head` |
+| `db.uncommitted_count() -> int` | group-commit tally |
+| `db.replay(namespace, start=0, end=None) -> list[dict]` | `replay` (literal) |
+| `db.register_view(name, key, indexes={}, where_field=, where_value=)` | register an `IndexedView` |
+| `db.view(name) -> View` | typed query handle |
+| `db.deregister_view(name) -> bool` | `deregister` |
+| `db.fork(namespace, at) -> str` | create branch (returns branch name) |
+| `db.history(namespace) -> list[dict]` | default-branch replay |
+| `db.branch_history(branch, namespace) -> list[dict]` | inherited branch replay |
+
+`View` handles support `.get(key)`, `.by(index, key)`, `.range(lo, hi)`,
+`.prefix(p)`, `.len()`.
+
+Payloads are any JSON-able Python value (`dict`/`list`/`str`/`int`/`float`/
+`bool`/`None`), converted to/from `serde_json::Value` at the boundary. Views
+are declared by field name (primary `key`, `indexes` mapping name→field, an
+optional `where_field`/`where_value` filter) — no per-event Python callback
+crosses the FFI boundary.
+
+A LangGraph checkpointer that survives process restarts ships in
+[`examples/py/`](../examples/py); an MCP server is on the
+[roadmap](../ROADMAP.md). Branch lifecycle and ancestry use the same engine
+catalog as Rust:
+
+```python
+ancestry = db.branch_ancestry(branch_name)  # root-first metadata dictionaries
+archived = db.archive_branch(branch_name)  # history remains readable
+```

salamander_db-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["maturin>=1.5,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "salamander-db"
+# Sourced from salamander-py/Cargo.toml by maturin — one place to bump.
+dynamic = ["version"]
+description = "SQLite for event-sourced state — Python bindings for salamander-db."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["event-sourcing", "embedded", "database", "agent"]
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Repository = "https://github.com/rdelprete/salamander-db"
+
+[tool.maturin]
+# The Rust cdylib lib is named `salamander`, which is the Python import name;
+# the distribution ("salamander-db") differs, mirroring the Rust package/lib
+# split. abi3 gives one wheel across CPython 3.9+.
+module-name = "salamander"
+features = ["pyo3/extension-module"]
+manifest-path = "salamander-py/Cargo.toml"

salamander_db-0.1.0/salamander/Cargo.toml

@@ -0,0 +1,52 @@
+[package]
+name = "salamander-db"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Embedded event-sourcing engine with instant recovery — the append-only log is the only durable structure."
+readme = "README.md"
+documentation = "https://docs.rs/salamander-db"
+homepage = "https://github.com/rdelprete/salamander-db"
+keywords = ["event-sourcing", "embedded", "database", "wal", "agent"]
+categories = ["database-implementations", "data-structures"]
+rust-version = "1.90"
+# Integration tests and their fixtures are development-only; keep them out
+# of the published crate (the lib, examples, and benches ship).
+exclude = ["tests/"]
+
+[lib]
+name = "salamander"
+path = "src/lib.rs"
+
+[dependencies]
+crc32c = "0.6"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+bincode = "1.3"
+thiserror = "1"
+
+[dev-dependencies]
+proptest = "1"
+criterion = "0.5"
+tempfile = "3"
+
+[[bench]]
+name = "open_time"
+harness = false
+
+[[bench]]
+name = "view_apply"
+harness = false
+
+[[bench]]
+name = "replay"
+harness = false
+
+[[bench]]
+name = "snapshots"
+harness = false
+
+[[bench]]
+name = "instant_recovery"
+harness = false

salamander_db-0.1.0/salamander/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raffaele Del Prete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

salamander_db-0.1.0/salamander/README.md

@@ -0,0 +1,55 @@
+# salamander-db
+
+**SQLite for event-sourced state — built first for agent memory.**
+
+An embedded event-sourcing engine. The append-only log is the only durable
+structure; everything else is a rebuildable projection. Replay, time-travel,
+and fork are first-class: rewind any session to step N, branch it, and run
+two futures against the same history.
+
+Second story: **crash-proof application state.** The torn-tail rule makes
+"state that never logically existed" impossible after a kill — and the full
+history comes free.
+
+```rust
+use salamander::agent::{EventBody, KvProjection};
+use salamander::{AgentDb, Projection};
+
+let mut db = AgentDb::open("./mydata")?;
+db.append("session-1", EventBody::Put { key: "k".into(), value: b"v".to_vec() })?;
+db.commit()?;                                  // fsync; durable
+
+// Everything else rebuilds from the log:
+let kv: KvProjection = db.projection()?;       // full replay
+let past: KvProjection = db.view_at(1)?;       // state as of offset 1 (time-travel)
+```
+
+## Features
+
+- **Segmented append-only log** — CRC32C framing, torn-tail truncation on
+  open, atomic manifest, single-writer lock.
+- **Projections** — deterministic folds of the log; `KvProjection`,
+  `SessionProjection`, or your own via the `Projection` trait.
+- **Time-travel & fork** — `view_at(n)`; `fork(ns, n)` branches a session
+  while the log stays linear.
+- **Payload-generic** — `Salamander<B>` over any serde payload; a provided
+  `agent` vocabulary, `JsonDb` for dynamic JSON, or bring your own enum.
+- **Query layer** — live registered views with secondary indexes:
+  `get` / `range` / `prefix` / `by`, maintained incrementally (never stale).
+- **Group commit** — combinable byte/count/time commit policies.
+- **Crash-tested** — a `kill -9` harness asserts the core invariant across
+  thousands of crashes.
+
+## Status
+
+Phase 1 core + Phase 1.5 (payload-generic engine, query layer, group commit,
+dynamic-JSON payloads) complete. Single-writer, embedded, in-memory
+projections (persistence is Phase 2). Not multi-writer, not a SQL/query
+language, not a vector store — by design.
+
+Roadmap, changelog, and runnable examples:
+<https://github.com/rdelprete/salamander-db>
+
+## License
+
+MIT

salamander_db-0.1.0/salamander/benches/instant_recovery.rs

@@ -0,0 +1,85 @@
+use std::collections::BTreeMap;
+
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use salamander::{
+    DurabilityDto, Engine, EngineAppendBatch, EngineOptions, EventData, ExpectedRevisionDto,
+    PayloadCodec, QueryConsistency, QueryDefinition, QueryOperation,
+};
+
+fn fixture(events: usize) -> tempfile::TempDir {
+    let dir = tempfile::tempdir().unwrap();
+    let engine = Engine::open(EngineOptions::new(dir.path())).unwrap();
+    for index in 0..events {
+        engine
+            .append(EngineAppendBatch {
+                branch_id: [0; 16],
+                stream: format!("s{}", index % 128),
+                expected: ExpectedRevisionDto::Any,
+                idempotency_key: None,
+                durability: DurabilityDto::Buffered,
+                events: vec![EventData {
+                    event_id: None,
+                    event_type: "row".into(),
+                    schema_version: 1,
+                    metadata: BTreeMap::new(),
+                    codec: PayloadCodec::Json,
+                    payload: serde_json::to_vec(&serde_json::json!({"id": format!("k{index}")}))
+                        .unwrap(),
+                }],
+            })
+            .unwrap();
+    }
+    engine.commit().unwrap();
+    engine
+        .register_partitioned_query(
+            "rows".into(),
+            QueryDefinition {
+                key_field: "id".into(),
+                indexes: BTreeMap::new(),
+                filter: None,
+            },
+            64,
+        )
+        .unwrap();
+    engine.close().unwrap();
+    dir
+}
+
+fn bench(c: &mut Criterion) {
+    let fixture = fixture(100_000);
+    c.bench_function("instant_recovery/open_catalog_only", |b| {
+        b.iter(|| {
+            let engine = Engine::open(EngineOptions::new(fixture.path())).unwrap();
+            black_box(engine.head().unwrap());
+            engine.close().unwrap();
+        })
+    });
+    c.bench_function("instant_recovery/heal_one_partition", |b| {
+        b.iter(|| {
+            let engine = Engine::open(EngineOptions::new(fixture.path())).unwrap();
+            let handle = engine.query_named("rows".into()).unwrap();
+            black_box(
+                engine
+                    .query_partitions(
+                        handle,
+                        vec![0],
+                        QueryOperation::Len,
+                        QueryConsistency::RequireHead,
+                    )
+                    .unwrap(),
+            );
+            engine.close().unwrap();
+        })
+    });
+    c.bench_function("instant_recovery/heal_all_partitions", |b| {
+        b.iter(|| {
+            let engine = Engine::open(EngineOptions::new(fixture.path())).unwrap();
+            let handle = engine.query_named("rows".into()).unwrap();
+            black_box(engine.query(handle, QueryOperation::Len).unwrap());
+            engine.close().unwrap();
+        })
+    });
+}
+
+criterion_group!(benches, bench);
+criterion_main!(benches);

salamander_db-0.1.0/salamander/benches/open_time.rs

@@ -0,0 +1,96 @@
+//! M5 — IMPLEMENTATION.md Step 7 / DESIGN.md §9.
+//!
+//! Criterion bench: cold-start cost vs. log size — the "baseline villain"
+//! that motivates Phase 2 (DESIGN.md §9, §8). Two measurements per size:
+//!
+//! - `open_only` — `AgentDb::open`, which recovers the *log* (scans the
+//!   active segment for a torn tail) but replays no projections. Roughly
+//!   flat in log size: only the last segment is touched.
+//! - `open_and_replay` — `open` plus a full-log `KvProjection` rebuild.
+//!   Linear in log size — this is the cost Phase 1 pays to reach usable
+//!   derived state, and what instant recovery (Phase 2) exists to erase.
+//!
+//! Sizes come from the `SALAMANDER_BENCH_SIZES` env var (comma-separated
+//! event counts); the default is a quick `100000,1000000`. The canonical
+//! M5 run is:
+//!
+//! ```text
+//! SALAMANDER_BENCH_SIZES=1000000,10000000,50000000 cargo bench --bench open_time
+//! ```
+//!
+//! Fixtures are generated once per size, outside the measured loop.
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use salamander::agent::{EventBody, KvProjection};
+use salamander::{AgentDb, Projection};
+use tempfile::TempDir;
+
+const NAMESPACE: &str = "bench";
+
+fn sizes() -> Vec<u64> {
+    match std::env::var("SALAMANDER_BENCH_SIZES") {
+        Ok(s) => s
+            .split(',')
+            .filter_map(|p| p.trim().parse::<u64>().ok())
+            .filter(|&n| n > 0)
+            .collect(),
+        Err(_) => vec![100_000, 1_000_000],
+    }
+}
+
+/// Build a fixture directory holding `n` committed events. One constant key
+/// keeps the projection's map size flat, so `open_and_replay` measures the
+/// pure per-event decode+apply cost rather than BTree growth.
+fn populate(n: u64) -> TempDir {
+    let dir = tempfile::tempdir().expect("tempdir");
+    {
+        let mut db = AgentDb::open(dir.path()).expect("open");
+        for i in 0..n {
+            db.append(
+                NAMESPACE,
+                EventBody::Put {
+                    key: "bench".to_string(),
+                    value: i.to_le_bytes().to_vec(),
+                },
+            )
+            .expect("append");
+        }
+        db.commit().expect("commit");
+    } // drop releases the single-writer lock so the bench can reopen freely
+    dir
+}
+
+fn bench_open_time(c: &mut Criterion) {
+    // Generate every fixture up front; each stays alive (as a TempDir) for
+    // the whole run and is cleaned up when this Vec drops.
+    let fixtures: Vec<(u64, TempDir)> = sizes().into_iter().map(|n| (n, populate(n))).collect();
+
+    let mut group = c.benchmark_group("open_time");
+    // Opening a large log is expensive; 10 is criterion's minimum sample
+    // count and keeps a 50M-event run from taking hours.
+    group.sample_size(10);
+
+    for (n, dir) in &fixtures {
+        group.throughput(Throughput::Elements(*n));
+
+        group.bench_with_input(BenchmarkId::new("open_only", n), dir, |b, dir| {
+            b.iter(|| {
+                let db = AgentDb::open(dir.path()).expect("open");
+                black_box(db.head())
+            });
+        });
+
+        group.bench_with_input(BenchmarkId::new("open_and_replay", n), dir, |b, dir| {
+            b.iter(|| {
+                let db = AgentDb::open(dir.path()).expect("open");
+                let kv = db.projection::<KvProjection>().expect("projection");
+                black_box(kv.state().len())
+            });
+        });
+    }
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_open_time);
+criterion_main!(benches);

salamander_db-0.1.0/salamander/benches/replay.rs

@@ -0,0 +1,141 @@
+//! WP-04 — streaming-reader throughput and selectivity.
+//!
+//! Three measurements per size:
+//!
+//! - `full_scan` — stream every record through the bounded reader
+//!   (replaces the old materializing scan; linear, but O(1) memory).
+//! - `single_stream` — a `StreamSelector::Streams` plan for one of
+//!   `STREAM_FAN` streams. With sidecar postings this touches only the
+//!   selected records' segments; the gap to `full_scan / STREAM_FAN`
+//!   measures the selective-read win WP-09 healing relies on.
+//! - `tail_seek` — read the final 100 records. Sub-linear thanks to
+//!   segment binary search plus in-segment seek points.
+//!
+//! Sizes come from `SALAMANDER_BENCH_SIZES` (comma-separated counts);
+//! default `100000,1000000`. The spec's canonical runs:
+//!
+//! ```text
+//! SALAMANDER_BENCH_SIZES=1000000 cargo bench --bench replay
+//! SALAMANDER_BENCH_SIZES=10000000 cargo bench --bench replay   # 10M physical
+//! ```
+//!
+//! (The 100M *planning* case is a unit test — `intersecting_range` over
+//! synthetic segment metadata — since it measures index arithmetic, not
+//! I/O.)
+
+use std::ops::Bound;
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use salamander::agent::EventBody;
+use salamander::{
+    AgentDb, AppendRequest, BranchId, Durability, EventType, ExpectedRevision, NewEvent,
+    RecordReader, ReplayPlan, StreamId, StreamName, StreamSelector,
+};
+use tempfile::TempDir;
+
+const STREAM_FAN: u64 = 16;
+
+fn sizes() -> Vec<u64> {
+    match std::env::var("SALAMANDER_BENCH_SIZES") {
+        Ok(s) => s
+            .split(',')
+            .filter_map(|p| p.trim().parse::<u64>().ok())
+            .filter(|&n| n > 0)
+            .collect(),
+        Err(_) => vec![100_000, 1_000_000],
+    }
+}
+
+/// `n` events spread round-robin over `STREAM_FAN` streams, committed in
+/// batches of 64 to keep fixture generation fast. Returns the fixture dir
+/// and one stream's id for selective plans.
+fn populate(n: u64) -> (TempDir, StreamId) {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let mut chosen = None;
+    {
+        let mut db = AgentDb::open(dir.path()).expect("open");
+        let mut appended = 0u64;
+        while appended < n {
+            let stream = appended % STREAM_FAN;
+            let batch = (n - appended).min(64);
+            let receipt = db
+                .append_batch(AppendRequest {
+                    branch: BranchId::ZERO,
+                    stream: StreamName::new(format!("stream-{stream}")).expect("name"),
+                    expected: ExpectedRevision::Any,
+                    idempotency_key: None,
+                    events: (0..batch)
+                        .map(|i| {
+                            NewEvent::new(
+                                EventType::new("bench.put").expect("type"),
+                                EventBody::Put {
+                                    key: "k".into(),
+                                    value: (appended + i).to_le_bytes().to_vec(),
+                                },
+                            )
+                        })
+                        .collect(),
+                    durability: Durability::Buffered,
+                })
+                .expect("append");
+            if stream == 0 {
+                chosen = Some(receipt.stream_id);
+            }
+            appended += batch;
+        }
+        db.commit().expect("commit");
+    }
+    (dir, chosen.expect("at least one batch"))
+}
+
+fn drain(db: &AgentDb, plan: ReplayPlan) -> u64 {
+    let mut reader = db.read(plan).expect("plan");
+    let mut count = 0u64;
+    while reader.next().expect("read").is_some() {
+        count += 1;
+    }
+    count
+}
+
+fn bench_replay(c: &mut Criterion) {
+    let mut group = c.benchmark_group("replay");
+    group.sample_size(10);
+
+    for n in sizes() {
+        let (dir, stream) = populate(n);
+        let db = AgentDb::open(dir.path()).expect("reopen");
+        group.throughput(Throughput::Elements(n));
+
+        group.bench_with_input(BenchmarkId::new("full_scan", n), &n, |b, _| {
+            b.iter(|| black_box(drain(&db, ReplayPlan::default())))
+        });
+
+        group.bench_with_input(BenchmarkId::new("single_stream", n), &n, |b, _| {
+            b.iter(|| {
+                black_box(drain(
+                    &db,
+                    ReplayPlan {
+                        streams: StreamSelector::Streams(vec![stream]),
+                        ..ReplayPlan::default()
+                    },
+                ))
+            })
+        });
+
+        group.bench_with_input(BenchmarkId::new("tail_seek", n), &n, |b, _| {
+            b.iter(|| {
+                black_box(drain(
+                    &db,
+                    ReplayPlan {
+                        from: Bound::Included(n.saturating_sub(100)),
+                        ..ReplayPlan::default()
+                    },
+                ))
+            })
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_replay);
+criterion_main!(benches);