Skip to content

docs(storage): correct sidecar WAL removal timing - #364

Open
teipsum wants to merge 1 commit into
GrafeoDB:mainfrom
teipsum:u3b-storage-docstring-fix
Open

docs(storage): correct sidecar WAL removal timing#364
teipsum wants to merge 1 commit into
GrafeoDB:mainfrom
teipsum:u3b-storage-docstring-fix

Conversation

@teipsum

@teipsum teipsum commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Problem

The single-file storage docs claimed the sidecar WAL directory is "removed after each checkpoint". It is not: periodic checkpoints fold in-flight mutations into the .grafeo file but retain the sidecar; remove_sidecar_wal is invoked only on a clean close(). Retaining the sidecar across checkpoints is exactly what lets an unexpected restart recover in-flight mutations — only an orderly close discards it.

Fix

Correct three docstrings to match actual behaviour: the file/mod.rs module doc, the GrafeoFileManager lifecycle steps, and the remove_sidecar_wal doc comment (all under crates/grafeo-storage/src/file/). Docs-only; no functional change.

Note: flush.rs already documents the periodic-checkpoint WAL correctly as "Kept" on current main, so it is deliberately left untouched — only the remaining stale docstrings are corrected.

Tests

cargo fmt --all -- --check                                 -> clean
cargo test -p grafeo-storage --all-features file::         -> 54 passed; 0 failed
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" \
  cargo doc -p grafeo-storage --no-deps --all-features     -> no broken links

Single commit, based on main @ 4ebae02.


Summary by cubic

Fix storage docs to reflect the correct sidecar WAL lifecycle: periodic checkpoints keep the sidecar; only a clean close() calls remove_sidecar_wal. Updates the GrafeoFileManager lifecycle comments and the module docs in crates/grafeo-storage/src/file/; no behavior change.

Written for commit 18e59df. Summary will update on new commits.

Review in cubic

The single-file format docs claimed the sidecar WAL directory is
"removed after each checkpoint". It is not: periodic checkpoints fold
in-flight mutations into the .grafeo file but retain the sidecar, and
remove_sidecar_wal is invoked only on a clean close() (see the engine
close path's close:before_remove_sidecar_wal crash point). Retaining
the sidecar across checkpoints is what lets an unexpected restart
recover in-flight mutations; only an orderly close discards it.

Correct the module docs (file/mod.rs), the GrafeoFileManager lifecycle
steps, and the remove_sidecar_wal docstring to match actual behaviour.
Docs-only; no functional change.
@teipsum
teipsum requested a review from StevenBtw as a code owner June 11, 2026 00:35

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 2 files

Re-trigger cubic

@codecov

codecov Bot commented Jun 11, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@codspeed-hq

codspeed-hq Bot commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Merging this PR will not alter performance

✅ 70 untouched benchmarks


Comparing teipsum:u3b-storage-docstring-fix (18e59df) with main (4ebae02)

Open in CodSpeed

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