feat(storage): the benchmark rig, and the first LMDB recording

.changeset/benchmark-rig.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/checks.yml

@@ -279,6 +279,17 @@ jobs:
         env:
           PARITY_ADMIN_URL: postgres://postgres:postgres@localhost:5432/postgres
         run: cargo test -p nostream-storage --test migrations --test parity --test migration_pg -- --ignored --test-threads=1
+      # The benchmark rig's Postgres column: the same workload and the same `--verify` the LMDB
+      # arm runs, against the scratch database it drops and recreates. The dev profile is
+      # deliberate — this proves the path and the counts, and its timings are cited nowhere.
+      - name: Benchmark harness against Postgres
+        env:
+          PARITY_ADMIN_URL: postgres://postgres:postgres@localhost:5432/postgres
+        run: cargo run -p nostream-storage --example bench -- --backend postgres --events 2000 --seed 7 --verify --out /tmp/bench-postgres.json
+      # `cargo test --workspace` builds an example target and never runs its tests, so the rig's
+      # own tests need a command that does. They carry the rules `--verify` asserts.
+      - name: Benchmark harness unit tests
+        run: cargo test -p nostream-storage --all-features --example bench
       - name: Storage builds without the Postgres driver
         run: cargo check -p nostream-storage --no-default-features --all-targets
       - name: Release build

CLAUDE.md

@@ -36,9 +36,9 @@ cargo test --workspace --all-features
 cargo build --workspace --all-features --release
 ```
 
-CI additionally runs the three database-backed storage tests ("Storage parity against Postgres")
-against a `postgres:16-alpine` service, and they are `#[ignore]`d so a checkout without a database still passes
-`cargo test --workspace`:
+CI additionally runs five database- and example-backed checks. Three are the storage tests
+("Storage parity against Postgres"), against a `postgres:16-alpine` service; they are `#[ignore]`d
+so a checkout without a database still passes `cargo test --workspace`:
 
 ```
 cargo test -p nostream-storage --test migrations --test parity --test migration_pg \
@@ -48,8 +48,21 @@ cargo test -p nostream-storage --test migrations --test parity --test migration_
 `PARITY_ADMIN_URL` names the administrative database (CI sets
 `postgres://postgres:postgres@localhost:5432/postgres`); the targets create, migrate and
 drop their own scratch databases — `migration_pg` seeds one and copies it into a temporary LMDB
-store. `scripts/storage-parity.sh` runs all three plus the
-TypeScript Cucumber suite against the sqlx-migrated schema — the complete local oracle. The
+store. The fourth is the benchmark rig's Postgres arm ("Benchmark harness against Postgres"):
+it runs `crates/nostream-storage/examples/bench.rs` against a scratch database and proves the path
+and `--verify`, and its numbers are cited nowhere. The fifth, below, is the rig's own unit tests.
+
+The rig's own unit tests need their own command, because `cargo test --workspace` only *builds* an
+example target. CI runs it as "Benchmark harness unit tests", and so must you when you touch the
+rig:
+
+```
+cargo test -p nostream-storage --all-features --example bench
+```
+
+`scripts/storage-parity.sh` runs the three storage targets plus the
+TypeScript Cucumber suite against the sqlx-migrated schema — the local parity oracle. It does not
+run the benchmark rig, which is a measurement and not a parity check. The
 LMDB arm of that oracle needs no database: `cargo test -p nostream-storage --test parity_lmdb
 -- --nocapture` replays the same fixture on a temporary store and runs inside the fifth
 validation command above.

crates/nostream-storage/Cargo.toml

@@ -32,8 +32,17 @@ tracing = { workspace = true, optional = true }
 uuid = { workspace = true, optional = true }
 
 [dev-dependencies]
+clap.workspace = true
 serde_yaml.workspace = true
 tempfile.workspace = true
 
+# The benchmark rig (`docs/rewrite/benchmarks.md`). Both features are required: the harness holds
+# either backend behind one `EventRepository`, so a build that turns one off has nothing to
+# measure. The requirement is also what keeps CI's `--no-default-features --all-targets` check
+# from compiling it.
+[[example]]
+name = "bench"
+required-features = ["lmdb", "postgres"]
+
 [lints]
 workspace = true