Repository navigation
Description
Summary
Reopening a file database whose WAL holds only entries that are already checkpointed rewinds the transaction counter. The transactions after that reuse tx_count values already in the file. :as-of answers become wrong, and the reused counts are written to the file at the next checkpoint.
Cause
On open, PersistentFactStorage sets the counter from the file header's last_checkpointed_tx_count. replay_wal (src/db.rs) then skips every WAL entry at or below that count, and calls FactStorage::restore_tx_counter(). That function sets the counter to the highest tx_count among the facts it just loaded. When every entry was skipped, no facts were loaded, so the counter is set to 0, below the header's value.
When it happens
The WAL is deleted after each checkpoint, so it outlives a checkpoint only when:
- the process crashes or loses power between a checkpoint's commit and the WAL delete;
- the WAL delete fails (WAL-006);
wal_checkpoint_thresholdisusize::MAX, which skips the close-time checkpoint while the storage layer still saves on drop.
Affected
Releases v0.5.0 through v2.0.2, file databases only.
Symptom
Repro on v2.0.2: transact [:alice :age 30] (tx 1), then [:alice :age 31] (tx 2), checkpoint, and put the pre-checkpoint WAL back, simulating a crash before the delete. Reopen, then (retract [[:alice :age 30]]) and (transact [[:alice :age 99]]):
| query | expected | actual |
|---|---|---|
:as-of 1 |
[30] |
[] |
:as-of 2 |
[30, 31] |
[31, 99] |
| current | [31, 99] |
[31, 99] |
The retraction reused tx 1 and the new assertion reused tx 2. Once checkpointed, the wrong history is permanent.
Workaround
If a .wal file sits next to the database after a crash, open the database and call checkpoint() before writing. Don't run with wal_checkpoint_threshold(usize::MAX) on data you keep.
Fix
The counter never moves backwards on replay: restore_tx_counter keeps the higher of the current counter and the highest loaded tx_count. Add a regression test for the sequence above.
Activity
Merge pull request #448 from project-minigraf/fix/447-tx-counter-rewind
Merge pull request #450 from project-minigraf/merge/main-into-v3-2026…
adityamukho commentedon Oct 6, 2026
Fixed in v2.0.3 (released 2026-10-06, PR #448). Upgrade to v2.0.3 or later; the file format is unchanged. Listed under "Fixed in v2.0.3" in #421.