Skip to content

fix(storage): refuse a WAL from a later checkpoint with STG-047 (#535) - #537

Merged
adityamukho merged 2 commits into
v3from
fix/535-wal-base-generation
Oct 11, 2026
Merged

adityamukho merged 2 commits into
v3from
fix/535-wal-base-generation

Conversation

@adityamukho

Copy link
Copy Markdown
Collaborator

Refs #535 (data-integrity: stays open until v3.0.0 is released; listed in #421).

Problem

Restoring an older app.graph next to the current app.graph.wal replayed 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_meta checked the WAL's base_generation only when exactly one meta slot was valid.

Change

  • New STG-047 "WAL is from a later checkpoint". check_wal_not_later(g, wal_base) refuses when base_generation > g, the newest generation the file holds:
    • both meta slots valid (the issue's case);
    • one slot valid and the other never written (SlotState::Empty), e.g. a backup taken at generation 1. A damaged newer slot keeps STG-033;
    • a new/empty or torn-initial file (generation 1), a v7 file, and the migration backup-meta path (both open at generation 1; a v2.x v1 WAL reads as base 1, so it is unaffected).
  • Applies to read-write and read-only opens; neither file is modified. A WAL with a base at or below g still replays (crash between a checkpoint's commit and its WAL delete, WAL whose entries are all checkpointed survives checkpoint() until the next write #457).
  • Docs: ERROR_REFERENCE.md entry, 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 .wal before restoring.

Release note

New ErrorCode variant → 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.
  • Unit tests in 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

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

codecov Bot commented Oct 11, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@adityamukho
adityamukho merged commit 200baca into v3 Oct 11, 2026
24 checks passed
@adityamukho
adityamukho deleted the fix/535-wal-base-generation branch October 11, 2026 05:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant