Skip to content

fix(graph-db): release small staging generations in one commit - #4884

Merged
ScriptedAlchemy merged 3 commits into
masterfrom
t3/graph-db-release-sweep-timeout
Nov 13, 2026
Merged

ScriptedAlchemy merged 3 commits into
masterfrom
t3/graph-db-release-sweep-timeout

Conversation

@ScriptedAlchemy

Copy link
Copy Markdown
Owner

Summary

Staging-row release planned relations and entities as separate pages, so every release paid at least two fsync-backed commits, even for three rows. This PR replaces the two per-kind page helpers with one bounded planner (projection_deletion_page_checked):

  • One page admits relations first, then entities, under a single shared mutation-count and live-byte budget.
  • Entities join a page only once the relation scan admitted every remaining relation. A page filled by relations commits relations only, so an entity is never released by a page that leaves one of its relations behind.
  • Canonical batch order already puts DeleteRelation before DeleteEntity, so relations are still applied first inside the one transaction.
  • The page loop keeps the cancellation check between committed pages and the idempotent retry of a partially released generation. Memory stays bounded by one page; it never gathers two full pages.
  • GenerationRetirementPageKind and the two per-kind helpers are deleted; the existing single-pass scan is reused with a shared budget.

Unchanged: grafeo's commit-record fsync, our follow-up sync_wal fsync (the only fsync covering grafeo's EpochAdvance record, and the only place a WAL failure becomes DurabilityUncertain, since grafeo logs WAL write errors and continues), and the typed WAL failure handling.

Why

CI run 43308573947 on #4871 failed verified_generation_contract::staging_footprint::release_sweep_retries_idle_sealed_reader_hibernation at staging_footprint.rs:927 (Err(Timeout): the release didn't finish within 100ms while a sealed reader was parked).

Per-phase timing on macOS showed no lock blocking: every snapshot-gate and database-guard wait was 41ns–6µs. Nearly all the time was in row deletion's two durable commits. Each paid a grafeo commit with its fsync (~5–8ms) plus our sync_wal fsync (~4–9ms).

Measured (macOS, this test alone, 5 runs each, staging engine already open)

Sweep time (ms) Median
Before (master e845a0653c) 30.0, 36.4, 37.5, 38.3, 91.6 37.5
After 13.3, 13.8, 14.0, 14.7, 24.5 14.0

The Linux CI causal link is not proven. The failure didn't reproduce locally (8/8 passes on master), and no CI timings exist. These are Mac measurements of avoidable serialized fsync work on the path the test times, not a reproduction of the CI timeout. The 100ms assertion is unchanged.

Tests

New unit tests in generation_runtime::tests:

  • small_mixed_generation_releases_its_rows_in_one_durable_commit: 2 entities and 1 relation release with the projection's real commit sequence advancing by exactly 1, and a physical reopen observes the same commit with no rows. Fails on master (sequence 5, expected 4).
  • release_page_fills_its_shared_budget_with_entities_after_relations: with 1 relation and 4,106 entities, the first page removes the relation plus exactly 4,095 entities.
  • release_page_admits_entities_only_after_every_relation: with 4,097 relations, the first page leaves every entity in place. After a physical reopen, the next page releases the last relation and the entities together.

Verification (Bazel; every name-filtered run went through scripts/require-exact-test.sh and reported a nonzero count):

  • //crates/tracedecay-graph-db:unit_test generation_runtime::tests: 27 passed (includes the existing partial-release replay, read-once, cancellation and reopen tests)
  • //crates/tracedecay-graph-db:unit_test state::tests: 6 passed
  • //crates/tracedecay-graph-db:graph_db_suite:
    • exact release_sweep_retries_idle_sealed_reader_hibernation: 1 passed
    • verified_generation_contract::staging_footprint: 15 passed
    • replay: 11 passed
    • retire: 15 passed
  • rustfmt_check_2024 and bazel build --config=clippy //crates/tracedecay-graph-db/... (-Dwarnings): pass

🤖 Generated with Claude Code

Staging-row release planned relations and entities as separate pages,
so even a three-row generation paid two fsync-backed commits. One
bounded page now admits relations first and then entities under a
single shared mutation-count and live-byte budget. Entities join a page
only after every remaining relation is admitted, which keeps the
relations-before-entities order, the per-page cancellation boundary,
and the idempotent retry of a partially released generation.

Both fsync-backed guarantees and the typed WAL failure handling are
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: aa9af66

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@ScriptedAlchemy
ScriptedAlchemy merged commit 7043cbf into master Nov 13, 2026
16 checks passed
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