Skip to content

Report the log id a write landed at - #72

Merged
matrixarkai merged 1 commit into
mainfrom
oss/wal-append-reports-log-id
Aug 19, 2026
Merged

Report the log id a write landed at#72
matrixarkai merged 1 commit into
mainfrom
oss/wal-append-reports-log-id

Conversation

@bjmeetsfo

Copy link
Copy Markdown
Collaborator

A block carried in the WAL is addressed by the byte offset of its record, so a write has to learn that offset. The append already computed it and threw it away.

This is the last prerequisite for block-in-WAL: with it, a write knows where its own record landed and can address a block by it.

What it adds

append_with_sync_reporting returns the record and its log id — the record's position in the log's whole history, which stays valid across a reclaim. append_with_sync becomes a thin wrapper that drops the id, so every existing caller is unchanged.

The cached base, and why

Turning a physical offset into a log id needs the reclaim base. Reading it from disk on every append would put a file read on the write path, so it is cached per shard alongside the other per-shard append state: filled on first use, refreshed by reclaim — the only thing that moves it.

That cache is the part worth reviewing. A stale base would report ids wrong by exactly the reclaimed prefix, and those ids would still resolve — to the wrong record. That is the silent failure this whole scheme exists to prevent, so log_ids_reported_after_a_reclaim_account_for_the_base appends after a reclaim and reads the record back by its reported id.

Testing

24 WAL tests pass. New coverage:

  • an append reports the log id its record landed at, and each id reads back as that record
  • a reported log id still names its record after a reclaim moved it; ids that fail to resolve are only ever ones below the base
  • ids reported after a reclaim account for the base

Full-suite attribution

848 passed / 10 failed. One name fails here that is not in my last baseline — raft::tests::part4::raft_replication_deadline_is_configurable_and_bounds_propose — which was already a known flake on pristine main earlier in this series. Worth noting the baseline is older than current main (which gained ~90 tests from #62#67), so that diff is indicative rather than conclusive; the test is being re-checked in isolation.

Where this leaves block-in-WAL

Merged so far: record types and framing, CRC32C, storage descriptors, the block-retention floor, offset-stable log ids, streaming reclaim. With this, the remaining work is two pieces:

  1. carry the block bytes in the WAL record and set the address to the log id;
  2. resolve a WAL-resident address on read.

The obstacle for (1) is ordering: execute_on_shard mints addresses before the WAL append happens, across 12 call sites. The bounded route is async_storage mode, which already writes no block at all — the value's only durable copy is its WAL record, held at a synthetic counter address. Replacing that counter with the log id makes it addressable, and fixes the documented hole where an acked write reads back as missing if it is evicted before a dump.

A block carried in the WAL is addressed by the byte offset of its record, so a
write has to learn that offset. The append already computed it and discarded it.

append_with_sync_reporting returns it as a log id -- the record's position in the
log's whole history, which stays valid across a reclaim. append_with_sync is now
a thin wrapper that drops it, so every existing caller is unchanged.

Turning the physical offset into a log id needs the reclaim base, and reading
that from disk per append would put a file read on the write path. It is cached
per shard alongside the other per-shard append state: filled on first use, and
refreshed by reclaim, which is the only thing that moves it. A stale cache would
report ids wrong by exactly the reclaimed prefix -- and they would still resolve,
to the wrong record -- so a test appends after a reclaim and reads the record
back by its reported id.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@bjmeetsfo
bjmeetsfo requested a review from superhaiou as a code owner August 19, 2026 23:13
@matrixarkai
matrixarkai merged commit 4b0a8f6 into main Aug 19, 2026
4 of 5 checks passed
@matrixarkai
matrixarkai deleted the oss/wal-append-reports-log-id branch August 19, 2026 23: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.

3 participants