Repository navigation
fix(storage): refuse a WAL from a later checkpoint with STG-047 (#535) - #537
Merged
Merged
Conversation
Opening an older .graph next to a .wal created after a later checkpoint (a restored backup with the current WAL left in place) replayed the WAL onto the older file and succeeded, leaving a silent gap where the transactions between the two checkpoints were. Meta selection used the WAL's base generation only when one meta slot was valid. Open now fails with STG-047, read-write and read-only, when the WAL's base generation is newer than every meta page the file holds: both slots valid, one valid and the other never written, a new file, or a v7 file (which migrates to generation 1). Both files are left unmodified. A WAL with an older base still replays (#457). A damaged newer slot keeps STG-033. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h
This was referenced Oct 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #535 (data-integrity: stays open until v3.0.0 is released; listed in #421).
Problem
Restoring an older
app.graphnext to the currentapp.graph.walreplayed the WAL onto the older file and opened successfully. The transactions between the two checkpoints were silently missing, and the next checkpoint made the gap permanent.select_metachecked the WAL'sbase_generationonly when exactly one meta slot was valid.Change
STG-047"WAL is from a later checkpoint".check_wal_not_later(g, wal_base)refuses whenbase_generation > g, the newest generation the file holds:SlotState::Empty), e.g. a backup taken at generation 1. A damaged newer slot keepsSTG-033;gstill replays (crash between a checkpoint's commit and its WAL delete, WAL whose entries are all checkpointed survives checkpoint() until the next write #457).ERROR_REFERENCE.mdentry,DURABILITY.md(open step, restore step, error table; known limitation removed), CHANGELOG, test counts. The docs site reads both files from this repo per tag, so no minigraf-docs PR is needed.No v2.x backport
v2.x WALs (version 1) record no base generation, so v2.x cannot detect this. The durability guide already tells operators to remove any
.walbefore restoring.Release note
New
ErrorCodevariant → UniFFI bindings (Python/Java/Android/Swift) need regenerating at the v3.0.0 cascade.Tests
tests/integrity_test.rs::wal_from_a_later_checkpoint_is_refused: the issue's repro through the public API, read-write and read-only, files byte-identical afterwards; removing the WAL opens the backup.persistent_facts.rs: both-valid (base 4 vs gens 2/3, bases 1–3 still open), single-generation file, empty file (nothing initialised), v7 file (not migrated).cargo test: 1422 passed, 10 ignored.🤖 Generated with Claude Code
https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h