# bison-db v0.7.0 — Beta: soak testing

**Correctness under load.** With the API and on-disk format frozen, v0.7.0 proves
the store stays correct while it runs: a seeded stress/soak test drives thousands
of randomized mixed operations against a reference model, plus error-path
coverage and a written competitive analysis. Zero breaking changes against
v0.6.0.

## What is bison-db?

An embedded, document-oriented database for Rust: store schemaless documents
entirely in-process, with no server, no network, and no external services. The
whole database is one file, writes are appended to a checksummed log, and a crash
never leaves a half-written record behind.

## What's new in 0.7.0

### Stress / soak test

`tests/stress.rs` runs a long, deterministic sequence of randomized operations
against an in-memory reference model and checks that the store matches the model
throughout. Each step is a random **insert, update, delete, read-back,
compaction, or close-and-reopen**, driven by a seeded xorshift PRNG so any
failure reproduces exactly. The check covers:

- **Live contents** — `len()` and every live id's document equal the model;
  absent ids read back as `None`.
- **The secondary index** — `find` over every group equals the model filtered by
  that group, after arbitrary interleavings of writes, compaction, and reopen.
- **Durability and recovery** — periodic flush-drop-reopen (rebuilding the index,
  which is in-memory by design) and a final reopen-and-verify.

This is the test that exercises the whole stack at once — encoding, framing,
recovery, compaction, and index maintenance — and catches the cross-cutting bugs
that single-operation unit tests cannot.

### Error-path coverage

- An oversized value (past `MAX_RECORD_BYTES`) is rejected with
  `Error::ValueTooLarge` **before** any state changes — the store's length is
  unchanged and no document id is consumed, so a rejected write is a clean no-op.
- `compact` preserves the store's `SyncPolicy`, so a compacted `Always` store is
  still durable-per-write afterward.

### Competitive analysis — `docs/PERFORMANCE.md`

A new **"How it compares"** section makes the architectural case honestly. The
decisive factor against a networked document database (MongoDB and the like) is
not micro-optimization — it is that bison-db does the work *in process*. A
networked query pays serialization plus a socket round trip plus a second
process, measured in hundreds of microseconds to milliseconds before any indexing
work; a bison-db read is a function call at **~0.36 µs**. For in-process storage
that is a structural advantage of roughly **three orders of magnitude on point
operations** — with the explicit, honest trade-off that bison-db is embedded and
single-process by design, not a replacement for a multi-host server database.

A *controlled* head-to-head against peer engines (a pure-Rust embedded store such
as `redb`/`sled`, and a document database) is scheduled for the release-candidate
cycle, where it can be set up fairly without adding a heavy benchmark dependency
to the library.

## Performance

Unchanged from v0.6.0 (medians, Linux/WSL2, x86_64, Rust 1.95, release):

| Operation | Median |
|-----------|-------:|
| `insert` (`Manual`, small doc) | ~0.9 µs |
| `get` (small doc) | ~0.36 µs |
| `find` by indexed field (10k docs) | ~65 ns |
| `find` by full scan (10k docs) | ~1.8 ms |

## Breaking changes

**None.** This release adds tests and documentation; no public item changed.

## Verification

Run on Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable 1.95.x; the same
commands run in the CI matrix across Linux, macOS, and Windows on stable and
MSRV 1.85:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo build --examples
cargo audit
cargo deny check
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
```

All green; `cargo audit` and `cargo deny` clean. Test counts at this tag
(`--all-features`): 54 unit + 9 integration + 3 concurrency + 3 robustness +
3 property + 1 soak + 58 doctests.

## What's next

- **v0.8.0 → 1.0.0 — RC / Stable.** A controlled head-to-head benchmark against
  peer engines, real-consumer integration, and a final soak, then publish 1.0
  with the API and format already frozen.

## Installation

```toml
[dependencies]
bison-db = "0.7"

# With serde support for the document model:
bison-db = { version = "0.7", features = ["serde"] }
```

MSRV: Rust 1.85 (2024 edition).

## Documentation

- [README](https://github.com/jamesgober/bison-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/bison-db/blob/main/docs/API.md)
- [On-disk Format](https://github.com/jamesgober/bison-db/blob/main/docs/FORMAT.md)
- [Performance](https://github.com/jamesgober/bison-db/blob/main/docs/PERFORMANCE.md)
- [Roadmap](https://github.com/jamesgober/bison-db/blob/main/dev/ROADMAP.md)
- [CHANGELOG](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.6.0...v0.7.0`](https://github.com/jamesgober/bison-db/compare/v0.6.0...v0.7.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md#070---2026-06-08).
