# bison-db v0.6.0 — Alpha: hardening

**Confidence, not features.** The public API (v0.5.0) and on-disk format (v0.4.0)
are already frozen, so v0.6.0 spends its effort proving the store holds up:
fuzz-tested parse and recovery paths, captured benchmarks with a written method,
and a realistic example. Zero breaking changes against v0.5.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.6.0

### Fuzz-tested parse and recovery

A store file is untrusted input the moment it has been copied, truncated, or
damaged — opening one is a parse of potentially hostile bytes. v0.6.0 adds
in-tree, property-based fuzzing that asserts the only acceptable outcomes are a
clean `Ok` or a clean `Err`:

- **The decoder never panics.** Property tests feed arbitrary byte sequences, and
  every single-byte truncation of a valid encoding, to the document decoder; it
  must always terminate with `Ok` or `Err` — never panic, over-read, or allocate
  unbounded.
- **`Db::open` never panics.** Integration tests (`tests/robustness.rs`) write
  arbitrary bytes, randomly mutate the bytes of a valid store, and truncate a
  valid store at every length, then open each one. Opening must not panic; if it
  succeeds, the returned store is internally consistent and every surviving
  document is re-readable.

These complement the existing CRC checks and torn-tail recovery with evidence
that the failure modes are handled, not just intended.

### Captured benchmarks — `docs/PERFORMANCE.md`

The benchmark numbers now have a home, a method, and an environment record. Every
figure is measured against a real on-disk store (encoding, framing, CRC, and
syscalls included) and is reproducible with `cargo bench`. Median results, Linux
(WSL2)/x86_64, Rust 1.95, release profile:

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

The headline relationships: an index makes the same equality query roughly
**27,000×** faster than scanning a 10k-document store, and per-write `fsync`
(`SyncPolicy::Always`) costs about three orders of magnitude over batched
`Manual` + `flush` — a cost set by the storage device, not by bison-db. See
[`docs/PERFORMANCE.md`](https://github.com/jamesgober/bison-db/blob/main/docs/PERFORMANCE.md)
for the full write-up and the reasons the design is fast.

### A realistic example — `session_store`

`examples/session_store.rs` models an embedded web-session store: sessions are
documents keyed by their `DocId`, indexed by `user_id` so "log out everywhere"
is a fast indexed `find`-and-revoke rather than a scan. It opens with
`SyncPolicy::Always` so a login is durable on return, and calls `compact` to
reclaim the space left by revoked sessions — exercising indexes, durability, and
compaction together in one coherent workflow.

## Breaking changes

**None.** This release adds tests, documentation, and one example; 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`): 52 unit + 9 integration + 3 concurrency + 3 robustness +
3 property + 58 doctests.

## What's next

- **v0.7.0 → 1.0.0 — Beta / RC / Stable.** Real-consumer integration, broader
  testing, and a populated head-to-head benchmark, then publish 1.0 with the API
  and format already frozen.

## Installation

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

# With serde support for the document model:
bison-db = { version = "0.6", 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.5.0...v0.6.0`](https://github.com/jamesgober/bison-db/compare/v0.5.0...v0.6.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md#060---2026-06-08).
