wal-db 1.0.0

Write-ahead log primitive for Rust storage engines. Durable, recoverable, lock-free append path. The WAL substrate under lsm-db, txn-db, raft-io, and Hive DB.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# wal-db v0.7.0 — Hardening + API freeze

**Tested against malice, and frozen.** v0.7.0 turns the recovery and error paths
against deliberately hostile inputs and injected disk failures, on top of the
fuzz harness and loom model checks, and freezes the public API for the 1.x line.
No public API change — this is about confidence, not surface.

## What is wal-db?

A write-ahead log primitive for Rust storage engines — the durability substrate
under `lsm-db`, `txn-db`, `raft-io`, and Hive DB. Lock-free append, group commit,
platform-correct durability, segment rotation, fuzz-hardened recovery, optional
typed records.

## What's new in 0.7.0

### Adversarial recovery inputs

The fuzz harness already proves recovery never panics or over-allocates on
*arbitrary* bytes. `tests/hostile.rs` adds the specific hostile shapes as named
regression tests, each pinned to the guarantee it checks:

- a **garbage prefix** — a file that is not a log at all — recovers nothing and
  truncates to empty;
- an **implausible length** (a header claiming ~4 GiB) is rejected on the length
  check *before a single payload byte is read or allocated* — the bound that
  stops a corrupt or hostile log from forcing a wild allocation;
- **all-zeros** recovers nothing (a zero-length record with a zero checksum does
  not match an empty record's checksum);
- a **garbage tail** after valid records keeps the valid ones and trims the tail;
- a **corrupt middle record** truncates the log from there on open;
- truncation **mid-header** and **mid-payload** drops the partial record.

Recovery reads all-and-only the intact records and never trusts a length or a
checksum it has not verified.

### Injected I/O failures

Real disks fail. `tests/faults.rs` drives the exact error paths a full disk or a
failing flush would hit, through the `WalStore` seam:

- a **disk-full append** surfaces the error and leaves the records already written
  intact and readable;
- a **failed write fail-stops the log** — a later sync whose range covers the gap
  reports the truncation rather than a false durability;
- an **fsync failure** is always reported, never silently swallowed.

A WAL that lies about durability is worse than one that stops, so it stops.

### API freeze

The public surface is frozen for the 1.x line — no breaking changes before 2.0.
It is built to keep growing additively: `WalError` and `RecoveryPolicy` are
`#[non_exhaustive]`, `WalConfig` is a builder, and `WalStore`'s one non-required
method has a default. The frozen surface:

`Wal` (and its methods), `Lsn`, `Record`, `WalIter`, `WalConfig`,
`RecoveryPolicy`, `WalStore`, `FileStore`, `MemStore`, `SegmentedStore`,
`WalError`, `Result`, the `prelude`, and the `pack_io` re-export under the
`pack-io` feature.

## Breaking changes

**None.** This release adds tests and freezes the existing surface; it changes no
public API.

## Verification

Run on Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable 1.95.x and MSRV
1.85.0; macOS via the CI matrix. Cross-platform durability is re-verified by the
cross-process durability test on all three OSes, and the macOS partial-sync bug is
avoided structurally by `fcntl(F_FULLFSYNC)`.

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo +1.85 clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
RUSTFLAGS="--cfg loom" cargo test --test loom_wal
cargo +nightly fuzz run recover --target x86_64-unknown-linux-gnu -- -max_total_time=60
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```

All green on both platforms; 107 tests pass, the fuzzer ran millions of inputs
with no crash, and loom passed.

## What's next

- **0.8.x → 0.9.x — Alpha / Beta → RC.** Integrate against `lsm-db` and `raft-io`
  as first consumers and fix what they surface (minor-compatible additions only,
  no breaking signatures), then a stability soak toward 1.0.

## Installation

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

# Typed records:
wal-db = { version = "0.7", features = ["pack-io"] }
```

MSRV: Rust 1.85.

## Documentation

- [README](https://github.com/jamesgober/wal-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/wal-db/blob/main/docs/API.md)
- [On-Disk Format](https://github.com/jamesgober/wal-db/blob/main/docs/ON_DISK_FORMAT.md)
- [Benchmarks](https://github.com/jamesgober/wal-db/blob/main/docs/BENCHMARKS.md)
- [CHANGELOG](https://github.com/jamesgober/wal-db/blob/main/CHANGELOG.md)

---

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