# txn-db v0.7.0 — Hardening & API freeze

**The public API is frozen.** v0.7.0 puts the feature-complete engine through
adversarial schedules and edge cases, re-verifies the durable path across
platforms, and freezes the public surface: it will not change before 2.0. What
remains before 1.0 is a beta/RC soak.

## What is txn-db?

A multi-version concurrency control (MVCC) transaction engine: the layer that
turns a key-value store into a transactional database. Every write produces a new
version tagged with a commit timestamp, so readers get a stable snapshot without
ever blocking writers, and writers detect conflicts at commit time. The version
store is a trait, so the engine composes on top of any backend that can keep
timestamped versions.

## What's new in 0.7.0

### Hardening

A new suite, `tests/adversarial.rs`, exercises the engine under conditions chosen
to break it rather than the happy path:

- **Long reader vs aggressive collection.** A snapshot is held while four writers
  overwrite every key and a fifth thread calls `collect_garbage` in a tight loop.
  The snapshot keeps reading exactly the values it pinned, and collection reclaims
  only the history below it.
- **Abort storm.** Twelve threads run 400 read-modify-write increments each
  against one shared key. The engine loses no update — the final value is exactly
  4,800 — and finishes: an abort storm must not deadlock or livelock.
- **Very large transaction.** A single transaction writes 20,000 keys spanning
  every shard, commits atomically, and reads back intact; a second large
  transaction overwrites half of them.
- **Edge key/value sizes.** Empty keys, empty values, a 4 KiB key, and a 1 MiB
  value all round-trip.
- **Mixed workload.** Eight threads each own a key range and run an arbitrary
  sequence of puts, deletes, and snapshot reads while a collector runs; each
  thread's keys end in exactly the state it last wrote.

Plus extreme-timestamp store tests (ordering, visibility, conflict detection, and
collection at the top of the `u64` range) and a `loom` model check that
collection running concurrently with a reader never disturbs what the reader
sees.

### A documented concurrency subtlety

Hardening surfaced — and the tests now document — that under concurrent
out-of-order commits the read watermark can briefly lag a thread's *own* most
recent commit. A transaction that writes only its own keys can therefore still
meet a retryable `Conflict`. This is correct snapshot-isolation behavior: a
spurious abort, never a lost update, resolved by the normal retry loop. It is
called out so it is not mistaken for a bug.

### Cross-platform re-verification

The full suite — including the crash-recovery tests that drive the `wal-db`
durable path — and the `loom` checks were re-run on Linux (WSL2 Ubuntu) as well
as Windows.

### API freeze

The public surface is frozen as of this release and recorded in the roadmap. It
will not change before 2.0:

- `Db` — `new`, `open`, `with_store`, `begin`, `begin_serializable`, `snapshot`,
  `last_committed`, `collect_garbage`, `Clone`, `Default`.
- `Transaction` — `get`, `put`, `delete`, `commit`, `rollback`, `read_timestamp`.
- `Snapshot` — `get`, `read_timestamp`.
- `Timestamp`, `TxnError` (`Conflict` / `Store` / `Durability`, `conflict`,
  `store`, `is_retryable`), `Result`, `VersionStore` (`get`, `try_commit`,
  `collect_garbage`), `MemoryStore`, `WriteEntry`, `prelude`.

## Breaking changes

**None.** v0.7.0 adds tests and freezes the existing surface.

## Verification

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

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test                       # default features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 clippy --all-targets --all-features -- -D warnings
cargo +1.85 test --all-features
RUSTFLAGS="--cfg loom" cargo test --test loom_txn --release
cargo deny check
cargo audit
```

All green. Counts at this tag (`--all-features`): 45 unit + 28 integration
(5 backing-store + 5 adversarial + 6 durability + 2 garbage-collection +
4 serializable property + 6 snapshot-isolation) + 33 doctests, plus 3 `loom`
model checks.

## What's next

- **0.8.0 → 0.9.x — Alpha / Beta → RC.** Integrate against the first real
  consumers and fix what they surface (MINOR-compatible additions only; no
  breaking signatures), then a beta bug-fix and broader-testing soak, then
  release-candidate doc polish and critical fixes.
- **1.0.0 — Stable.** Published with the API and any on-disk format frozen.

## Installation

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

# Opt into serializable isolation and/or a durable commit log:
txn-db = { version = "0.7", features = ["serializable", "durability"] }
```

MSRV: Rust 1.85 (the 2024 edition).

## Documentation

- [README](https://github.com/jamesgober/txn-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/txn-db/blob/main/docs/API.md)
- [Performance](https://github.com/jamesgober/txn-db/blob/main/docs/PERFORMANCE.md)
- [CHANGELOG](https://github.com/jamesgober/txn-db/blob/main/CHANGELOG.md)

---

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