sq/todos/SQ-005-wal-segment-reader.md

SQ-005: WAL Segment Reader

Status: [ ] TODO Blocked by: SQ-004 Priority: High

Description

Implement the WAL segment reader that reads messages from segment files, supporting seek-to-offset and forward scanning.

Files to Create/Modify

• crates/sq-storage/src/wal/reader.rs - WalReader with open, read_from, iterator

WalReader API

pub struct WalReader<F: FileSystem> {
    fs: Arc<F>,
}

impl<F: FileSystem> WalReader<F> {
    pub fn new(fs: Arc<F>) -> Self;
    pub async fn read_segment(&self, path: &Path) -> Result<Vec<Message>>;
    pub async fn read_from_offset(&self, path: &Path, offset: u64) -> Result<Vec<Message>>;
    pub async fn read_segment_header(&self, path: &Path) -> Result<SegmentHeader>;
}

Acceptance Criteria (using InMemoryFileSystem)

• Write N messages with writer, read all back with reader, verify equality
• Read from a specific offset in the middle of a segment
• Corrupted record mid-segment: reader returns error for that record, can report partial results
• Empty segment (header only): reader yields zero messages
• Invalid magic bytes: reader returns descriptive error
• Truncated record at end of segment (partial write): reader stops cleanly at last complete record