Struct WALRecovery 

pub struct WALRecovery { /* private fields */ }

WAL recovery engine

Reconstructs database state by replaying WAL records. Uses in-memory page cache during recovery; actual page operations are deferred until BTreeManager integration.

Recovery Process

1. Open WAL file and read header
2. Read records sequentially until EOF or unrecoverable error
3. For each valid record, update internal state
4. Return final header state and statistics

Note

This is a simplified recovery implementation that works without BTreeManager. Full integration with BTreeManager is deferred to Task 65-04.

Implementations

impl WALRecovery

pub fn new(wal_path: PathBuf) -> Self

Create a new WAL recovery engine

pub fn stats(&self) -> &WALRecoveryStats

Get recovery statistics

pub fn checkpoint_header(&self) -> Option<&PersistentHeaderV3>

Get last checkpoint header (if any)

pub fn last_lsn(&self) -> u64

Get last LSN processed

pub fn page_cache(&self) -> &HashMap<u64, Vec<u8>>

Get in-memory page cache

pub fn recover(&mut self) -> NativeResult<()>

Recover from WAL file

Reads WAL file and applies all records sequentially. Returns Ok(()) on successful recovery, even if some records were skipped.

pub fn get_header_state(&self) -> Option<&PersistentHeaderV3>

Get header state from last checkpoint (if available)

Returns the PersistentHeaderV3 that was captured in the most recent checkpoint record. This can be used to restore the database to a consistent state.

pub fn recover_kv(&mut self, kv_store: &mut KvStore) -> NativeResult<usize>

Recover KV state from WAL records

Replays only KV-related records (KvSet, KvDelete, KvTombstone) to rebuild an in-memory KvStore. This is called during V3Backend::open() to restore KV durability across close/reopen cycles.

V3 KV RECOVERY CONTRACT

Recovery Precedence (in order):

1. WAL replay (authoritative): If WAL exists, replay all KV records
   • This captures the latest state including mutations after last flush
2. Checkpoint fallback: If WAL missing, read checkpoint file
   • This captures the last flushed state (before WAL truncation)
3. Empty KV: If neither WAL nor checkpoint recoverable
   • Returns Ok(0) to indicate no KV records applied
   • Caller decides whether to continue with empty KV

Corruption Handling:

• Corrupt checkpoint files are auto-deleted (see cleanup_corrupt_checkpoint)
• Checkpoint errors do NOT propagate (return Ok(0) instead)
• WAL errors DO propagate (WAL is authoritative, corruption is serious)

Lifecycle Scenarios:

• After flush(): checkpoint=latest, WAL=empty → checkpoint recovery
• Before flush(): WAL=latest, checkpoint=stale → WAL recovery
• Corrupt checkpoint + valid WAL → WAL recovery (checkpoint never checked)
• Corrupt checkpoint + no WAL → empty KV (checkpoint deleted, logged)

Arguments

• kv_store - Mutable reference to the KvStore to rebuild

Returns

• Ok(kv_records_applied) - Number of KV records successfully applied
• Err(NativeBackendError) - If WAL file cannot be read (WAL errors propagate)

Trait Implementations

impl Debug for WALRecovery

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.