libgrovedb: add benchmark plan

Author: kwvg

src/ffi/grovedb/BENCH_PLAN.md

@@ -0,0 +1,168 @@
+# GroveDB Benchmark Implementation Plan
+
+## Context
+
+All 7 phases (28 commits) of the GroveDB FFI are complete on `grovedb_p2`. Benchmarks
+are needed for each API phase (0-6) so they can be interleaved between the implementation
+commits. They use **nanobench** (vendored at `src/bench/vendor/nanobench.h` v4.3.11) and
+follow Dash Core's `BenchRunner` + `BENCHMARK()` macro auto-registration pattern.
+
+GroveDB-specific `OperationCost` fields appear **inside the markdown table** alongside
+wall-clock timing, since these are used for fee calculation in Dash Platform.
+
+---
+
+## Coding Rules
+
+- **Indent**: 2 spaces for `.h`, `.cpp`
+- **Namespaces**: Nested definition (`namespace grovedb {`), never `namespace xx::yy`
+- **Header guards**: `GROVEDB_` prefix for `src/` headers
+- **Header visibility**: Bench targets only use public headers from `include/grovedb/`
+- **Exception averse**: Never throw our own exceptions
+- **Build**: Bench is **Meson-only** (no `sources.mk` entries)
+
+---
+
+## Key Design Decisions
+
+### 1. OperationCost IN the Markdown Table
+
+1. `bench.output(nullptr)` - suppress nanobench's default table
+2. Before each `bench.run()`, pre-execute the operation once for `OperationCost`,
+   store as context via `SetCostContext(bench, cost)`
+3. After all benchmarks, call `RenderWithCosts(results, std::cout)` - iterates
+   results and formats timing + cost columns into a markdown table
+
+### 2. Framework: Dash Core BenchRunner Pattern
+
+- `BenchFunction = std::function<void(ankerl::nanobench::Bench&)>`
+- `BenchRunner` with static `benchmarks()` map, constructor-based auto-registration
+- `BENCHMARK(n)` macro creating a static `BenchRunner` at file scope
+- `Args` struct with `is_list_only` and `regex_filter` fields
+
+### 3. Shared Infrastructure
+
+- `TempDir` from `src/test/util/`
+- `MakeKey(i, len)`, `MakeValue(i, len)` - deterministic byte generation
+- `PopulateDb(db, n, key_len, val_len)` - pre-fill a tree
+- `SetCostContext(bench, cost)` / `ClearCostContext(bench)` - cost context
+
+---
+
+## Benchmark Catalog
+
+### Phase 0: Element (`bench_element.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `ElementItem` | `Element::Item(bytes)` |
+| `ElementEmptyTree` | `Element::EmptyTree()` |
+| `ElementEmptySumTree` | `Element::EmptySumTree()` |
+| `ElementSumItem` | `Element::SumItem(42)` |
+
+### Phase 1: CRUD (`bench_crud.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `Open` | `Db::Open` |
+| `Flush` | `Db::Flush` |
+| `GetRootHash` | `Db::GetRootHash` |
+| `PutSequential` | `Db::Put` (sequential keys) |
+| `PutRandom` | `Db::Put` (random keys into 10K tree) |
+| `GetHit` | `Db::Get` (known key) |
+| `GetMiss` | `Db::Get` (non-existent key) |
+| `GetDirect` | `Db::GetDirect` |
+| `GetOptionalHit` | `Db::GetOptional` (existing key) |
+| `GetOptionalMiss` | `Db::GetOptional` (missing key) |
+| `KeyExistsHit` | `Db::KeyExists` (existing key) |
+| `KeyExistsMiss` | `Db::KeyExists` (missing key) |
+| `SubtreeExists` | `Db::SubtreeExists` (3-level path) |
+| `IsEmptyTree` | `Db::IsEmptyTree` |
+| `PutIfAbsentNew` | `Db::PutIfAbsent` (key absent) |
+| `PutIfAbsentExists` | `Db::PutIfAbsent` (key present) |
+| `PutIfChangedSame` | `Db::PutIfChanged` (same value) |
+| `PutIfChangedDiff` | `Db::PutIfChanged` (different value) |
+| `TxnBeginCommitEmpty` | `BeginTransaction` + `Commit` |
+| `TxnPutCommit` | `Put` in txn + `Commit` |
+| `TxnGetOverhead` | `Get` with txn vs plain |
+
+### Phase 2: Delete (`bench_delete.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `Delete` | `Db::Delete` |
+| `DeleteIfEmptyTrue` | `Db::DeleteIfEmpty` (empty subtree) |
+| `DeleteIfEmptyFalse` | `Db::DeleteIfEmpty` (non-empty) |
+| `PruneEmptyAncestors` | `Db::PruneEmptyAncestors` |
+| `Clear` | `Db::Clear` |
+
+### Phase 3: Query (`bench_query.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `QueryValuesKey` | `QueryValues` + `QueryItem::Key` |
+| `QueryValuesRange10` | `QueryValues` + `RangeFull` limit=100 |
+| `QueryValuesRange100` | `QueryValues` + `RangeFull` (full scan) |
+| `QueryValuesLimit` | `QueryValues` limit=10 on 10K tree |
+| `QueryRawElement` | `QueryRaw` result_type=0 |
+| `QueryRawKeyElement` | `QueryRaw` result_type=1 |
+| `QueryRawPathKeyElement` | `QueryRaw` result_type=2 |
+| `QuerySums` | `QuerySums` (1K SumItems) |
+| `QueryItemsOrSums` | `QueryItemsOrSums` |
+| `QueryKeysOptional` | `QueryKeysOptional` |
+
+### Phase 4: Proof (`bench_proof.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `ProveSingleKey` | `Db::Prove` (1 Key item) |
+| `ProveRange` | `Db::Prove` (Range item) |
+| `VerifyQuery` | `Db::VerifyQuery` |
+| `VerifySubsetQuery` | `Db::VerifySubsetQuery` |
+| `ProveVerifyRoundTrip` | `Prove` + `VerifyQuery` |
+
+### Phase 5: Batch (`bench_batch.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `BatchInsert10` | `ApplyBatch` (10 ops) |
+| `BatchInsert100` | `ApplyBatch` (100 ops) |
+| `BatchInsert1000` | `ApplyBatch` (1000 ops) |
+| `BatchMixed100` | `ApplyBatch` (50 insert + 50 delete) |
+| `BatchReplace100` | `ApplyBatch` (100 Replace ops) |
+| `BatchDeleteTree` | `ApplyBatch` (subtree deletion) |
+| `BatchInTxn100` | `ApplyBatch(ops, opts, txn)` |
+
+### Phase 6: Auxiliary + Checkpoint (`bench_aux.cpp`)
+
+| Benchmark | API |
+|-----------|-----|
+| `PutAux` | `Db::PutAux` |
+| `GetAuxHit` | `Db::GetAux` (existing key) |
+| `GetAuxMiss` | `Db::GetAux` (missing key) |
+| `DeleteAux` | `Db::DeleteAux` |
+| `FindSubtrees` | `Db::FindSubtrees` |
+| `CreateCheckpoint` | `Db::CreateCheckpoint` |
+
+---
+
+## Verification
+
+```bash
+# Setup bench build directory
+meson setup /tmp/grovedb_benchdir src/ffi/grovedb \
+  -Dbuild_bench=true \
+  -Dgrovedb_cxx_build_dir=$(pwd)/rust/builddir/subprojects/grovedb_cxx
+
+# Compile
+meson compile -C /tmp/grovedb_benchdir
+
+# Run all benchmarks
+/tmp/grovedb_benchdir/src/bench/bench_grovedb
+
+# Run filtered
+/tmp/grovedb_benchdir/src/bench/bench_grovedb --filter="Get.*"
+
+# List only
+/tmp/grovedb_benchdir/src/bench/bench_grovedb --list
+```