# Benchmarks

`tests/bench/` holds performance benches for storage / parser hot paths. Each
runner is a separate binary built into its own subdirectory.

## Runners

| Runner | Path | Measures |
|---|---|---|
| `bench_runner` | `tests/bench/bench_runner/` | General-purpose runner; orchestrates other benches. |
| `bench_export_import` | `tests/bench/bench_export_import/` | Database export/import throughput (SQLite + flatfile). |
| `bench_failure_modes` | `tests/bench/bench_failure_modes/` | Flatfile parser error/recovery paths. |
| `bench_long_messages` | `tests/bench/bench_long_messages/` | Flatfile parser on very long messages. |
| `gen_history` | `tests/bench/gen_history/` | Generates synthetic chat history fixtures used by other benches. |

Each runner pulls in a small set of `src/*.c` files (`common.c`,
`database.c`, `database_flatfile*.c`, etc.) — see the per-runner Makefile or
top-level `Makefile.am` for exact dependencies.

## Stubs

Benches use their own minimal stubs (typically `bench_stubs.c`,
`bench_common.c`, `bench_csv.c` per runner) — separate from
`tests/unittests/` stubs to keep the bench builds small.

## Running

Benches are not part of `make check`. Build and invoke each runner directly
once configured:

```sh
make tests/bench/bench_runner/bench_runner
./tests/bench/bench_runner/bench_runner [args]
```

(Argument shape per-runner; check `--help`.)

## Output

Runners typically emit CSV (`bench_csv.c`) for downstream tooling. Treat
output as machine-readable; do not parse the human header lines.

## When to add a bench

- A storage / parser hot path is sensitive to regression.
- A perf claim in a PR needs to be reproducible.

If it's just a one-off measurement, run it locally and don't commit. The
bench runners are for sustained, comparable measurement.