Skip to main content

commonware_runtime/utils/buffer/paged/
writer.rs

1//! Single-owner, append-only access to a [Blob].
2//!
3//! A [Writer] exclusively owns its blob and cannot be cloned. Appended bytes can be read back
4//! immediately but are not durable until a sync completes ([Writer::sync], or the handles
5//! returned by [Writer::start_sync] and [Writer::seal]).
6//!
7//! # Snapshot
8//!
9//! [Writer::snapshot] returns the writer with a logical read view.
10//!
11//! # Seal
12//!
13//! [Writer::seal] ends writing, returning an immutable [super::Sealed] view plus a completion
14//! handle for the sync it starts.
15//!
16//! # Paging
17//!
18//! Callers append and read logical bytes; the blob stores physical pages in the format described
19//! in [`super`]. Appends accumulate in a write buffer and reach the blob in pages. Buffered bytes
20//! are readable immediately but durable only after `sync`. Full pages read from the blob are
21//! cached in a shared page cache, so reads are served from the write buffer, the page cache, or
22//! the blob itself. Large appends bypass the write buffer and write whole pages directly to the
23//! blob.
24//!
25//! # Checksums
26//!
27//! Each physical page ends in a two-slot CRC record. The slots let a partial page be rewritten
28//! without clobbering its last durable contents, so an interrupted write loses at most unsynced
29//! bytes. [Writer::new] backs up over any trailing bytes not covered by a valid checksum,
30//! treating them as an incomplete write. On a partial last page, it also zeroes a checksum slot
31//! that such a write left behind, so a later interrupted write cannot bring those bytes back.
32//!
33//! # Recovery
34//!
35//! [Recovery::open] trims an invalid tail and [Recovery::truncate] makes the selected prefix
36//! durable before returning. Conversion into an append-only [Writer] gives up permission to
37//! shorten the blob.
38//!
39//! # Raw [Blob] handles
40//!
41//! The [Writer] owns the page layout, page cache entries, and durability bookkeeping of its
42//! [Blob]. Raw handles shared before the writer existed see physical bytes, including CRC
43//! records, and do not observe buffered bytes until they are flushed. They must not mutate the
44//! blob while a [Writer] exists: such writes bypass the write buffer and page cache and can
45//! invalidate checksum recovery.
46
47use super::{
48    Sealed,
49    read::{PageReader, Replay},
50    tip::Buffer,
51    view::{Tail, View},
52};
53use crate::{
54    Blob, Error, Handle, IoBuf, IoBufMut, IoBufs, ReadOptions, WriteOptions,
55    buffer::{
56        SyncState,
57        paged::{ActiveChecksum, CHECKSUM_SIZE, CacheRef, Checksum, Slot},
58    },
59};
60use bytes::BufMut;
61use commonware_codec::{EncodeSize, Write};
62use commonware_cryptography::Crc32;
63use commonware_utils::Widen;
64use std::{
65    marker::PhantomData,
66    num::{NonZeroU16, NonZeroUsize},
67    sync::Arc,
68};
69use tracing::warn;
70
71/// Adjusts a requested write-buffer `capacity` upward to the value the buffer actually uses,
72/// applying two upward adjustments:
73///
74/// - Rounds up to a whole multiple of `page_size`, so the buffer always holds an exact number of
75///   pages. Callers can then drain and bulk-cache full pages without re-rounding the capacity.
76/// - Raises the result to a floor of two pages, so the buffer can hold at least one full page of
77///   new data even while caching a nearly-full page of already written data.
78fn adjusted_capacity(capacity: usize, page_size: u64) -> usize {
79    let page_size = page_size as usize;
80    let rounded = capacity.next_multiple_of(page_size);
81    let floor = page_size * 2;
82    if rounded < floor {
83        warn!(
84            floor,
85            "requested buffer capacity is too low, increasing it to floor"
86        );
87    }
88    rounded.max(floor)
89}
90
91/// Returns whether appending `append_len` bytes should bypass the write buffer and write whole
92/// pages directly: the append would overflow capacity, and at least one whole page remains to
93/// write after filling the current page up to a boundary.
94///
95/// Larger appends bypass the buffer, so a buffered append exceeds `capacity` by less than one
96/// page (given `capacity` is a whole number of pages; see [adjusted_capacity]). The write
97/// buffer's peak size therefore stays under `capacity + page_size`.
98const fn too_big_for_buffer(
99    buffer_len: usize,
100    buffer_capacity: usize,
101    append_len: usize,
102    page_size: usize,
103) -> bool {
104    let fill = buffer_len.next_multiple_of(page_size) - buffer_len;
105    let overflows_capacity = buffer_len + append_len > buffer_capacity;
106    let has_full_page_after_fill = append_len >= fill + page_size;
107
108    overflows_capacity && has_full_page_after_fill
109}
110
111/// An initialized, append-only paged blob.
112pub struct Append;
113
114/// A paged blob whose retained prefix is still being selected.
115pub struct Recovering;
116
117/// Exclusive initialization owner for selecting and durably publishing a retained prefix.
118///
119/// All previous writers and disk-backed readers must close before recovery opens.
120/// Only recovery may shorten the retained logical prefix.
121pub type Recovery<B> = Writer<B, Recovering>;
122
123/// Unique writer to a cache-wrapped [Blob].
124///
125/// Storage-mutating functions consume the writer and return it only on success: an error (or a
126/// dropped future) destroys the handle.
127pub struct Writer<B: Blob, Phase = Append> {
128    /// Distinguishes the recovery owner from the append-only writer.
129    phase: PhantomData<Phase>,
130
131    /// The underlying blob being wrapped.
132    blob: Arc<B>,
133
134    /// The page where the next appended byte will be written to.
135    current_page: u64,
136
137    /// The active checksum of the partial page in the blob, if any.
138    partial_page_state: Option<ActiveChecksum>,
139
140    /// The durable checksum of the page a partial-page flush would rewrite, if any.
141    ///
142    /// Rewrites preserve this slot byte-identically so a torn rewrite can never lose the page's
143    /// last durable contents. It trails [Self::partial_page_state] until a completed sync proves
144    /// the flushed state durable: an unsynced flush ([Self::replay], [Self::start_sync]) must not
145    /// advance it, or a later rewrite would evict the durable checksum and a crash cutting both
146    /// writes could leave no slot covering the synced prefix.
147    durable_page_state: Option<ActiveChecksum>,
148
149    /// Durability state for plain writes, resizes, and range-sync writes.
150    sync_state: SyncState,
151
152    /// Unique id assigned to this blob by the page cache.
153    id: u64,
154
155    /// A reference to the page cache that manages read caching for this blob.
156    cache_ref: CacheRef,
157
158    /// The write buffer containing any logical bytes following the last full page boundary in the
159    /// underlying blob.
160    buffer: Buffer,
161}
162
163impl<B: Blob> Recovery<B> {
164    /// Open `blob` for initialization repair.
165    ///
166    /// `blob` must already hold `original_blob_size` physical bytes. Reads are cached through
167    /// `cache_ref` and appends stage in a write buffer of capacity `capacity`. Trims any invalid
168    /// tail so the blob ends at a checksum-validated page. If that page is partial, also zeroes a
169    /// checksum slot that an interrupted write or shrink left behind. Earlier pages are not
170    /// scanned.
171    ///
172    /// Before appending, the tail-page contents must be durable: either pass a blob with no writes
173    /// since it was opened or call [Self::sync]. Until then, recovery may read or truncate the
174    /// blob. The discovered checksum slot seeds durable-slot tracking, so appending over a
175    /// still-volatile tail can overwrite the only durable slot.
176    pub async fn open(
177        blob: B,
178        original_blob_size: u64,
179        capacity: usize,
180        cache_ref: CacheRef,
181    ) -> Result<Self, Error> {
182        let blob = Arc::new(blob);
183        let page_size: u64 = cache_ref.page_size().widen();
184        let (partial_page_state, pages, invalid_data_found) =
185            Writer::<B>::read_last_valid_page(&blob, original_blob_size, page_size).await?;
186        if invalid_data_found {
187            // Invalid data was detected, trim it from the blob.
188            let new_blob_size = pages * (page_size + CHECKSUM_SIZE);
189            warn!(
190                original_blob_size,
191                new_blob_size, "truncating blob to remove invalid data"
192            );
193            blob.resize(new_blob_size).await?;
194            blob.sync().await?;
195        }
196        let capacity = adjusted_capacity(capacity, page_size);
197
198        // A valid tail may still include unsynced writes from the wrapped blob handle.
199        let mut sync_state = if invalid_data_found {
200            SyncState::Clean
201        } else {
202            SyncState::Dirty
203        };
204
205        // The next rewrite of a partial tail page lands its checksum in the other slot. If a torn
206        // write left part of a checksum there, a second torn write could complete it over bytes
207        // beyond the valid length, so that slot is zeroed before the page can be rewritten.
208        if let Some((_, active, false)) = &partial_page_state {
209            let slot_offset = pages * (page_size + CHECKSUM_SIZE) - CHECKSUM_SIZE
210                + Widen::<u64>::widen(active.slot.other().offset());
211            warn!(
212                page = pages - 1,
213                "zeroing checksum slot left by a torn write"
214            );
215            sync_state
216                .write_at(
217                    &blob,
218                    slot_offset,
219                    Checksum::slot_bytes(0, 0).to_vec(),
220                    WriteOptions::SYNC | WriteOptions::DONT_CACHE,
221                )
222                .await?;
223        }
224
225        // Retain a partial page in the tip buffer; complete pages remain backed by the blob.
226        let (current_page, partial_page_state, partial_data) = match partial_page_state {
227            Some((partial_page, crc_record, _)) => {
228                (pages - 1, Some(crc_record), Some(partial_page))
229            }
230            None => (pages, None, None),
231        };
232
233        let buffer = Buffer::from(
234            current_page * page_size,
235            partial_data.unwrap_or_default().as_ref(),
236            capacity,
237            page_size as usize,
238        );
239
240        Ok(Self {
241            phase: PhantomData,
242            blob,
243            current_page,
244            partial_page_state,
245            durable_page_state: partial_page_state,
246            sync_state,
247            id: cache_ref.next_id(),
248            cache_ref,
249            buffer,
250        })
251    }
252
253    /// Durably rewrite a committed page to a shorter partial length.
254    async fn sync_shrunk_page(
255        &mut self,
256        page: u64,
257        page_size: u64,
258        new_len: u16,
259        new_crc: u32,
260        old_checksum: &ActiveChecksum,
261    ) -> Result<ActiveChecksum, Error> {
262        // Recovery chooses the valid slot with the larger length. While shrinking, the new
263        // checksum must be made durable without becoming authoritative until the old longer slot
264        // can be disabled. The sequence below therefore lets recovery observe either the old page
265        // or the new shorter page, but not a footer where both slots were damaged by
266        // one torn write.
267        let physical_page_size = page_size
268            .checked_add(CHECKSUM_SIZE)
269            .ok_or(Error::OffsetOverflow)?;
270        let crc_start = page
271            .checked_mul(physical_page_size)
272            .and_then(|start| start.checked_add(page_size))
273            .ok_or(Error::OffsetOverflow)?;
274        let old_slot = old_checksum.slot;
275        let new_slot = old_slot.other();
276
277        // Stage the new slot with a 0 length and the shrunken page CRC. A crash here leaves the
278        // old slot as the only non-zero valid slot.
279        let new_slot_offset = crc_start
280            .checked_add(new_slot.offset() as u64)
281            .ok_or(Error::OffsetOverflow)?;
282        let staged_slot = Checksum::slot_bytes(0, new_crc);
283        self.sync_state
284            .write_at(
285                &self.blob,
286                new_slot_offset,
287                staged_slot.to_vec(),
288                WriteOptions::SYNC | WriteOptions::DONT_CACHE,
289            )
290            .await?;
291
292        // Publish the new shrunken length. If a crash happens before the old slot is invalidated,
293        // both slots may be valid, but recovery still chooses the old longer length.
294        let published_len = Checksum::slot_len_bytes(new_len);
295        self.sync_state
296            .write_at(
297                &self.blob,
298                new_slot_offset,
299                published_len.to_vec(),
300                WriteOptions::SYNC | WriteOptions::DONT_CACHE,
301            )
302            .await?;
303
304        // Clear the old slot entirely. The write stays within the old slot, so it cannot damage
305        // the already-durable shorter checksum, and zeroing the CRC alongside the length keeps a
306        // later torn rewrite of this page from reassembling the retired longer checksum over the
307        // pre-shrink bytes still on the page. Once this lands, the shrunken slot wins.
308        let old_slot_offset = crc_start
309            .checked_add(old_slot.offset() as u64)
310            .ok_or(Error::OffsetOverflow)?;
311        self.sync_state
312            .write_at(
313                &self.blob,
314                old_slot_offset,
315                Checksum::slot_bytes(0, 0).to_vec(),
316                WriteOptions::SYNC | WriteOptions::DONT_CACHE,
317            )
318            .await?;
319
320        Ok(ActiveChecksum::new(new_slot, new_len, new_crc))
321    }
322
323    /// Shrink the retained logical prefix to `target_size`. A page-boundary shrink leaves its
324    /// resize for the caller's sync.
325    async fn shrink(mut self, target_size: u64) -> Result<Self, Error> {
326        let page_size: u64 = self.cache_ref.page_size().widen();
327        let physical_page_size = page_size
328            .checked_add(CHECKSUM_SIZE)
329            .ok_or(Error::OffsetOverflow)?;
330
331        // Partial-page truncation requires a durable source page.
332        self = self.sync().await?;
333
334        // Calculate the physical size needed for the new size.
335        let full_pages = target_size / page_size;
336        let partial_bytes = target_size % page_size;
337        let physical_pages = full_pages
338            .checked_add(u64::from(partial_bytes > 0))
339            .ok_or(Error::OffsetOverflow)?;
340        let new_physical_size = physical_pages
341            .checked_mul(physical_page_size)
342            .ok_or(Error::OffsetOverflow)?;
343        let tail_offset = full_pages
344            .checked_mul(page_size)
345            .ok_or(Error::OffsetOverflow)?;
346        let current_physical_size = if self.partial_page_state.is_some() {
347            self.current_page
348                .checked_add(1)
349                .and_then(|pages| pages.checked_mul(physical_page_size))
350                .ok_or(Error::OffsetOverflow)?
351        } else {
352            self.current_page
353                .checked_mul(physical_page_size)
354                .ok_or(Error::OffsetOverflow)?
355        };
356
357        // A logical shrink can leave the physical page count unchanged. Only real physical
358        // resizes need to create a pending sync.
359        if new_physical_size != current_physical_size {
360            self.sync_state
361                .resize(&self.blob, new_physical_size)
362                .await?;
363        }
364        if partial_bytes > 0 {
365            self.shrink_to_partial(full_pages, partial_bytes, page_size, tail_offset)
366                .await?;
367            return Ok(self);
368        }
369
370        // Shrink the blob to a page boundary, which requires no CRC-slot rewrite.
371        self.partial_page_state = None;
372        self.durable_page_state = None;
373        self.current_page = full_pages;
374        self.buffer.replace(tail_offset, &[]);
375
376        Ok(self)
377    }
378
379    /// Perform a shrink to a partial page tip and make the shorter CRC slot authoritative.
380    async fn shrink_to_partial(
381        &mut self,
382        full_pages: u64,
383        partial_bytes: u64,
384        page_size: u64,
385        tail_offset: u64,
386    ) -> Result<(), Error> {
387        // The truncated page becomes the blob's tip. Its data is validated before the shorter
388        // checksum record is published.
389        self.current_page = full_pages;
390
391        // The retained prefix becomes the authoritative tip buffer, so this
392        // page need not remain in the OS page cache.
393        let (page_data, old_checksum) = super::get_page_with_checksum_from_blob(
394            &self.blob,
395            full_pages,
396            page_size,
397            ReadOptions::DONT_CACHE,
398        )
399        .await?;
400
401        // Ensure the validated data covers what we need.
402        if (page_data.len() as u64) < partial_bytes {
403            return Err(Error::InvalidChecksum);
404        }
405
406        let new_data = &page_data.as_ref()[..partial_bytes as usize];
407        self.buffer.replace(tail_offset, new_data);
408
409        let final_record = self
410            .sync_shrunk_page(
411                full_pages,
412                page_size,
413                partial_bytes as u16,
414                Crc32::checksum(new_data),
415                &old_checksum,
416            )
417            .await?;
418
419        // Both active and durable state now identify the published shorter record.
420        self.partial_page_state = Some(final_record);
421        self.durable_page_state = Some(final_record);
422
423        Ok(())
424    }
425
426    /// Durably retain at most `size` logical bytes.
427    ///
428    /// A size above the current length leaves the length unchanged. Pending writes are synchronized
429    /// even when the length does not change.
430    ///
431    /// Outstanding replays that cover the shortened or rewritten suffix are invalidated and must
432    /// not be consumed afterward.
433    pub async fn truncate(mut self, size: u64) -> Result<Self, Error> {
434        if size < self.size() {
435            self = self.shrink(size).await?;
436        }
437        self.sync().await
438    }
439}
440
441impl<B: Blob> From<Recovery<B>> for Writer<B> {
442    /// Convert recovery into a live writer without flushing or syncing.
443    ///
444    /// Truncation is already durable. Bytes appended since the last completed sync remain unsynced.
445    fn from(recovery: Recovery<B>) -> Self {
446        Self {
447            phase: PhantomData,
448            blob: recovery.blob,
449            current_page: recovery.current_page,
450            partial_page_state: recovery.partial_page_state,
451            durable_page_state: recovery.durable_page_state,
452            sync_state: recovery.sync_state,
453            id: recovery.id,
454            cache_ref: recovery.cache_ref,
455            buffer: recovery.buffer,
456        }
457    }
458}
459
460impl<B: Blob> Writer<B> {
461    /// Open a paged blob, repairing incomplete tail pages before publishing its writer.
462    /// The existing tail must be durable, and no previous writer or disk-backed reader may
463    /// access this storage incarnation during initialization.
464    pub async fn new(
465        blob: B,
466        size: u64,
467        capacity: usize,
468        cache_ref: CacheRef,
469    ) -> Result<Self, Error> {
470        Ok(Recovery::open(blob, size, capacity, cache_ref)
471            .await?
472            .into())
473    }
474
475    /// Scans backwards from the end of the blob, stopping when it finds a valid page.
476    ///
477    /// # Returns
478    ///
479    /// A tuple of `(partial_page, page_count, invalid_data_found)`:
480    ///
481    /// - `partial_page`: If the last valid page is partial (contains fewer than `page_size` logical
482    ///   bytes), returns `Some((data, checksum, inert))` containing the logical data, its active
483    ///   checksum, and whether the page's other checksum slot is zeroed or covers a prefix of that
484    ///   data. Returns `None` if the last valid page is full or if no valid pages exist.
485    ///
486    /// - `page_count`: The number of pages in the blob up to and including the last valid page
487    ///   found (whether or not it's partial). Note that it's possible earlier pages may be invalid
488    ///   since this function stops scanning when it finds one valid page.
489    ///
490    /// - `invalid_data_found`: `true` if there are any bytes in the blob that follow the last valid
491    ///   page. Typically the blob should be resized to eliminate them since their integrity cannot
492    ///   be guaranteed.
493    async fn read_last_valid_page(
494        blob: &B,
495        blob_size: u64,
496        page_size: u64,
497    ) -> Result<(Option<(IoBuf, ActiveChecksum, bool)>, u64, bool), Error> {
498        let physical_page_size = page_size + CHECKSUM_SIZE;
499        let partial_bytes = blob_size % physical_page_size;
500        let mut last_page_end = blob_size - partial_bytes;
501
502        // If the last physical page in the blob is truncated, it can't have a valid CRC record and
503        // must be invalid.
504        let mut invalid_data_found = partial_bytes != 0;
505
506        while last_page_end != 0 {
507            // Read the last page and parse its CRC record.
508            // A valid full page remains disk-authoritative and may be read again after startup.
509            let page_start = last_page_end - physical_page_size;
510            let buf = blob
511                .read_at(
512                    page_start,
513                    physical_page_size as usize,
514                    ReadOptions::default(),
515                )
516                .await?
517                .coalesce()
518                .freeze();
519
520            match Checksum::validate_page(buf.as_ref()) {
521                Some(checksum) => {
522                    // Found a valid page.
523                    let len = checksum.len as u64;
524                    if len != page_size {
525                        // The page is partial (logical data doesn't fill the page).
526                        let inert = Checksum::other_slot_is_inert(buf.as_ref(), &checksum);
527                        let logical_bytes = buf.slice(..len as usize);
528                        return Ok((
529                            Some((logical_bytes, checksum, inert)),
530                            last_page_end / physical_page_size,
531                            invalid_data_found,
532                        ));
533                    }
534                    // The page is full.
535                    return Ok((None, last_page_end / physical_page_size, invalid_data_found));
536                }
537                None => {
538                    // The page is invalid.
539                    last_page_end = page_start;
540                    invalid_data_found = true;
541                }
542            }
543        }
544
545        // No valid page exists in the blob.
546        Ok((None, 0, invalid_data_found))
547    }
548
549    /// Capture an immutable [`Sealed`] view of the logical bytes.
550    ///
551    /// Buffered full pages are written to the blob, and the partial page is copied into the view.
552    /// Neither is made durable. Call [`Self::sync`] if the returned handle's bytes must survive a
553    /// crash.
554    ///
555    /// Later appends preserve this view, including its frozen partial page.
556    pub async fn snapshot(mut self) -> Result<(Self, Sealed<B>), Error> {
557        // Write complete pages before capturing the view, which owns a copy of the partial tail.
558        self.flush_internal(false, false).await?;
559        let sealed = self.sealed_handle(self.id);
560        Ok((self, sealed))
561    }
562
563    /// Capture an immutable [`Sealed`] view of the logical bytes without writing to the blob.
564    ///
565    /// This is [`Self::snapshot`] without its flush. It returns the same view when every full
566    /// page is already in the blob, and `None` while the write buffer holds a full page that has
567    /// not been written.
568    pub fn try_snapshot(&self) -> Option<Sealed<B>> {
569        if self.has_flush_work(false) {
570            return None;
571        }
572        Some(self.sealed_handle(self.id))
573    }
574
575    /// Read and validate one page, returning its logical bytes and the range they cover.
576    async fn read_page(
577        blob: &B,
578        page: u64,
579        page_size: u64,
580        read_options: ReadOptions,
581    ) -> Result<(IoBuf, u64, u64), Error> {
582        let (logical, _) =
583            super::get_page_with_checksum_from_blob(blob, page, page_size, read_options).await?;
584        let start = page.checked_mul(page_size).ok_or(Error::OffsetOverflow)?;
585        let len: u64 = Widen::widen(logical.len());
586        let end = start.checked_add(len).ok_or(Error::OffsetOverflow)?;
587        Ok((logical, start, end))
588    }
589
590    /// Read a logical range directly from a raw paged blob, validating every page it spans.
591    ///
592    /// Returns [Error::BlobInsufficientLength] when valid page contents do not cover the whole
593    /// range, and [Error::OffsetOverflow] when its end or page offsets overflow.
594    pub async fn read_range(
595        blob: &B,
596        logical_page_size: NonZeroU16,
597        offset: u64,
598        len: usize,
599        read_options: ReadOptions,
600    ) -> Result<IoBufs, Error> {
601        // Resolve the requested range before allocating or reading any pages.
602        let len_u64: u64 = Widen::widen(len);
603        let end = offset.checked_add(len_u64).ok_or(Error::OffsetOverflow)?;
604        if len == 0 {
605            return Ok(IoBufs::default());
606        }
607
608        // Identify the inclusive logical page range spanning the requested bytes.
609        let logical_page_size: u64 = logical_page_size.widen();
610        let first_page = offset / logical_page_size;
611        let last_page = (end - 1) / logical_page_size;
612        let mut out = IoBufs::default();
613
614        // Validate every spanning page and append only its intersection with the requested range.
615        for page in first_page..=last_page {
616            let (logical, page_start, page_end) =
617                Self::read_page(blob, page, logical_page_size, read_options).await?;
618            let overlap_start = offset.max(page_start);
619            let overlap_end = end.min(page_end);
620            if overlap_start >= overlap_end {
621                return Err(Error::BlobInsufficientLength);
622            }
623            let start = (overlap_start - page_start) as usize;
624            let end = (overlap_end - page_start) as usize;
625            out.append(logical.slice(start..end));
626        }
627
628        // A short terminal page can leave the requested range only partially covered.
629        if out.len() != len {
630            return Err(Error::BlobInsufficientLength);
631        }
632        Ok(out)
633    }
634
635    /// Read the terminal logical range of a raw paged blob and return its logical size.
636    ///
637    /// The blob must contain only complete physical pages. The last page is validated first to
638    /// determine the logical end. If `len` crosses a page boundary, preceding pages are validated
639    /// with [Self::read_range].
640    pub async fn read_tail(
641        blob: &B,
642        physical_size: u64,
643        logical_page_size: NonZeroU16,
644        len: usize,
645        read_options: ReadOptions,
646    ) -> Result<(u64, IoBufs), Error> {
647        if physical_size == 0 {
648            return if len == 0 {
649                Ok((0, IoBufs::default()))
650            } else {
651                Err(Error::BlobInsufficientLength)
652            };
653        }
654
655        // A trailing partial page means the caller did not size the blob to complete physical
656        // pages, so there is no trusted terminal page to read the logical end from.
657        let page_size: u64 = logical_page_size.widen();
658        let physical_page_size = page_size
659            .checked_add(CHECKSUM_SIZE)
660            .ok_or(Error::OffsetOverflow)?;
661        if !physical_size.is_multiple_of(physical_page_size) {
662            return Err(Error::BlobInsufficientLength);
663        }
664
665        // The checksum length on the terminal page determines the blob's logical end.
666        let page = physical_size / physical_page_size - 1;
667        let (tail, page_start, logical_size) =
668            Self::read_page(blob, page, page_size, read_options).await?;
669        let len_u64: u64 = Widen::widen(len);
670        let offset = logical_size
671            .checked_sub(len_u64)
672            .ok_or(Error::BlobInsufficientLength)?;
673
674        // Read only the portion preceding the terminal page, then append its already-validated
675        // suffix. This keeps a terminal item wholly within the last page to one blob read.
676        let mut out = if offset < page_start {
677            let prefix_len =
678                usize::try_from(page_start - offset).map_err(|_| Error::OffsetOverflow)?;
679            Self::read_range(blob, logical_page_size, offset, prefix_len, read_options).await?
680        } else {
681            IoBufs::default()
682        };
683        let tail_start = usize::try_from(offset.max(page_start) - page_start)
684            .map_err(|_| Error::OffsetOverflow)?;
685        out.append(tail.slice(tail_start..));
686        assert_eq!(out.len(), len);
687        Ok((logical_size, out))
688    }
689
690    /// Construct an immutable read handle for the current blob state.
691    fn sealed_handle(&self, id: u64) -> Sealed<B> {
692        let page_size: u64 = self.cache_ref.page_size().widen();
693        let full_pages = self.current_page;
694        assert_eq!(
695            full_pages.checked_mul(page_size),
696            Some(self.buffer.offset),
697            "flushed page count is inconsistent with the buffer offset"
698        );
699
700        // Readers own their partial page so appends can reuse the writer's unique mutable tail.
701        let partial_page = if self.buffer.is_empty() {
702            None
703        } else {
704            Some(IoBuf::copy_from_slice(self.buffer.partial()))
705        };
706        Sealed::new(
707            self.blob.clone(),
708            self.buffer.size(),
709            partial_page,
710            self.cache_ref.clone(),
711            id,
712        )
713    }
714
715    /// Consume the write handle, flushing buffered bytes and beginning a sync of the blob.
716    ///
717    /// Returns an immutable [`Sealed`] read handle plus a completion handle for the started sync.
718    /// Reads through the [`Sealed`] handle observe flushed bytes immediately.
719    /// Durability isn't guaranteed until the sync handle completes.
720    pub async fn seal(mut self) -> Result<(Sealed<B>, Handle<()>), Error> {
721        // Complete earlier syncs before flushing the final bytes under this writer's ownership.
722        self.sync_state.wait_for_pending().await?;
723        self.flush_internal(true, false).await?;
724
725        // Transfer reads to an immutable view while the runtime completes its durability barrier.
726        let handle = self.sync_state.start_sync(&self.blob).await;
727        Ok((self.sealed_handle(self.id), handle))
728    }
729}
730
731impl<B: Blob, Phase> Writer<B, Phase> {
732    /// Append all bytes in `buf` to the tip of the blob, returning the logical offset at which
733    /// the first byte was written.
734    pub async fn append(mut self, buf: &[u8]) -> Result<(Self, u64), Error> {
735        let page_size: usize = self.cache_ref.page_size().widen();
736
737        // Bypass the write buffer and write whole pages directly when `buf` is large.
738        if too_big_for_buffer(
739            self.buffer.len(),
740            self.buffer.capacity,
741            buf.len(),
742            page_size,
743        ) {
744            return self.append_owned(IoBuf::copy_from_slice(buf)).await;
745        }
746
747        let offset = self.buffer.size();
748        if self.buffer.append(buf) {
749            self.flush_internal(false, false).await?;
750        }
751        Ok((self, offset))
752    }
753
754    /// Append `buf` to the write buffer if it fits.
755    ///
756    /// Returns its logical offset on success. Returns `None` without changing the writer when
757    /// there is insufficient buffer space. Performs no I/O and does not make the append durable.
758    /// Callers can fall back to [`Self::append_owned`] when it does not fit.
759    pub fn try_append(&mut self, buf: &[u8]) -> Option<u64> {
760        self.buffer.try_append(buf)
761    }
762
763    /// Encode a value directly into the write buffer if it fits.
764    ///
765    /// Returns its logical offset on success. Returns `None` without encoding or changing the
766    /// writer when there is insufficient buffer space. Performs no I/O and does not make the
767    /// append durable. Callers can fall back to [`Self::append_owned`] when it does not fit.
768    ///
769    /// # Panics
770    ///
771    /// Panics if the encoder writes a different number of bytes than [`EncodeSize::encode_size`].
772    pub fn try_append_value<T: EncodeSize + Write>(&mut self, value: &T) -> Option<u64> {
773        self.buffer.try_append_value(value)
774    }
775
776    /// Append owned bytes to the tip of the blob.
777    ///
778    /// Large appends fill the current tip to a page boundary, write complete pages directly to the
779    /// blob, and leave only a sub-page suffix in the write buffer. This avoids copying full-page
780    /// payloads while preserving the invariant that the buffer starts at `current_page`.
781    pub async fn append_owned(mut self, buf: IoBuf) -> Result<(Self, u64), Error> {
782        let page_size: usize = self.cache_ref.page_size().widen();
783        let offset = self.buffer.size();
784
785        // Buffer the append unless `buf` is too big for the buffer.
786        if !too_big_for_buffer(
787            self.buffer.len(),
788            self.buffer.capacity,
789            buf.len(),
790            page_size,
791        ) {
792            if self.buffer.append(buf.as_ref()) {
793                self.flush_internal(false, false).await?;
794            }
795            return Ok((self, offset));
796        }
797
798        // Bytes needed to fill current page to a page boundary (0 if already aligned).
799        let fill = self.buffer.len().next_multiple_of(page_size) - self.buffer.len();
800
801        // Top up the tip to a page boundary so its contents flush as full pages, leaving any
802        // partial-page CRC handling to the regular flush path.
803        if fill > 0 {
804            self.buffer.append(&buf.as_ref()[..fill]);
805        }
806        let boundary = self.buffer.size();
807        if !self.buffer.is_empty() {
808            self.flush_internal(false, false).await?;
809            assert!(
810                self.buffer.size() == boundary && self.buffer.is_empty(),
811                "flush left unexpected buffered bytes before a direct-path append"
812            );
813        }
814
815        // Prepare physical pages for the whole pages remaining in `buf` without copying logical
816        // payload bytes.
817        let bulk_len = (buf.len() - fill) / page_size * page_size;
818        let bulk = buf.slice(fill..fill + bulk_len);
819        let mut physical_pages = IoBufs::default();
820        self.append_full_pages(std::iter::once(&bulk), None, &mut physical_pages);
821
822        assert!(
823            self.partial_page_state.is_none(),
824            "an empty tip implies no partial page state"
825        );
826
827        // Direct blob writes must not overtake an earlier started sync barrier.
828        self.sync_state.wait_for_pending().await?;
829
830        // Cache the pages before `replace` publishes the new size, so reads of the bulk range are
831        // served from the cache while the blob write is still in flight. Insert in
832        // write-buffer-sized chunks. The capacity is a whole number of pages (see
833        // [adjusted_capacity]), so each chunk is page-aligned.
834        let chunk_len = self.buffer.capacity;
835        let mut cache_offset = boundary;
836        for chunk in bulk.as_ref().chunks(chunk_len) {
837            let remaining = self.cache_ref.cache(self.id, chunk, cache_offset);
838            assert_eq!(remaining, 0, "cached bulk pages must be page-aligned");
839            cache_offset += chunk.len() as u64;
840        }
841
842        // Update state before writing. Copy the suffix into at most one page so the tip never
843        // retains the input's larger backing.
844        self.current_page += (bulk_len / page_size) as u64;
845        self.buffer
846            .replace(boundary + bulk_len as u64, &buf.as_ref()[fill + bulk_len..]);
847
848        // Make sure the buffer offset and underlying blob agree on the state of the tip.
849        let page_size: u64 = self.cache_ref.page_size().widen();
850        assert_eq!(self.current_page * page_size, self.buffer.offset);
851
852        let physical_page_size = page_size + CHECKSUM_SIZE;
853        let write_at_offset = boundary / page_size * physical_page_size;
854        self.sync_state
855            .write_at(
856                &self.blob,
857                write_at_offset,
858                physical_pages,
859                WriteOptions::DONT_CACHE,
860            )
861            .await?;
862
863        Ok((self, offset))
864    }
865
866    /// Whether a partial page of `partial_len` bytes needs a write when `full_pages` full
867    /// pages precede it in the same flush and `flushed` is the last flushed partial state: an
868    /// empty tip never writes, a moved tip always writes, and an unmoved tip writes only when
869    /// its length changed.
870    fn partial_page_dirty(
871        full_pages: usize,
872        partial_len: usize,
873        flushed: Option<&ActiveChecksum>,
874    ) -> bool {
875        partial_len != 0
876            && (full_pages > 0 || flushed.is_none_or(|state| state.len as usize != partial_len))
877    }
878
879    /// Whether a flush would emit any physical page write.
880    fn has_flush_work(&self, write_partial_page: bool) -> bool {
881        let page_size: usize = self.cache_ref.page_size().widen();
882        let full_pages = self.buffer.len() / page_size;
883        if full_pages > 0 {
884            return true;
885        }
886        write_partial_page
887            && Self::partial_page_dirty(
888                full_pages,
889                self.buffer.len() % page_size,
890                self.partial_page_state.as_ref(),
891            )
892    }
893
894    /// Flush all full pages from the buffer to disk, resetting the buffer to contain only the bytes
895    /// in any final partial page.
896    ///
897    /// If `write_partial_page` is true, the partial page will be written to the blob as well along
898    /// with a CRC record.
899    ///
900    /// A flush emits one write covering whole physical pages. A previously written partial page
901    /// is rewritten in full, preserving its durable bytes and protected checksum slot.
902    ///
903    /// If `sync` is true, the emitted write is made durable immediately. When an earlier mutation
904    /// is pending, the write is followed by a blob sync instead of relying on per-write durability.
905    ///
906    /// Returns `true` if the flush made its writes durable, so no additional sync is needed.
907    async fn flush_internal(
908        &mut self,
909        write_partial_page: bool,
910        sync: bool,
911    ) -> Result<bool, Error> {
912        // If there's nothing to write, return early without observing any pending barrier (an
913        // empty start_sync must remain a cheap re-observation of the in-flight sync).
914        if !self.has_flush_work(write_partial_page) {
915            return Ok(false);
916        }
917
918        // A flush mutates the blob, so first resolve any outstanding start_sync barrier. Once
919        // no unsynced mutation remains, the last flushed partial state is durable and becomes
920        // the checksum the rewrite below must preserve.
921        self.sync_state.wait_for_pending().await?;
922        if self.sync_state.is_clean() {
923            self.durable_page_state = self.partial_page_state;
924        }
925
926        // Capture the full pages' original range before draining advances the tip. Their backing
927        // moves into the flush, and the partial page is detached from any larger allocation.
928        let page_size: usize = self.cache_ref.page_size().widen();
929        let pages_to_cache = self.buffer.len() / page_size;
930        let cache_offset = self.buffer.offset;
931        let full_pages = self.buffer.drain_full_pages();
932        let new_offset = self.buffer.offset;
933
934        // Rewrites preserve the durable checksum, not merely the last flushed one: an unsynced
935        // flush may have rewritten the partial page without making its checksum durable.
936        let (physical_pages, partial_page_state) = self.to_physical_pages(
937            &full_pages,
938            self.buffer.partial(),
939            write_partial_page,
940            self.partial_page_state.as_ref(),
941            self.durable_page_state.as_ref(),
942        );
943        assert!(
944            !physical_pages.is_empty(),
945            "flush work predicate must match physical page construction"
946        );
947
948        // Cache full pages before publishing the new blob state so reads don't observe stale
949        // persisted bytes during the handoff from tip to cache.
950        if pages_to_cache > 0 {
951            let cached = self.cache_ref.cache_pages(
952                self.id,
953                full_pages
954                    .iter()
955                    .flat_map(|chunk| chunk.as_ref().chunks_exact(page_size)),
956                cache_offset,
957            );
958            assert_eq!(cached, pages_to_cache * page_size);
959        }
960
961        let physical_page_size = page_size + CHECKSUM_SIZE as usize;
962        let write_at_offset = self.current_page * physical_page_size as u64;
963
964        // Update state before writing. No blob mutation follows a failed write: the failing
965        // method drops the writer.
966        self.current_page += pages_to_cache as u64;
967        self.partial_page_state = partial_page_state;
968
969        // A new tip page has no durable contents to preserve yet.
970        if pages_to_cache > 0 {
971            self.durable_page_state = None;
972        }
973
974        // Make sure the buffer offset and underlying blob agree on the state of the tip.
975        let page_size: u64 = self.cache_ref.page_size().widen();
976        assert_eq!(self.current_page * page_size, new_offset);
977
978        // Rewriting a physical page resubmits its durable bytes and protected checksum
979        // unchanged, so a torn write leaves the durable state recoverable.
980        if sync {
981            // Publish the flushed checksum as durable only after the write's barrier completes.
982            self.sync_state
983                .write_at(
984                    &self.blob,
985                    write_at_offset,
986                    physical_pages,
987                    WriteOptions::SYNC | WriteOptions::DONT_CACHE,
988                )
989                .await?;
990            self.durable_page_state = partial_page_state;
991        } else {
992            // An unsynced write retains the checksum protecting the last durable prefix.
993            self.sync_state
994                .write_at(
995                    &self.blob,
996                    write_at_offset,
997                    physical_pages,
998                    WriteOptions::DONT_CACHE,
999                )
1000                .await?;
1001        }
1002        Ok(sync)
1003    }
1004
1005    /// Returns the size of the blob.
1006    pub const fn size(&self) -> u64 {
1007        self.buffer.size()
1008    }
1009
1010    /// Whether [Self::sync] would write buffered bytes, sync the blob, or observe a started sync.
1011    pub fn needs_sync(&self) -> bool {
1012        !self.sync_state.is_clean() || self.has_flush_work(true)
1013    }
1014
1015    /// Returns a borrowed view over this blob.
1016    const fn view(&self) -> View<'_, B> {
1017        View {
1018            blob: &self.blob,
1019            cache_ref: &self.cache_ref,
1020            id: self.id,
1021            size: self.buffer.size(),
1022            tail_offset: self.buffer.offset,
1023            tail: Tail::Buffered(&self.buffer),
1024        }
1025    }
1026
1027    /// Read into `buf` if it can be done synchronously without I/O. Returns `true` only if all
1028    /// `buf.len()` bytes were satisfied from the page cache and/or the in-memory tail. When `false`
1029    /// is returned, the contents of `buf` are unspecified.
1030    pub fn try_read_sync_into(&self, buf: &mut [u8], offset: u64) -> bool {
1031        self.view().try_read_sync_into(buf, offset)
1032    }
1033
1034    /// Read exactly `len` immutable bytes starting at `offset`.
1035    pub async fn read_at(&self, offset: u64, len: usize) -> Result<IoBufs, Error> {
1036        self.view().read_at(offset, len).await
1037    }
1038
1039    /// Reads up to `len` bytes starting at `offset`, but only as many as are available.
1040    ///
1041    /// Returns the buffer (truncated to actual bytes read) and the number of bytes read. Returns
1042    /// an error if no bytes are available at the given offset.
1043    pub async fn read_up_to(
1044        &self,
1045        offset: u64,
1046        len: usize,
1047        bufs: impl Into<IoBufMut> + Send,
1048    ) -> Result<(IoBufMut, usize), Error> {
1049        self.view().read_up_to(offset, len, bufs).await
1050    }
1051
1052    /// Read multiple fixed-size items at sorted byte offsets into a contiguous caller buffer.
1053    ///
1054    /// `buf` must be exactly `offsets.len() * item_size` bytes. All offsets must be sorted,
1055    /// non-overlapping, and within bounds.
1056    ///
1057    /// Returns the number of items fully served without a blob read (from the in-memory tail and the
1058    /// page cache). The remaining items required at least one blob read.
1059    pub async fn read_many_into(
1060        &self,
1061        buf: &mut [u8],
1062        offsets: &[u64],
1063        item_size: NonZeroUsize,
1064    ) -> Result<usize, Error> {
1065        self.view().read_many_into(buf, offsets, item_size).await
1066    }
1067
1068    /// Like [`Self::read_many_into`], but each `(offset, len)` range has its own length. `buf`
1069    /// holds the ranges back to back.
1070    ///
1071    /// Returns how many ranges were served entirely from the in-memory tail and page cache before
1072    /// any blob read. Empty ranges count as served.
1073    ///
1074    /// # Panics
1075    ///
1076    /// Panics if a range starts before the previous range ends, or if `buf` is not the ranges'
1077    /// total length.
1078    pub async fn read_ranges_into(
1079        &self,
1080        buf: &mut [u8],
1081        ranges: &[(u64, usize)],
1082    ) -> Result<usize, Error> {
1083        self.view().read_ranges_into(buf, ranges).await
1084    }
1085
1086    /// Like [`Self::read_many_into`], but synchronous and cache-only. Returns the indices of
1087    /// items that require a blob read. Their slots in `buf` hold unspecified bytes.
1088    pub fn try_read_many_sync_into(
1089        &self,
1090        buf: &mut [u8],
1091        offsets: &[u64],
1092        item_size: NonZeroUsize,
1093    ) -> Vec<usize> {
1094        self.view().try_read_many_sync_into(buf, offsets, item_size)
1095    }
1096
1097    /// Like [`Self::try_read_many_sync_into`], but for variable-length `(offset, len)` ranges:
1098    /// `buf` holds one slot per range, back to back.
1099    pub fn try_read_ranges_sync_into(&self, buf: &mut [u8], ranges: &[(u64, usize)]) -> Vec<usize> {
1100        self.view().try_read_ranges_sync_into(buf, ranges)
1101    }
1102
1103    /// Reads bytes starting at `offset` into `buf`.
1104    pub async fn read_into(&self, buf: &mut [u8], offset: u64) -> Result<(), Error> {
1105        self.view().read_into(buf, offset).await
1106    }
1107
1108    /// Prepare physical-page writes from buffered logical bytes.
1109    ///
1110    /// Each physical page contains one logical page plus CRC record. If the last page is not yet
1111    /// full, it will be included only if `include_partial_page` is true.
1112    ///
1113    /// # Arguments
1114    ///
1115    /// * `full_pages` - Page-aligned chunks containing complete logical pages
1116    /// * `partial_page` - The trailing bytes that do not fill a page
1117    /// * `include_partial_page` - Whether to include a partial page if one exists
1118    /// * `flushed` - The active checksum of the last flushed partial page, if any. Used only to
1119    ///   detect a partial page with nothing new to write.
1120    /// * `durable` - The durable checksum of the page being rewritten, if any. When present, the
1121    ///   first page's CRC record preserves it in its original slot and places the new checksum
1122    ///   in the other slot.
1123    ///
1124    /// Returns the physical pages to write and, for any included partial page, its new active
1125    /// checksum.
1126    fn to_physical_pages(
1127        &self,
1128        full_pages: &IoBufs,
1129        partial_page: &[u8],
1130        include_partial_page: bool,
1131        flushed: Option<&ActiveChecksum>,
1132        durable: Option<&ActiveChecksum>,
1133    ) -> (IoBufs, Option<ActiveChecksum>) {
1134        let page_size: usize = self.cache_ref.page_size().widen();
1135        let physical_page_size = page_size + CHECKSUM_SIZE as usize;
1136        let pages_to_write = full_pages.len() / page_size;
1137        let mut write_buffer = IoBufs::default();
1138
1139        if pages_to_write > 0 {
1140            self.append_full_pages(full_pages.iter(), durable, &mut write_buffer);
1141        }
1142
1143        if !include_partial_page {
1144            return (write_buffer, None);
1145        }
1146
1147        if !Self::partial_page_dirty(pages_to_write, partial_page.len(), flushed) {
1148            return (write_buffer, None);
1149        }
1150        let partial_len = partial_page.len();
1151        let crc = Crc32::checksum(partial_page);
1152
1153        // For partial pages: if this is the first page and there's a durable CRC, preserve it.
1154        // Otherwise just use the new CRC in slot 0.
1155        let durable = if pages_to_write == 0 { durable } else { None };
1156        let (crc_record, active_checksum) =
1157            Self::build_crc_record(partial_len as u16, crc, durable);
1158
1159        // A persisted partial page still occupies one full physical page:
1160        // [partial logical bytes, zero padding, crc record].
1161        let mut padded = IoBufMut::with_capacity(physical_page_size);
1162        padded.put_slice(partial_page);
1163        let zero_count = page_size - partial_len;
1164        if zero_count > 0 {
1165            padded.put_bytes(0, zero_count);
1166        }
1167        padded.put_slice(&crc_record.to_bytes());
1168        write_buffer.append(padded.freeze());
1169
1170        (write_buffer, Some(active_checksum))
1171    }
1172
1173    /// Append page-aligned chunks in on-disk format, with one payload slice and CRC per page.
1174    /// The first page preserves `old_checksum` in its original slot when present.
1175    fn append_full_pages<'a>(
1176        &self,
1177        data: impl Iterator<Item = &'a IoBuf> + Clone,
1178        old_checksum: Option<&ActiveChecksum>,
1179        write_buffer: &mut IoBufs,
1180    ) {
1181        let page_size: usize = self.cache_ref.page_size().widen();
1182        let pages = data
1183            .clone()
1184            .map(|chunk| {
1185                assert!(chunk.len().is_multiple_of(page_size));
1186                chunk.len() / page_size
1187            })
1188            .sum::<usize>();
1189        assert!(pages > 0);
1190        let page_size_u16 =
1191            u16::try_from(page_size).expect("page size must fit in u16 for CRC record");
1192
1193        // Store the batch's CRC records in one allocation, in the same order as the payload pages.
1194        let mut crcs = IoBufMut::with_capacity(CHECKSUM_SIZE as usize * pages);
1195        for (page, logical_page) in data
1196            .clone()
1197            .flat_map(|chunk| chunk.as_ref().chunks_exact(page_size))
1198            .enumerate()
1199        {
1200            let crc = Crc32::checksum(logical_page);
1201            let old_checksum = if page == 0 { old_checksum } else { None };
1202            let (crc_record, _) = Self::build_crc_record(page_size_u16, crc, old_checksum);
1203            crcs.put_slice(&crc_record.to_bytes());
1204        }
1205        let crc_blob = crcs.freeze();
1206
1207        // Interleave payload pages and CRC records in physical write order. Slicing retains the
1208        // original payload chunks and the shared CRC allocation without copying their bytes.
1209        let mut crc_start = 0;
1210        for chunk in data {
1211            for start in (0..chunk.len()).step_by(page_size) {
1212                write_buffer.append(chunk.slice(start..start + page_size));
1213                write_buffer.append(crc_blob.slice(crc_start..crc_start + CHECKSUM_SIZE as usize));
1214                crc_start += CHECKSUM_SIZE as usize;
1215            }
1216        }
1217    }
1218
1219    /// Build a CRC record and identify its active checksum. An old checksum remains in its original
1220    /// slot while the new checksum is placed in the other slot.
1221    const fn build_crc_record(
1222        new_len: u16,
1223        new_crc: u32,
1224        old_checksum: Option<&ActiveChecksum>,
1225    ) -> (Checksum, ActiveChecksum) {
1226        let Some(old_checksum) = old_checksum else {
1227            return (
1228                Checksum::new(new_len, new_crc),
1229                ActiveChecksum::new(Slot::First, new_len, new_crc),
1230            );
1231        };
1232
1233        let new_slot = old_checksum.slot.other();
1234        let record = match old_checksum.slot {
1235            Slot::First => Checksum {
1236                len1: old_checksum.len,
1237                crc1: old_checksum.crc,
1238                len2: new_len,
1239                crc2: new_crc,
1240            },
1241            Slot::Second => Checksum {
1242                len1: new_len,
1243                crc1: new_crc,
1244                len2: old_checksum.len,
1245                crc2: old_checksum.crc,
1246            },
1247        };
1248        (record, ActiveChecksum::new(new_slot, new_len, new_crc))
1249    }
1250
1251    /// Flushes any buffered data, then returns the writer with a [Replay] for the underlying blob.
1252    ///
1253    /// The returned replay validates that every stored page holds a full page and retains a
1254    /// frozen copy of the current partial page. CRCs are not included in the output. Every
1255    /// underlying blob read performed by the returned replay uses `read_options`, including
1256    /// refills after seeking.
1257    ///
1258    /// Pages are read in batches as for [`Sealed::replay`], which describes what `buffer_size`
1259    /// bounds.
1260    ///
1261    /// This does not establish durability. Use [`sync`](Self::sync) if the replayed bytes must
1262    /// survive a crash.
1263    pub async fn replay(
1264        mut self,
1265        buffer_size: NonZeroUsize,
1266        read_options: ReadOptions,
1267    ) -> Result<(Self, Replay<B>), Error> {
1268        // Flush the live tip so every full page is on the blob, then freeze the partial tail so
1269        // later rewrites cannot shorten the replay's view.
1270        self.flush_internal(true, false).await?;
1271        let page_size = self.cache_ref.page_size();
1272        let logical_size = self.size();
1273        let physical_page_size = u64::from(page_size.get()) + CHECKSUM_SIZE;
1274        let pages = logical_size.div_ceil(u64::from(page_size.get()));
1275        let physical_size = pages
1276            .checked_mul(physical_page_size)
1277            .ok_or(Error::OffsetOverflow)?;
1278        let buffer_pages = (buffer_size.get() / physical_page_size as usize).max(1);
1279        let partial_page = (logical_size > self.buffer.offset)
1280            .then(|| IoBuf::copy_from_slice(self.buffer.partial()));
1281        let replay = Replay::new(PageReader::new(
1282            self.blob.clone(),
1283            physical_size,
1284            logical_size,
1285            partial_page,
1286            buffer_pages,
1287            page_size,
1288            read_options,
1289        ));
1290        Ok((self, replay))
1291    }
1292
1293    /// Flushes buffered data and makes all pending mutations durable.
1294    ///
1295    /// A newly flushed write can carry [`WriteOptions::SYNC`] when no earlier mutation is pending.
1296    /// Otherwise, [`Blob::sync`] provides the barrier for all pending mutations.
1297    pub async fn sync(mut self) -> Result<Self, Error> {
1298        // Flush any buffered data, including any partial page. A flush that writes to the blob
1299        // makes that write durable itself and returns true.
1300        if self.flush_internal(true, true).await? {
1301            return Ok(self);
1302        }
1303
1304        // The flush had nothing to write. Sync only if a durability barrier is still pending.
1305        // Everything flushed is durable once it completes.
1306        self.sync_state.sync(&self.blob).await?;
1307        self.durable_page_state = self.partial_page_state;
1308        Ok(self)
1309    }
1310
1311    /// Flushes buffered data and begins making all pending mutations durable, returning a
1312    /// completion handle.
1313    ///
1314    /// Awaiting the returned [`Handle`] waits for the same durability guarantee as [`Self::sync`]
1315    /// for the state flushed by this call. Later calls to [`Self::sync`] and writer methods that
1316    /// mutate the blob first wait for any outstanding start_sync handles. A failure of the started
1317    /// sync is reported by the handle and by the next such call. Flush errors are returned
1318    /// directly.
1319    pub async fn start_sync(mut self) -> Result<(Self, Handle<()>), Error> {
1320        // Finish writes before handing their durability barrier to the runtime.
1321        self.flush_internal(true, false).await?;
1322        let handle = self.sync_state.start_sync(&self.blob).await;
1323        Ok((self, handle))
1324    }
1325
1326    /// Length of the longest contiguous prefix of well-formed pages on the blob.
1327    ///
1328    /// [`Recovery::open`] sizes a blob by scanning backward to its last valid page, which cannot
1329    /// detect an earlier page that was lost or corrupted. This scans forward instead, stopping
1330    /// at the first invalid or short page.
1331    ///
1332    /// Expects all appended bytes to have reached the blob (as after recovery): a partial page
1333    /// still buffered in this writer is unreadable from the blob and fails the scan. `buffer_size`
1334    /// bounds each blob read, with a minimum of one physical page. Applies `read_options` to
1335    /// every blob read.
1336    ///
1337    /// `proven` is a logical byte offset already known valid (a durability watermark or a
1338    /// replay-validated prefix). Pages wholly below it are accepted without reading, and the
1339    /// scan starts at the page containing it. A proof past the blob's content clamps to the
1340    /// full pages that exist. A partial tail must be read to determine its valid length.
1341    pub async fn recoverable_prefix_len(
1342        &self,
1343        proven: u64,
1344        buffer_size: NonZeroUsize,
1345        read_options: ReadOptions,
1346    ) -> Result<u64, Error> {
1347        self.recoverable_prefix_len_at_most(proven, u64::MAX, buffer_size, read_options)
1348            .await
1349    }
1350
1351    /// Like [`Self::recoverable_prefix_len`], but returns at most `max_size` logical bytes.
1352    ///
1353    /// Reads only pages intersecting the prefix below `max_size`. A cap inside a page requires
1354    /// validating that entire page's checksum. Zero requires no reads. A cap above the stored end
1355    /// does not extend the prefix. `proven` has the same meaning as in the unbounded scan.
1356    pub async fn recoverable_prefix_len_at_most(
1357        &self,
1358        proven: u64,
1359        max_size: u64,
1360        buffer_size: NonZeroUsize,
1361        read_options: ReadOptions,
1362    ) -> Result<u64, Error> {
1363        let logical_page_size: u64 = self.cache_ref.page_size().widen();
1364        let total_pages = (self.current_page + u64::from(self.partial_page_state.is_some()))
1365            .min(max_size.div_ceil(logical_page_size));
1366        let physical_page_size = logical_page_size
1367            .checked_add(CHECKSUM_SIZE)
1368            .ok_or(Error::OffsetOverflow)?;
1369        let physical_page_size_usize =
1370            usize::try_from(physical_page_size).map_err(|_| Error::OffsetOverflow)?;
1371        let max_batch_pages: u64 =
1372            Widen::widen((buffer_size.get() / physical_page_size_usize).max(1));
1373
1374        // Pages below the proof are accepted without reading. Clamp the starting page to the
1375        // full pages present: the partial tail must be read to determine how many bytes it adds
1376        // to the valid prefix.
1377        let start_page = (proven / logical_page_size)
1378            .min(self.current_page)
1379            .min(total_pages);
1380        let mut valid_len = start_page
1381            .checked_mul(logical_page_size)
1382            .ok_or(Error::OffsetOverflow)?;
1383        let mut page = start_page;
1384        while page < total_pages {
1385            // Bound each read while deriving its physical range with checked arithmetic.
1386            let batch_pages = max_batch_pages.min(total_pages - page);
1387            let batch_end = page.checked_add(batch_pages).ok_or(Error::OffsetOverflow)?;
1388            let physical_offset = page
1389                .checked_mul(physical_page_size)
1390                .ok_or(Error::OffsetOverflow)?;
1391            let physical_len = batch_pages
1392                .checked_mul(physical_page_size)
1393                .ok_or(Error::OffsetOverflow)?;
1394            let physical_len = usize::try_from(physical_len).map_err(|_| Error::OffsetOverflow)?;
1395
1396            // Coalesce once so each physical page can be checksum-validated in place.
1397            let physical = self
1398                .blob
1399                .read_at(physical_offset, physical_len, read_options)
1400                .await?
1401                .coalesce();
1402
1403            // The first invalid page terminates the only recoverable contiguous prefix.
1404            for physical_page in physical.as_ref().chunks_exact(physical_page_size_usize) {
1405                let Some(checksum) = Checksum::validate_page(physical_page) else {
1406                    return Ok(valid_len.min(max_size));
1407                };
1408                let len = u64::from(checksum.len);
1409                valid_len = valid_len.checked_add(len).ok_or(Error::OffsetOverflow)?;
1410
1411                // A valid partial logical page ends the contiguous prefix wherever it appears.
1412                if len < logical_page_size {
1413                    return Ok(valid_len.min(max_size));
1414                }
1415            }
1416            page = batch_end;
1417        }
1418        Ok(valid_len.min(max_size))
1419    }
1420
1421    /// Wait for any started sync to complete without starting a new sync.
1422    pub async fn wait_for_sync(mut self) -> Result<Self, Error> {
1423        self.sync_state.wait_for_pending().await?;
1424        Ok(self)
1425    }
1426}
1427
1428#[cfg(test)]
1429#[commonware_macros::test_group("miri")]
1430mod tests {
1431    use super::*;
1432    use crate::{
1433        Buf, Handle, IoBufsMut, Runner as _, Spawner as _, Storage as _, Supervisor as _,
1434        buffer::{
1435            paged::{CHECKSUM_SLOT_LEN_SIZE, CHECKSUM_SLOT_SIZE},
1436            tests::SyncTrackingBlob,
1437        },
1438        deterministic,
1439        mocks::{
1440            DelayedSyncBlob, RecordingContext, WriteFaultContext, WriteFaults, next_pending_sync,
1441        },
1442    };
1443    use commonware_codec::{Copying, FixedSize, ReadExt};
1444    use commonware_macros::test_traced;
1445    use commonware_utils::{NZU16, NZUsize, channel::oneshot, sync::Mutex};
1446    use futures::FutureExt as _;
1447    use std::{
1448        cell::Cell,
1449        num::NonZeroU16,
1450        ops::Range,
1451        sync::{
1452            Arc,
1453            atomic::{AtomicUsize, Ordering},
1454        },
1455    };
1456
1457    impl<B: Blob, Phase> Writer<B, Phase> {
1458        /// Return the page-cache id used for reads.
1459        pub(in super::super) const fn cache_id(&self) -> u64 {
1460            self.id
1461        }
1462    }
1463
1464    const PAGE_SIZE: NonZeroU16 = NZU16!(103); // janky size to ensure we test page alignment
1465    const BUFFER_SIZE: usize = PAGE_SIZE.get() as usize * 2;
1466
1467    /// `try_append` buffers bytes within the flush threshold at the writer's size and leaves the
1468    /// writer unchanged otherwise.
1469    #[test_traced]
1470    fn test_try_append_capacity() {
1471        deterministic::Runner::default().start(|context| async move {
1472            let (blob, size) = context.open("try_append", b"blob").await.unwrap();
1473            let cache = CacheRef::new(NZU16!(16), NZUsize!(4));
1474            let mut writer = Writer::new(blob, size, 32, cache).await.unwrap();
1475
1476            // Bytes within the threshold are buffered at the current size.
1477            assert_eq!(writer.try_append(&[1; 20]), Some(0));
1478            assert_eq!(writer.try_append(&[2; 12]), Some(20));
1479            assert_eq!(writer.size(), 32);
1480
1481            // Bytes past the threshold are refused without changing the writer.
1482            assert_eq!(writer.try_append(&[3]), None);
1483            assert_eq!(writer.size(), 32);
1484
1485            // The refused bytes take the ordinary flushing path, and everything reads back.
1486            let (writer, offset) = writer.append(&[3]).await.unwrap();
1487            assert_eq!(offset, 32);
1488            let read = writer.read_at(0, 33).await.unwrap().coalesce();
1489            assert_eq!(&read.as_ref()[..20], &[1; 20]);
1490            assert_eq!(&read.as_ref()[20..32], &[2; 12]);
1491            assert_eq!(read.as_ref()[32], 3);
1492        });
1493    }
1494
1495    #[test_traced]
1496    fn test_append_value_capacity_snapshot_and_recovery() {
1497        deterministic::Runner::default().start(|context| async move {
1498            struct MustNotEncode<const SIZE: usize>;
1499            impl<const SIZE: usize> FixedSize for MustNotEncode<SIZE> {
1500                const SIZE: usize = SIZE;
1501            }
1502            impl<const SIZE: usize> Write for MustNotEncode<SIZE> {
1503                fn write(&self, _: &mut impl BufMut) {
1504                    panic!("insufficient capacity must not invoke the encoder");
1505                }
1506            }
1507
1508            let (blob, size) = context.open("append_value", b"blob").await.unwrap();
1509            let cache = CacheRef::new(NZU16!(16), NZUsize!(4));
1510            let mut writer = Writer::new(blob, size, 32, cache.clone()).await.unwrap();
1511            assert_eq!(writer.try_append_value(&0u64), Some(0));
1512            assert_eq!(writer.try_append_value(&MustNotEncode::<25>), None);
1513            let (mut writer, snapshot) = writer.snapshot().await.unwrap();
1514            for i in 1..4u64 {
1515                assert_eq!(writer.try_append_value(&i), Some(i * 8));
1516            }
1517
1518            assert_eq!(writer.try_append_value(&MustNotEncode::<8>), None);
1519            assert_eq!(writer.size(), 32);
1520            assert_eq!(
1521                snapshot.read_at(0, 8).await.unwrap().coalesce().as_ref(),
1522                &0u64.to_be_bytes()
1523            );
1524
1525            // The rejected value can use the ordinary crossing path without losing data.
1526            let (writer, offset) = writer.append(&4u64.to_be_bytes()).await.unwrap();
1527            assert_eq!(offset, 32);
1528            let writer = writer.sync().await.unwrap();
1529
1530            // The snapshot shares the writer's blob, so drop both before reopening. The reopened
1531            // writer must recover all five synced values.
1532            drop(snapshot);
1533            drop(writer);
1534            let (blob, size) = context.open("append_value", b"blob").await.unwrap();
1535            let writer = Writer::new(blob, size, 32, cache).await.unwrap();
1536            assert_eq!(writer.size(), 40);
1537            let expected: Vec<_> = (0..5u64).flat_map(u64::to_be_bytes).collect();
1538            assert_eq!(
1539                writer.read_at(0, 40).await.unwrap().coalesce().as_ref(),
1540                expected
1541            );
1542        });
1543    }
1544
1545    #[test_traced]
1546    fn test_append_variable_value_encodes_in_place() {
1547        // Record encoder calls and the first writable address to detect staging copies.
1548        struct Value {
1549            size: usize,
1550            size_calls: Cell<usize>,
1551            writes: Cell<usize>,
1552            destination: Cell<usize>,
1553        }
1554
1555        impl EncodeSize for Value {
1556            fn encode_size(&self) -> usize {
1557                self.size_calls.set(self.size_calls.get() + 1);
1558                self.size
1559            }
1560        }
1561
1562        impl Write for Value {
1563            fn write(&self, buf: &mut impl BufMut) {
1564                self.writes.set(self.writes.get() + 1);
1565                if self.size > 0 {
1566                    self.destination.set(buf.chunk_mut().as_mut_ptr() as usize);
1567                }
1568                buf.put_bytes(7, self.size);
1569            }
1570        }
1571
1572        deterministic::Runner::default().start(|context| async move {
1573            let (blob, size) = context.open("variable_value", b"blob").await.unwrap();
1574            let cache = CacheRef::new(NZU16!(16), NZUsize!(4));
1575            let mut writer = Writer::new(blob, size, 64, cache.clone()).await.unwrap();
1576            let mut value = Value {
1577                size: 3,
1578                size_calls: Cell::new(0),
1579                writes: Cell::new(0),
1580                destination: Cell::new(0),
1581            };
1582
1583            // The encoder writes into the tip itself, including when it crosses into a new
1584            // allocation and the old tail joins the full-page prefix.
1585            assert_eq!(writer.try_append_value(&value), Some(0));
1586            let tail = writer.buffer.parts().1.as_ptr() as usize;
1587            assert_eq!(value.destination.get(), tail);
1588            value.size = 5;
1589            assert_eq!(writer.try_append_value(&value), Some(3));
1590            assert_eq!(value.destination.get(), tail + 3);
1591            value.size = 17;
1592            assert_eq!(writer.try_append_value(&value), Some(8));
1593            assert_eq!(value.destination.get(), tail + 8);
1594            assert_eq!(
1595                writer.buffer.parts().0.chunk_at(0).unwrap().as_ptr() as usize,
1596                tail
1597            );
1598
1599            // Empty values are valid. Sizing happens once per attempt, and a capacity miss
1600            // never invokes the encoder or changes the writer.
1601            value.size = 0;
1602            assert_eq!(writer.try_append_value(&value), Some(25));
1603            value.size = 39;
1604            assert_eq!(writer.try_append_value(&value), Some(25));
1605            for size in [1, usize::MAX] {
1606                value.size = size;
1607                assert_eq!(writer.try_append_value(&value), None);
1608            }
1609            value.size = 0;
1610            assert_eq!(writer.try_append_value(&value), Some(64));
1611            assert_eq!(value.size_calls.get(), 8);
1612            assert_eq!(value.writes.get(), 6);
1613            assert_eq!(writer.size(), 64);
1614
1615            // Reopen the blob to verify that directly encoded bytes persist.
1616            writer = writer.sync().await.unwrap();
1617            drop(writer);
1618            let (blob, size) = context.open("variable_value", b"blob").await.unwrap();
1619            let writer = Writer::new(blob, size, 64, cache).await.unwrap();
1620            assert_eq!(writer.size(), 64);
1621            assert_eq!(
1622                writer.read_at(0, 64).await.unwrap().coalesce().as_ref(),
1623                &[7; 64]
1624            );
1625        });
1626    }
1627
1628    #[test_traced("DEBUG")]
1629    fn test_writes_use_uncached_hint() {
1630        let executor = deterministic::Runner::default();
1631        executor.start(|_: deterministic::Context| async move {
1632            let blob = SyncTrackingBlob::new();
1633            let blob = Arc::new(blob);
1634            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1635            let mut writer = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
1636                .await
1637                .unwrap();
1638            writer = writer.sync().await.unwrap();
1639
1640            (writer, _) = writer.append(b"first").await.unwrap();
1641            writer = writer.sync().await.unwrap();
1642            assert_eq!(blob.uncached_snapshot(), (0, 1));
1643
1644            (writer, _) = writer.append(b"second").await.unwrap();
1645            let (_, sync) = writer.seal().await.unwrap();
1646            sync.await.unwrap();
1647            assert_eq!(blob.uncached_snapshot(), (1, 1));
1648        });
1649    }
1650
1651    /// Unsynced partial-page flushes ([Writer::replay]) rewrite the tail page without a durability
1652    /// barrier. Every rewrite must keep the page's durable checksum slot byte-identical: a crash
1653    /// can cut the unsynced rewrites per byte, and whichever bytes land, the footer must still
1654    /// validate the synced prefix.
1655    #[test_traced("DEBUG")]
1656    fn test_unsynced_flushes_preserve_durable_checksum_slot() {
1657        let executor = deterministic::Runner::default();
1658        executor.start(|context: deterministic::Context| async move {
1659            let page_size = PAGE_SIZE.get() as usize;
1660            let physical_page = page_size + CHECKSUM_SIZE as usize;
1661            let (blob, blob_size) = context
1662                .open("test_partition", b"replay_torn")
1663                .await
1664                .unwrap();
1665            let blob = Arc::new(blob);
1666            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1667            let mut writer = Writer::new(blob.clone(), blob_size, BUFFER_SIZE, cache_ref.clone())
1668                .await
1669                .unwrap();
1670
1671            // Make a mid-page prefix durable and capture the page's durable image.
1672            let synced: Vec<u8> = (1u8..=24).collect();
1673            (writer, _) = writer.append(&synced).await.unwrap();
1674            writer = writer.sync().await.unwrap();
1675            let durable_image = blob
1676                .read_at(0, physical_page, ReadOptions::default())
1677                .await
1678                .unwrap()
1679                .coalesce();
1680
1681            // Two unsynced rewrites of the same page.
1682            (writer, _) = writer.append(&[25u8; 8]).await.unwrap();
1683            (writer, _) = writer
1684                .replay(NZUsize!(BUFFER_SIZE), ReadOptions::default())
1685                .await
1686                .unwrap();
1687            (writer, _) = writer.append(&[26u8; 8]).await.unwrap();
1688            writer
1689                .replay(NZUsize!(BUFFER_SIZE), ReadOptions::default())
1690                .await
1691                .unwrap();
1692            let torn_image = blob
1693                .read_at(0, physical_page, ReadOptions::default())
1694                .await
1695                .unwrap()
1696                .coalesce();
1697
1698            // Crash: of the unsynced rewrites, only the final one's footer bytes land, while
1699            // the logical region keeps its durable bytes.
1700            let mut crash = durable_image.as_ref().to_vec();
1701            crash[page_size..].copy_from_slice(&torn_image.as_ref()[page_size..]);
1702            let (crashed, _) = context
1703                .open("test_partition", b"replay_crash")
1704                .await
1705                .unwrap();
1706            crashed
1707                .write_at(0, crash, WriteOptions::default())
1708                .await
1709                .unwrap();
1710            crashed.sync().await.unwrap();
1711
1712            // The synced prefix must recover through the preserved durable slot.
1713            let recovered = Writer::new(crashed, physical_page as u64, BUFFER_SIZE, cache_ref)
1714                .await
1715                .unwrap();
1716            assert_eq!(recovered.size(), synced.len() as u64);
1717            let read = recovered.read_at(0, synced.len()).await.unwrap().coalesce();
1718            assert_eq!(read.as_ref(), synced.as_slice());
1719        });
1720    }
1721
1722    /// `recoverable_prefix_len` returns the full logical size when every page is well-formed.
1723    #[test_traced("DEBUG")]
1724    fn test_recoverable_prefix_len_clean() {
1725        let executor = deterministic::Runner::default();
1726        executor.start(|context: deterministic::Context| async move {
1727            let (context, recordings) = RecordingContext::new(context);
1728            let (blob, blob_size) = context
1729                .open("test_partition", b"prefix_clean")
1730                .await
1731                .unwrap();
1732            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1733            let mut writer = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
1734                .await
1735                .unwrap();
1736            assert_eq!(
1737                writer
1738                    .recoverable_prefix_len(0, NZUsize!(BUFFER_SIZE), ReadOptions::default())
1739                    .await
1740                    .unwrap(),
1741                0
1742            );
1743
1744            let total = PAGE_SIZE.get() as usize * 2 + 50;
1745            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
1746            (writer, _) = writer.append(&data).await.unwrap();
1747            writer = writer.sync().await.unwrap();
1748
1749            // Prefix validation uses the default options so recovery can reuse the validated pages.
1750            recordings.clear();
1751            assert_eq!(
1752                writer
1753                    .recoverable_prefix_len(0, NZUsize!(BUFFER_SIZE), ReadOptions::default())
1754                    .await
1755                    .unwrap(),
1756                total as u64
1757            );
1758            let reads = recordings.snapshot().reads;
1759            assert!(!reads.is_empty());
1760            assert!(
1761                reads
1762                    .iter()
1763                    .all(|options| *options == ReadOptions::default())
1764            );
1765
1766            drop(writer);
1767            let (blob, blob_size) = context
1768                .open("test_partition", b"prefix_clean")
1769                .await
1770                .unwrap();
1771
1772            // Reopening also validates the disk-authoritative tail with the default options.
1773            recordings.clear();
1774            let _recovered = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
1775                .await
1776                .unwrap();
1777            let reads = recordings.snapshot().reads;
1778            assert!(!reads.is_empty());
1779            assert!(
1780                reads
1781                    .iter()
1782                    .all(|options| *options == ReadOptions::default())
1783            );
1784        });
1785    }
1786
1787    /// The scan stops at the first torn page even when later pages remain valid, catching the
1788    /// interior hole the backward scan in `Writer::new` misses.
1789    #[test_traced("DEBUG")]
1790    fn test_recoverable_prefix_len_torn_interior_page() {
1791        let executor = deterministic::Runner::default();
1792        executor.start(|context: deterministic::Context| async move {
1793            let (blob, blob_size) = context
1794                .open("test_partition", b"prefix_torn")
1795                .await
1796                .unwrap();
1797            let blob = Arc::new(blob);
1798            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1799            let mut writer = Writer::new(blob.clone(), blob_size, BUFFER_SIZE, cache_ref)
1800                .await
1801                .unwrap();
1802            let total = PAGE_SIZE.get() as usize * 3 + 10;
1803            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
1804            (writer, _) = writer.append(&data).await.unwrap();
1805            writer = writer.sync().await.unwrap();
1806
1807            // Tear page 1, leaving pages 0 and 2+ valid.
1808            let physical_page_size = PAGE_SIZE.get() as u64 + CHECKSUM_SIZE;
1809            let offset = physical_page_size + 7;
1810            let byte = blob
1811                .read_at(offset, 1, ReadOptions::default())
1812                .await
1813                .unwrap()
1814                .coalesce();
1815            blob.write_at(
1816                offset,
1817                vec![byte.as_ref()[0] ^ 0xFF],
1818                WriteOptions::default(),
1819            )
1820            .await
1821            .unwrap();
1822            blob.sync().await.unwrap();
1823
1824            assert_eq!(
1825                writer
1826                    .recoverable_prefix_len(0, NZUsize!(BUFFER_SIZE), ReadOptions::default())
1827                    .await
1828                    .unwrap(),
1829                PAGE_SIZE.get() as u64
1830            );
1831        });
1832    }
1833
1834    /// A proven prefix skips its pages without reading them: a scan started past a torn page
1835    /// accepts the caller's proof, and a proof past the blob's end clamps without panicking.
1836    #[test_traced("DEBUG")]
1837    fn test_recoverable_prefix_len_proven_prefix() {
1838        let executor = deterministic::Runner::default();
1839        executor.start(|context: deterministic::Context| async move {
1840            let (blob, blob_size) = context
1841                .open("test_partition", b"prefix_proven")
1842                .await
1843                .unwrap();
1844            let blob = Arc::new(blob);
1845            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1846            let mut writer = Writer::new(blob.clone(), blob_size, BUFFER_SIZE, cache_ref)
1847                .await
1848                .unwrap();
1849            let total = PAGE_SIZE.get() as usize * 4;
1850            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
1851            (writer, _) = writer.append(&data).await.unwrap();
1852            writer = writer.sync().await.unwrap();
1853
1854            // Tear page 1, leaving pages 0 and 2+ valid.
1855            let physical_page_size = PAGE_SIZE.get() as u64 + CHECKSUM_SIZE;
1856            let offset = physical_page_size + 7;
1857            let byte = blob
1858                .read_at(offset, 1, ReadOptions::default())
1859                .await
1860                .unwrap()
1861                .coalesce();
1862            blob.write_at(
1863                offset,
1864                vec![byte.as_ref()[0] ^ 0xFF],
1865                WriteOptions::default(),
1866            )
1867            .await
1868            .unwrap();
1869            blob.sync().await.unwrap();
1870
1871            // An unproven scan stops at the torn page. A proof past it skips the damage and
1872            // scans the remainder, and a mid-page proof rescans the page containing it.
1873            let page = u64::from(PAGE_SIZE.get());
1874            for (proven, expected) in [
1875                (0, page),
1876                (page, page),
1877                (2 * page, 4 * page),
1878                (2 * page + 3, 4 * page),
1879                (total as u64, 4 * page),
1880            ] {
1881                assert_eq!(
1882                    writer
1883                        .recoverable_prefix_len(
1884                            proven,
1885                            NZUsize!(BUFFER_SIZE),
1886                            ReadOptions::default()
1887                        )
1888                        .await
1889                        .unwrap(),
1890                    expected,
1891                    "proven {proven}"
1892                );
1893            }
1894
1895            // A proof past the blob clamps to the pages that exist. Callers only pass proven
1896            // prefixes, and storage-level guards reject a prefix the blob cannot back.
1897            assert_eq!(
1898                writer
1899                    .recoverable_prefix_len(
1900                        100 * page,
1901                        NZUsize!(BUFFER_SIZE),
1902                        ReadOptions::default()
1903                    )
1904                    .await
1905                    .unwrap(),
1906                4 * page
1907            );
1908
1909            // A partial tail is still read when the proof overshoots the blob: the clamp stops
1910            // at the full pages, so the tail contributes its logical length, not a full page.
1911            (writer, _) = writer.append(&data[..20]).await.unwrap();
1912            writer = writer.sync().await.unwrap();
1913            for proven in [4 * page + 20, 5 * page, 100 * page] {
1914                assert_eq!(
1915                    writer
1916                        .recoverable_prefix_len(
1917                            proven,
1918                            NZUsize!(BUFFER_SIZE),
1919                            ReadOptions::default()
1920                        )
1921                        .await
1922                        .unwrap(),
1923                    4 * page + 20,
1924                    "proven {proven}"
1925                );
1926            }
1927        });
1928    }
1929
1930    /// A valid-but-short interior page ends the prefix: a partial page's durable state can
1931    /// survive a crash while its extension to a full page is lost.
1932    #[test_traced("DEBUG")]
1933    fn test_recoverable_prefix_len_stale_short_interior_page() {
1934        let executor = deterministic::Runner::default();
1935        executor.start(|context: deterministic::Context| async move {
1936            let (blob, blob_size) = context
1937                .open("test_partition", b"prefix_stale")
1938                .await
1939                .unwrap();
1940            let blob = Arc::new(blob);
1941            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1942            let mut writer = Writer::new(blob.clone(), blob_size, BUFFER_SIZE, cache_ref)
1943                .await
1944                .unwrap();
1945
1946            // Persist a partial first page and capture its physical bytes.
1947            let total = PAGE_SIZE.get() as usize * 2;
1948            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
1949            (writer, _) = writer.append(&data[..20]).await.unwrap();
1950            writer = writer.sync().await.unwrap();
1951            let physical_page_size = (PAGE_SIZE.get() as u64 + CHECKSUM_SIZE) as usize;
1952            let stale = blob
1953                .read_at(0, physical_page_size, ReadOptions::default())
1954                .await
1955                .unwrap()
1956                .coalesce();
1957            let stale = stale.as_ref().to_vec();
1958
1959            // Extend past the first page, persist, then restore page 0 to its stale partial
1960            // state as if the extension never reached disk.
1961            (writer, _) = writer.append(&data[20..]).await.unwrap();
1962            writer = writer.sync().await.unwrap();
1963            blob.write_at(0, stale, WriteOptions::default())
1964                .await
1965                .unwrap();
1966            blob.sync().await.unwrap();
1967
1968            assert_eq!(
1969                writer
1970                    .recoverable_prefix_len(0, NZUsize!(BUFFER_SIZE), ReadOptions::default())
1971                    .await
1972                    .unwrap(),
1973                20
1974            );
1975        });
1976    }
1977
1978    /// A clean scan derives its read batches from the supplied byte budget while always making
1979    /// progress by at least one page.
1980    #[test_traced("DEBUG")]
1981    fn test_recoverable_prefix_len_batches_reads() {
1982        let executor = deterministic::Runner::default();
1983        executor.start(|context: deterministic::Context| async move {
1984            let (context, recordings) = RecordingContext::new(context);
1985            let (blob, blob_size) = context
1986                .open("test_partition", b"prefix_batches")
1987                .await
1988                .unwrap();
1989            let blob = Arc::new(blob);
1990            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
1991            let mut writer = Writer::new(blob.clone(), blob_size, BUFFER_SIZE, cache_ref)
1992                .await
1993                .unwrap();
1994
1995            // Eight full pages plus a partial tail span three batches under a three-page budget.
1996            let total = PAGE_SIZE.get() as usize * 8 + 10;
1997            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
1998            (writer, _) = writer.append(&data).await.unwrap();
1999            writer = writer.sync().await.unwrap();
2000
2001            // A sub-page budget falls back to one page per read.
2002            recordings.clear();
2003            assert_eq!(
2004                writer
2005                    .recoverable_prefix_len(0, NZUsize!(1), ReadOptions::default())
2006                    .await
2007                    .unwrap(),
2008                total as u64
2009            );
2010            assert_eq!(recordings.snapshot().reads.len(), 9);
2011
2012            // A three-page budget coalesces the same scan into three reads.
2013            recordings.clear();
2014            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
2015            let scan_buffer = NonZeroUsize::new(physical_page_size * 3).unwrap();
2016            assert_eq!(
2017                writer
2018                    .recoverable_prefix_len(0, scan_buffer, ReadOptions::default())
2019                    .await
2020                    .unwrap(),
2021                total as u64
2022            );
2023            assert_eq!(recordings.snapshot().reads.len(), 3);
2024        });
2025    }
2026
2027    #[test_traced("DEBUG")]
2028    fn test_recoverable_prefix_len_at_most() {
2029        deterministic::Runner::default().start(|context| async move {
2030            let (context, recordings) = RecordingContext::new(context);
2031            let (blob, size) = context.open("bounded_prefix", b"blob").await.unwrap();
2032            let cache = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2033            let mut writer = Writer::new(blob, size, BUFFER_SIZE, cache).await.unwrap();
2034            let page = u64::from(PAGE_SIZE.get());
2035            let total = page * 8 + 10;
2036            (writer, _) = writer.append(&vec![7; total as usize]).await.unwrap();
2037            writer = writer.sync().await.unwrap();
2038
2039            // One-page reads make touching any page beyond the cap observable.
2040            for (cap, proven, expected_reads) in [
2041                (0, 0, 0),
2042                (1, 0, 1),
2043                (page, 0, 1),
2044                (page + 1, 0, 2),
2045                (page * 3, page, 2),
2046                (1, u64::MAX, 0),
2047                (total - 1, 0, 9),
2048                (total, 0, 9),
2049                (total + 1, 0, 9),
2050                (u64::MAX, 0, 9),
2051                (u64::MAX, u64::MAX, 1),
2052            ] {
2053                recordings.clear();
2054                assert_eq!(
2055                    writer
2056                        .recoverable_prefix_len_at_most(
2057                            proven,
2058                            cap,
2059                            NZUsize!(1),
2060                            ReadOptions::DONT_CACHE,
2061                        )
2062                        .await
2063                        .unwrap(),
2064                    cap.min(total),
2065                    "cap {cap}, proven {proven}",
2066                );
2067                let reads = recordings.snapshot().reads;
2068                assert_eq!(reads.len(), expected_reads, "cap {cap}, proven {proven}");
2069                assert!(
2070                    reads
2071                        .iter()
2072                        .all(|options| *options == ReadOptions::DONT_CACHE)
2073                );
2074            }
2075        });
2076    }
2077
2078    #[test_traced("DEBUG")]
2079    fn test_read_many_into_empty() {
2080        let executor = deterministic::Runner::default();
2081        executor.start(|context: deterministic::Context| async move {
2082            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2083            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2084            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2085                .await
2086                .unwrap();
2087
2088            (append, _) = append.append(&[0u8; 8]).await.unwrap();
2089            assert_eq!(append.size(), 8);
2090
2091            // Empty offsets should succeed immediately.
2092            let mut buf = [];
2093            append
2094                .read_many_into(&mut buf, &[], NZUsize!(4))
2095                .await
2096                .unwrap();
2097        });
2098    }
2099
2100    #[test_traced("DEBUG")]
2101    fn test_read_many_into_all_in_tip() {
2102        // All items reside in the unflushed tip buffer.
2103        let executor = deterministic::Runner::default();
2104        executor.start(|context: deterministic::Context| async move {
2105            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2106            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2107            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2108                .await
2109                .unwrap();
2110
2111            let data: Vec<u8> = (0..20).collect();
2112            (append, _) = append.append(&data).await.unwrap();
2113            assert_eq!(append.size(), 20);
2114
2115            // Read 4-byte items at offsets 0, 4, 8, 12, 16.
2116            let offsets = [0u64, 4, 8, 12, 16];
2117            let mut buf = vec![0u8; 5 * 4];
2118            append
2119                .read_many_into(&mut buf, &offsets, NZUsize!(4))
2120                .await
2121                .unwrap();
2122
2123            for (i, &off) in offsets.iter().enumerate() {
2124                assert_eq!(
2125                    &buf[i * 4..(i + 1) * 4],
2126                    &data[off as usize..off as usize + 4],
2127                );
2128            }
2129        });
2130    }
2131
2132    #[test_traced("DEBUG")]
2133    fn test_try_read_sync_all_in_tip() {
2134        let executor = deterministic::Runner::default();
2135        executor.start(|context: deterministic::Context| async move {
2136            let (blob, blob_size) = context
2137                .open("test_partition", b"try_read_sync_tip")
2138                .await
2139                .unwrap();
2140            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2141            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2142                .await
2143                .unwrap();
2144
2145            let data: Vec<u8> = (0..20).collect();
2146            (append, _) = append.append(&data).await.unwrap();
2147
2148            let mut buf = vec![0u8; data.len()];
2149            assert!(append.try_read_sync_into(&mut buf, 0));
2150            assert_eq!(buf, data);
2151        });
2152    }
2153
2154    #[test_traced("DEBUG")]
2155    fn test_try_read_sync_cache_miss() {
2156        let executor = deterministic::Runner::default();
2157        executor.start(|context: deterministic::Context| async move {
2158            let (blob, blob_size) = context
2159                .open("test_partition", b"try_read_sync_cache_miss")
2160                .await
2161                .unwrap();
2162
2163            // A one-page cache lets us prime the first page while leaving the second uncached.
2164            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(1));
2165            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2166                .await
2167                .unwrap();
2168
2169            let page_size = PAGE_SIZE.get() as usize;
2170            let data: Vec<u8> = (0u8..=255).cycle().take(page_size * 2).collect();
2171            (append, _) = append.append(&data).await.unwrap();
2172            append = append.sync().await.unwrap();
2173
2174            let _ = append.read_at(0, page_size).await.unwrap();
2175
2176            // A read straddling the cached first page and the uncached second page misses.
2177            let mut buf = vec![0xAA; 4];
2178            assert!(!append.try_read_sync_into(&mut buf, (page_size - 2) as u64));
2179        });
2180    }
2181
2182    #[test_traced("DEBUG")]
2183    fn test_read_many_into_all_from_cache() {
2184        // Synced bytes remain readable from the retained partial tip.
2185        let executor = deterministic::Runner::default();
2186        executor.start(|context: deterministic::Context| async move {
2187            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2188            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2189            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2190                .await
2191                .unwrap();
2192
2193            let data: Vec<u8> = (0..20).collect();
2194            (append, _) = append.append(&data).await.unwrap();
2195            append = append.sync().await.unwrap();
2196            assert_eq!(append.size(), 20);
2197
2198            let offsets = [0u64, 8, 16];
2199            let mut buf = vec![0u8; 3 * 4];
2200            append
2201                .read_many_into(&mut buf, &offsets, NZUsize!(4))
2202                .await
2203                .unwrap();
2204
2205            for (i, &off) in offsets.iter().enumerate() {
2206                assert_eq!(
2207                    &buf[i * 4..(i + 1) * 4],
2208                    &data[off as usize..off as usize + 4],
2209                );
2210            }
2211        });
2212    }
2213
2214    #[test_traced("DEBUG")]
2215    fn test_read_many_into_mixed_tip_and_cache() {
2216        // Synced and unsynced bytes share the same partial tip.
2217        let executor = deterministic::Runner::default();
2218        executor.start(|context: deterministic::Context| async move {
2219            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2220            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2221            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2222                .await
2223                .unwrap();
2224
2225            let first: Vec<u8> = (0..16).collect();
2226            (append, _) = append.append(&first).await.unwrap();
2227            append = append.sync().await.unwrap();
2228
2229            let second: Vec<u8> = (16..32).collect();
2230            (append, _) = append.append(&second).await.unwrap();
2231            assert_eq!(append.size(), 32);
2232
2233            // Offsets span both synced and unsynced regions.
2234            let offsets = [0u64, 4, 16, 24];
2235            let mut buf = vec![0u8; 4 * 4];
2236            append
2237                .read_many_into(&mut buf, &offsets, NZUsize!(4))
2238                .await
2239                .unwrap();
2240
2241            let all: Vec<u8> = (0..32).collect();
2242            for (i, &off) in offsets.iter().enumerate() {
2243                assert_eq!(
2244                    &buf[i * 4..(i + 1) * 4],
2245                    &all[off as usize..off as usize + 4],
2246                );
2247            }
2248        });
2249    }
2250
2251    #[test_traced("DEBUG")]
2252    fn test_read_many_into_out_of_bounds() {
2253        let executor = deterministic::Runner::default();
2254        executor.start(|context: deterministic::Context| async move {
2255            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2256            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2257            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2258                .await
2259                .unwrap();
2260
2261            (append, _) = append.append(&[0u8; 8]).await.unwrap();
2262            assert_eq!(append.size(), 8);
2263
2264            // Last offset's end (8 + 4 = 12) exceeds size (8).
2265            let mut buf = vec![0u8; 4];
2266            let err = append
2267                .read_many_into(&mut buf, &[8], NZUsize!(4))
2268                .await
2269                .unwrap_err();
2270            assert!(matches!(err, Error::BlobInsufficientLength));
2271        });
2272    }
2273
2274    #[test_traced("DEBUG")]
2275    fn test_read_many_into_single_item() {
2276        let executor = deterministic::Runner::default();
2277        executor.start(|context: deterministic::Context| async move {
2278            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2279            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2280            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2281                .await
2282                .unwrap();
2283
2284            let data = vec![0xAA; 8];
2285            (append, _) = append.append(&data).await.unwrap();
2286            assert_eq!(append.size(), 8);
2287
2288            let mut buf = vec![0u8; 8];
2289            append
2290                .read_many_into(&mut buf, &[0], NZUsize!(8))
2291                .await
2292                .unwrap();
2293            assert_eq!(&buf, &data);
2294        });
2295    }
2296
2297    #[test_traced("DEBUG")]
2298    #[should_panic(expected = "buf must hold one slot per range totaling its length")]
2299    fn test_read_many_into_rejects_invalid_buffer_len() {
2300        let executor = deterministic::Runner::default();
2301        executor.start(|context: deterministic::Context| async move {
2302            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2303            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2304            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2305                .await
2306                .unwrap();
2307
2308            let data: Vec<u8> = (0..16).collect();
2309            (append, _) = append.append(&data).await.unwrap();
2310
2311            let offsets = [0u64, 4];
2312            let mut buf = vec![0u8; 7];
2313            let _ = append.read_many_into(&mut buf, &offsets, NZUsize!(4)).await;
2314        });
2315    }
2316
2317    #[test_traced("DEBUG")]
2318    #[should_panic(expected = "ranges must be sorted and non-overlapping")]
2319    fn test_read_many_into_rejects_unsorted_offsets() {
2320        let executor = deterministic::Runner::default();
2321        executor.start(|context: deterministic::Context| async move {
2322            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2323            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2324            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2325                .await
2326                .unwrap();
2327
2328            let data: Vec<u8> = (0..16).collect();
2329            (append, _) = append.append(&data).await.unwrap();
2330
2331            let mut buf = vec![0u8; 8];
2332            let _ = append.read_many_into(&mut buf, &[8, 4], NZUsize!(4)).await;
2333        });
2334    }
2335
2336    #[test_traced("DEBUG")]
2337    #[should_panic(expected = "ranges must be sorted and non-overlapping")]
2338    fn test_read_many_into_rejects_overlapping_offsets() {
2339        let executor = deterministic::Runner::default();
2340        executor.start(|context: deterministic::Context| async move {
2341            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2342            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2343            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2344                .await
2345                .unwrap();
2346
2347            let data: Vec<u8> = (0..16).collect();
2348            (append, _) = append.append(&data).await.unwrap();
2349
2350            let mut buf = vec![0u8; 8];
2351            let _ = append.read_many_into(&mut buf, &[2, 4], NZUsize!(4)).await;
2352        });
2353    }
2354
2355    #[test_traced("DEBUG")]
2356    fn test_read_many_into_rejects_offset_overflow() {
2357        let executor = deterministic::Runner::default();
2358        executor.start(|context: deterministic::Context| async move {
2359            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2360            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2361            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2362                .await
2363                .unwrap();
2364
2365            let data: Vec<u8> = (0..16).collect();
2366            (append, _) = append.append(&data).await.unwrap();
2367
2368            let mut buf = vec![0u8; 8];
2369            let err = append
2370                .read_many_into(&mut buf, &[u64::MAX - 1, 4], NZUsize!(4))
2371                .await
2372                .unwrap_err();
2373            assert!(matches!(err, Error::OffsetOverflow));
2374        });
2375    }
2376
2377    #[test_traced("DEBUG")]
2378    fn test_read_many_into_matches_read_at() {
2379        // Verify read_many_into returns the same bytes as individual read_at calls.
2380        let executor = deterministic::Runner::default();
2381        executor.start(|context: deterministic::Context| async move {
2382            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2383            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2384            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2385                .await
2386                .unwrap();
2387
2388            // Write enough data to span multiple pages (PAGE_SIZE=103).
2389            let data: Vec<u8> = (0u8..=255).cycle().take(300).collect();
2390            (append, _) = append.append(&data).await.unwrap();
2391            append = append.sync().await.unwrap();
2392
2393            // Add more in tip buffer.
2394            let more: Vec<u8> = (0u8..50).collect();
2395            (append, _) = append.append(&more).await.unwrap();
2396            assert_eq!(append.size(), 350);
2397
2398            let item_size = 10;
2399            let offsets: Vec<u64> = (0..35).map(|i| i * item_size as u64).collect();
2400            let mut batch_buf = vec![0u8; offsets.len() * item_size];
2401            append
2402                .read_many_into(&mut batch_buf, &offsets, NZUsize!(item_size))
2403                .await
2404                .unwrap();
2405
2406            // Compare each item against individual read_at.
2407            for (i, &off) in offsets.iter().enumerate() {
2408                let single = append.read_at(off, item_size).await.unwrap().coalesce();
2409                assert_eq!(
2410                    &batch_buf[i * item_size..(i + 1) * item_size],
2411                    single.as_ref(),
2412                    "mismatch at offset {off}",
2413                );
2414            }
2415        });
2416    }
2417
2418    #[test_traced("DEBUG")]
2419    fn test_read_many_into_scattered_cache_misses() {
2420        // Exercises all three source paths in a single read_many_into call:
2421        // tip buffer, page cache hit, and page cache miss (blob I/O).
2422        // The tip holds a partial page so one item straddles the tip boundary.
2423        let executor = deterministic::Runner::default();
2424        executor.start(|context: deterministic::Context| async move {
2425            let (blob, blob_size) = context.open("test_partition", b"rmany").await.unwrap();
2426
2427            // Small cache: only 2 pages, so we can force eviction.
2428            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(2));
2429            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2430                .await
2431                .unwrap();
2432
2433            // Write 3 pages of data and sync to disk.
2434            let synced: Vec<u8> = (0u8..=255)
2435                .cycle()
2436                .take(PAGE_SIZE.get() as usize * 3)
2437                .collect();
2438            (append, _) = append.append(&synced).await.unwrap();
2439            append = append.sync().await.unwrap();
2440
2441            // Write a partial page that stays in the tip buffer. The item_size
2442            // is chosen so the last item straddles the synced/tip boundary.
2443            let item_size = 10;
2444            let tip_len = PAGE_SIZE.get() as usize / 2;
2445            let tip: Vec<u8> = (100u8..=255).cycle().take(tip_len).collect();
2446            (append, _) = append.append(&tip).await.unwrap();
2447
2448            // Prime pages 0 and 2 into cache, leaving page 1 uncached.
2449            let _ = append.read_at(0, item_size).await.unwrap();
2450            let _ = append
2451                .read_at(PAGE_SIZE.get() as u64 * 2, item_size)
2452                .await
2453                .unwrap();
2454
2455            // Offset that straddles the synced/tip boundary: starts in the last
2456            // synced page, ends in the tip buffer.
2457            let straddle_off = synced.len() as u64 - (item_size as u64 / 2);
2458            let tip_off = synced.len() as u64 + item_size as u64;
2459            let offsets = [
2460                0u64,                       // page 0 (cached)
2461                PAGE_SIZE.get() as u64,     // page 1 (not cached - blob I/O)
2462                PAGE_SIZE.get() as u64 * 2, // page 2 (cached)
2463                straddle_off,               // straddles synced/tip boundary
2464                tip_off,                    // entirely in tip buffer
2465            ];
2466            let mut buf = vec![0u8; offsets.len() * item_size];
2467            append
2468                .read_many_into(&mut buf, &offsets, NZUsize!(item_size))
2469                .await
2470                .unwrap();
2471
2472            let read: Vec<u8> = synced.iter().chain(tip.iter()).copied().collect();
2473            for (i, &off) in offsets.iter().enumerate() {
2474                assert_eq!(
2475                    &buf[i * item_size..(i + 1) * item_size],
2476                    &read[off as usize..off as usize + item_size],
2477                );
2478            }
2479        });
2480    }
2481
2482    #[test_traced("DEBUG")]
2483    fn test_read_many_into_straddle_prefix_miss() {
2484        // A straddling item whose synced prefix page is NOT in the page cache: the
2485        // suffix is copied from the tip buffer and the prefix is read from the blob
2486        // without clobbering it, and the item is counted as a blob read.
2487        let executor = deterministic::Runner::default();
2488        executor.start(|context: deterministic::Context| async move {
2489            let (blob, blob_size) = context
2490                .open("test_partition", b"rmany_smiss")
2491                .await
2492                .unwrap();
2493
2494            // Single-page cache so residency is deterministic.
2495            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(1));
2496            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2497                .await
2498                .unwrap();
2499
2500            // Write 3 pages and sync, then a partial page that stays in the tip.
2501            let synced: Vec<u8> = (0u8..=255)
2502                .cycle()
2503                .take(PAGE_SIZE.get() as usize * 3)
2504                .collect();
2505            (append, _) = append.append(&synced).await.unwrap();
2506            append = append.sync().await.unwrap();
2507            let item_size = 10;
2508            let tip: Vec<u8> = (100u8..=255)
2509                .cycle()
2510                .take(PAGE_SIZE.get() as usize / 2)
2511                .collect();
2512            (append, _) = append.append(&tip).await.unwrap();
2513
2514            // Fault page 0 in, evicting whatever sync left resident, so the straddle
2515            // prefix page (page 2) is guaranteed not cached.
2516            let _ = append.read_at(0, item_size).await.unwrap();
2517
2518            let straddle_off = synced.len() as u64 - (item_size as u64 / 2);
2519            let tip_off = synced.len() as u64 + item_size as u64;
2520            let offsets = [straddle_off, tip_off];
2521            let mut buf = vec![0u8; offsets.len() * item_size];
2522            let hits = append
2523                .read_many_into(&mut buf, &offsets, NZUsize!(item_size))
2524                .await
2525                .unwrap();
2526
2527            // The tip-only item is a hit; the straddle item required a blob read.
2528            assert_eq!(hits, 1);
2529            let read: Vec<u8> = synced.iter().chain(tip.iter()).copied().collect();
2530            for (i, &off) in offsets.iter().enumerate() {
2531                assert_eq!(
2532                    &buf[i * item_size..(i + 1) * item_size],
2533                    &read[off as usize..off as usize + item_size],
2534                );
2535            }
2536        });
2537    }
2538
2539    #[test_traced("DEBUG")]
2540    fn test_append_crc_empty() {
2541        let executor = deterministic::Runner::default();
2542        executor.start(|context: deterministic::Context| async move {
2543            // Open a new blob.
2544            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2545            assert_eq!(blob_size, 0);
2546
2547            // Create a page cache reference.
2548            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2549
2550            // Create a Writer.
2551            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2552                .await
2553                .unwrap();
2554
2555            // Verify initial size is 0.
2556            assert_eq!(append.size(), 0);
2557
2558            // Close & re-open.
2559            append = append.sync().await.unwrap();
2560            drop(append);
2561
2562            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2563            assert_eq!(blob_size, 0); // There was no need to write a crc since there was no data.
2564
2565            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2566                .await
2567                .unwrap();
2568
2569            assert_eq!(append.size(), 0);
2570        });
2571    }
2572
2573    #[test_traced("DEBUG")]
2574    fn test_append_crc_basic() {
2575        let executor = deterministic::Runner::default();
2576        executor.start(|context: deterministic::Context| async move {
2577            // Open a new blob.
2578            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2579            assert_eq!(blob_size, 0);
2580
2581            // Create a page cache reference.
2582            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2583
2584            // Create a Writer.
2585            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2586                .await
2587                .unwrap();
2588
2589            // Verify initial size is 0.
2590            assert_eq!(append.size(), 0);
2591
2592            // Append some bytes.
2593            let data = vec![1, 2, 3, 4, 5];
2594            (append, _) = append.append(&data).await.unwrap();
2595
2596            // Verify size reflects appended data.
2597            assert_eq!(append.size(), 5);
2598
2599            // Append more bytes.
2600            let more_data = vec![6, 7, 8, 9, 10];
2601            (append, _) = append.append(&more_data).await.unwrap();
2602
2603            // Verify size is cumulative.
2604            assert_eq!(append.size(), 10);
2605
2606            // Read back the first chunk and verify.
2607            let read_buf = append.read_at(0, 5).await.unwrap().coalesce();
2608            assert_eq!(read_buf, &data[..]);
2609
2610            // Read back the second chunk and verify.
2611            let read_buf = append.read_at(5, 5).await.unwrap().coalesce();
2612            assert_eq!(read_buf, &more_data[..]);
2613
2614            // Read all data at once and verify.
2615            let read_buf = append.read_at(0, 10).await.unwrap().coalesce();
2616            assert_eq!(read_buf, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
2617
2618            // Close and reopen the blob and make sure the data is still there and the trailing
2619            // checksum is written & stripped as expected.
2620            append = append.sync().await.unwrap();
2621            drop(append);
2622
2623            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2624            // Physical page = 103 logical + 12 Checksum = 115 bytes (padded partial page)
2625            assert_eq!(blob_size, 115);
2626            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2627                .await
2628                .unwrap();
2629            assert_eq!(append.size(), 10); // CRC should be stripped after verification
2630
2631            // Append data that spans a page boundary.
2632            // PAGE_SIZE=103 is the logical page size. We have 10 bytes, so writing
2633            // 100 more bytes (total 110) will cross the page boundary at byte 103.
2634            let spanning_data: Vec<u8> = (11..=110).collect();
2635            (append, _) = append.append(&spanning_data).await.unwrap();
2636            assert_eq!(append.size(), 110);
2637
2638            // Read back data that spans the page boundary.
2639            let read_buf = append.read_at(10, 100).await.unwrap().coalesce();
2640            assert_eq!(read_buf, &spanning_data[..]);
2641
2642            // Read all 110 bytes at once.
2643            let read_buf = append.read_at(0, 110).await.unwrap().coalesce();
2644            let expected: Vec<u8> = (1..=110).collect();
2645            assert_eq!(read_buf, &expected[..]);
2646
2647            // Drop and re-open and make sure bytes are still there.
2648            append = append.sync().await.unwrap();
2649            drop(append);
2650
2651            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2652            // 2 physical pages: 2 * 115 = 230 bytes
2653            assert_eq!(blob_size, 230);
2654            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2655                .await
2656                .unwrap();
2657            assert_eq!(append.size(), 110);
2658
2659            // Append data to reach exactly a page boundary.
2660            // Logical page size is 103. We have 110 bytes, next boundary is 206 (103 * 2).
2661            // So we need 96 more bytes.
2662            let boundary_data: Vec<u8> = (111..=206).collect();
2663            assert_eq!(boundary_data.len(), 96);
2664            (append, _) = append.append(&boundary_data).await.unwrap();
2665            assert_eq!(append.size(), 206);
2666
2667            // Verify we can read it back.
2668            let read_buf = append.read_at(0, 206).await.unwrap().coalesce();
2669            let expected: Vec<u8> = (1..=206).collect();
2670            assert_eq!(read_buf, &expected[..]);
2671
2672            // Drop and re-open at the page boundary.
2673            append = append.sync().await.unwrap();
2674            drop(append);
2675
2676            let (blob, blob_size) = context.open("test_partition", b"test_blob").await.unwrap();
2677            // Physical size should be exactly 2 pages: 115 * 2 = 230 bytes
2678            assert_eq!(blob_size, 230);
2679            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2680                .await
2681                .unwrap();
2682            assert_eq!(append.size(), 206);
2683
2684            // Verify data is still readable after reopen.
2685            let read_buf = append.read_at(0, 206).await.unwrap().coalesce();
2686            assert_eq!(read_buf, &expected[..]);
2687        });
2688    }
2689
2690    #[test_traced("DEBUG")]
2691    fn test_append_owned_bypass_from_empty_tip() {
2692        // A large owned append from an empty, page-aligned tip writes whole pages directly to the
2693        // blob and leaves the partial-page suffix buffered.
2694        let executor = deterministic::Runner::default();
2695        executor.start(|context: deterministic::Context| async move {
2696            let (blob, blob_size) = context
2697                .open("test_partition", b"owned_empty")
2698                .await
2699                .unwrap();
2700            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2701            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2702                .await
2703                .unwrap();
2704
2705            // 500 bytes = 4 full pages (412 bytes) + 88-byte remainder.
2706            let data: Vec<u8> = (0..500).map(|i| (i % 251) as u8).collect();
2707            let src = IoBuf::from(data.clone());
2708            let src_start = src.as_ptr() as usize;
2709            let src_range = src_start..src_start + src.len();
2710            (append, _) = append.append_owned(src.clone()).await.unwrap();
2711            assert_eq!(append.size(), 500);
2712
2713            // The buffered suffix is a copy, not a view that would pin the input allocation.
2714            let tip_ptr = append.buffer.parts().1.as_ptr() as usize;
2715            assert!(!src_range.contains(&tip_ptr));
2716
2717            // The directly written pages populate the page cache, exactly as a buffered flush
2718            // would.
2719            let mut probe = vec![0u8; PAGE_SIZE.get() as usize];
2720            assert_eq!(
2721                append.cache_ref.read_cached(append.id, &mut probe, 0),
2722                PAGE_SIZE.get() as usize
2723            );
2724            assert_eq!(probe, &data[..PAGE_SIZE.get() as usize]);
2725
2726            // All bytes are readable before any sync (bulk from the cache, suffix from tip).
2727            let read_buf = append.read_at(0, 500).await.unwrap().coalesce();
2728            assert_eq!(read_buf, &data[..]);
2729
2730            // Everything becomes durable with a single sync.
2731            append = append.sync().await.unwrap();
2732            drop(append);
2733
2734            let (blob, blob_size) = context
2735                .open("test_partition", b"owned_empty")
2736                .await
2737                .unwrap();
2738            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2739                .await
2740                .unwrap();
2741            assert_eq!(append.size(), 500);
2742            let read_buf = append.read_at(0, 500).await.unwrap().coalesce();
2743            assert_eq!(read_buf, &data[..]);
2744        });
2745    }
2746
2747    #[test_traced("DEBUG")]
2748    fn test_append_owned_bypass_with_synced_partial_page() {
2749        // A large owned append on top of a synced partial page must rewrite the first page in
2750        // full (preserving the old CRC slot) before writing the bulk directly.
2751        let executor = deterministic::Runner::default();
2752        executor.start(|context: deterministic::Context| async move {
2753            let (blob, blob_size) = context
2754                .open("test_partition", b"owned_partial")
2755                .await
2756                .unwrap();
2757            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2758            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2759                .await
2760                .unwrap();
2761
2762            // Durably write a 50-byte partial page.
2763            let all: Vec<u8> = (0..500).map(|i| (i % 247) as u8).collect();
2764            (append, _) = append.append(&all[..50]).await.unwrap();
2765            append = append.sync().await.unwrap();
2766
2767            // 450 more bytes: 53 fill the first page (rewritten in full), 3 whole pages (309 bytes)
2768            // bypass the buffer, 88 remain in the tip.
2769            (append, _) = append
2770                .append_owned(IoBuf::from(all[50..].to_vec()))
2771                .await
2772                .unwrap();
2773            assert_eq!(append.size(), 500);
2774            let read_buf = append.read_at(0, 500).await.unwrap().coalesce();
2775            assert_eq!(read_buf, &all[..]);
2776
2777            // The direct write is not durable until sync: dropping without one preserves only the
2778            // synced 50-byte prefix.
2779            drop(append);
2780            let (blob, blob_size) = context
2781                .open("test_partition", b"owned_partial")
2782                .await
2783                .unwrap();
2784            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2785                .await
2786                .unwrap();
2787            assert_eq!(append.size(), 50);
2788            let read_buf = append.read_at(0, 50).await.unwrap().coalesce();
2789            assert_eq!(read_buf, &all[..50]);
2790
2791            // Repeating the owned append after recovery and syncing makes everything durable,
2792            // exercising the full rewrite of the recovered partial page.
2793            (append, _) = append
2794                .append_owned(IoBuf::from(all[50..].to_vec()))
2795                .await
2796                .unwrap();
2797            append = append.sync().await.unwrap();
2798            drop(append);
2799
2800            let (blob, blob_size) = context
2801                .open("test_partition", b"owned_partial")
2802                .await
2803                .unwrap();
2804            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2805                .await
2806                .unwrap();
2807            assert_eq!(append.size(), 500);
2808            let read_buf = append.read_at(0, 500).await.unwrap().coalesce();
2809            assert_eq!(read_buf, &all[..]);
2810        });
2811    }
2812
2813    #[test_traced("DEBUG")]
2814    fn test_append_owned_bypass_with_buffered_tip() {
2815        // A large owned append merges with unsynced buffered bytes: the fill completes the
2816        // current page, the bulk bypasses the buffer, and everything is readable.
2817        let executor = deterministic::Runner::default();
2818        executor.start(|context: deterministic::Context| async move {
2819            let (blob, blob_size) = context
2820                .open("test_partition", b"owned_buffered")
2821                .await
2822                .unwrap();
2823            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2824            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2825                .await
2826                .unwrap();
2827
2828            let all: Vec<u8> = (0..430).map(|i| (i % 239) as u8).collect();
2829            (append, _) = append.append(&all[..30]).await.unwrap();
2830            (append, _) = append
2831                .append_owned(IoBuf::from(all[30..].to_vec()))
2832                .await
2833                .unwrap();
2834            assert_eq!(append.size(), 430);
2835            let read_buf = append.read_at(0, 430).await.unwrap().coalesce();
2836            assert_eq!(read_buf, &all[..]);
2837
2838            append = append.sync().await.unwrap();
2839            drop(append);
2840
2841            let (blob, blob_size) = context
2842                .open("test_partition", b"owned_buffered")
2843                .await
2844                .unwrap();
2845            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2846                .await
2847                .unwrap();
2848            assert_eq!(append.size(), 430);
2849            let read_buf = append.read_at(0, 430).await.unwrap().coalesce();
2850            assert_eq!(read_buf, &all[..]);
2851        });
2852    }
2853
2854    #[test_traced("DEBUG")]
2855    fn test_append_owned_exact_page_multiple_and_small() {
2856        // An owned append of an exact page multiple leaves an empty tip that later buffered and
2857        // small owned appends continue from; small owned appends use the buffered path.
2858        let executor = deterministic::Runner::default();
2859        executor.start(|context: deterministic::Context| async move {
2860            let (blob, blob_size) = context
2861                .open("test_partition", b"owned_exact")
2862                .await
2863                .unwrap();
2864            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2865            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2866                .await
2867                .unwrap();
2868
2869            // Exactly 4 pages: no remainder.
2870            let bulk: Vec<u8> = (0..412).map(|i| (i % 233) as u8).collect();
2871            (append, _) = append
2872                .append_owned(IoBuf::from(bulk.clone()))
2873                .await
2874                .unwrap();
2875            assert_eq!(append.size(), 412);
2876
2877            // A small owned append takes the buffered path.
2878            let small: Vec<u8> = (0..10).map(|i| (i % 229) as u8).collect();
2879            (append, _) = append
2880                .append_owned(IoBuf::from(small.clone()))
2881                .await
2882                .unwrap();
2883            assert_eq!(append.size(), 422);
2884
2885            let read_buf = append.read_at(0, 422).await.unwrap().coalesce();
2886            assert_eq!(&read_buf.as_ref()[..412], &bulk[..]);
2887            assert_eq!(&read_buf.as_ref()[412..], &small[..]);
2888
2889            append = append.sync().await.unwrap();
2890            drop(append);
2891
2892            let (blob, blob_size) = context
2893                .open("test_partition", b"owned_exact")
2894                .await
2895                .unwrap();
2896            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
2897                .await
2898                .unwrap();
2899            assert_eq!(append.size(), 422);
2900        });
2901    }
2902
2903    #[test_traced("DEBUG")]
2904    fn test_append_owned_physical_bytes_match_buffered() {
2905        // The direct path must produce byte-identical physical output (page layout, CRC slot
2906        // placement, zero padding) to the buffered path for the same logical content.
2907        let executor = deterministic::Runner::default();
2908        executor.start(|context: deterministic::Context| async move {
2909            let data: Vec<u8> = (0..500).map(|i| (i % 251) as u8).collect();
2910            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2911
2912            let (blob, size) = context
2913                .open("test_partition", b"phys_direct")
2914                .await
2915                .unwrap();
2916            let mut direct = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
2917                .await
2918                .unwrap();
2919            (direct, _) = direct
2920                .append_owned(IoBuf::from(data.clone()))
2921                .await
2922                .unwrap();
2923            direct = direct.sync().await.unwrap();
2924            drop(direct);
2925
2926            // Small appends always stay on the buffered path and force intermediate flushes.
2927            let (blob, size) = context
2928                .open("test_partition", b"phys_buffered")
2929                .await
2930                .unwrap();
2931            let mut buffered = Writer::new(blob, size, BUFFER_SIZE, cache_ref)
2932                .await
2933                .unwrap();
2934            for chunk in data.chunks(10) {
2935                (buffered, _) = buffered.append(chunk).await.unwrap();
2936            }
2937            buffered = buffered.sync().await.unwrap();
2938            drop(buffered);
2939
2940            let (blob_a, size_a) = context
2941                .open("test_partition", b"phys_direct")
2942                .await
2943                .unwrap();
2944            let (blob_b, size_b) = context
2945                .open("test_partition", b"phys_buffered")
2946                .await
2947                .unwrap();
2948            assert_eq!(size_a, size_b);
2949            let bytes_a = blob_a
2950                .read_at(0, size_a as usize, ReadOptions::default())
2951                .await
2952                .unwrap()
2953                .coalesce();
2954            let bytes_b = blob_b
2955                .read_at(0, size_b as usize, ReadOptions::default())
2956                .await
2957                .unwrap()
2958                .coalesce();
2959            assert_eq!(bytes_a.as_ref(), bytes_b.as_ref());
2960        });
2961    }
2962
2963    #[test_traced("DEBUG")]
2964    fn test_append_borrowed_large_takes_direct_path() {
2965        // A plain `append` larger than the write buffer is routed through the direct path, so the
2966        // write buffer holds only the partial-page suffix afterwards instead of the whole input.
2967        let executor = deterministic::Runner::default();
2968        executor.start(|context: deterministic::Context| async move {
2969            let (blob, blob_size) = context
2970                .open("test_partition", b"borrowed_large")
2971                .await
2972                .unwrap();
2973            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
2974            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref.clone())
2975                .await
2976                .unwrap();
2977
2978            // Start misaligned with a small buffered prefix.
2979            let all: Vec<u8> = (0..530).map(|i| (i % 241) as u8).collect();
2980            (append, _) = append.append(&all[..30]).await.unwrap();
2981
2982            // 500 more bytes exceed the 206-byte write buffer and take the direct path.
2983            (append, _) = append.append(&all[30..]).await.unwrap();
2984            assert_eq!(append.size(), 530);
2985
2986            // Only the partial-page suffix remains buffered (530 = 5 full pages + 15 bytes).
2987            assert_eq!(append.buffer.len(), 15);
2988
2989            let read_buf = append.read_at(0, 530).await.unwrap().coalesce();
2990            assert_eq!(read_buf, &all[..]);
2991
2992            append = append.sync().await.unwrap();
2993            drop(append);
2994
2995            let (blob, blob_size) = context
2996                .open("test_partition", b"borrowed_large")
2997                .await
2998                .unwrap();
2999            let append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
3000                .await
3001                .unwrap();
3002            assert_eq!(append.size(), 530);
3003            let read_buf = append.read_at(0, 530).await.unwrap().coalesce();
3004            assert_eq!(read_buf, &all[..]);
3005        });
3006    }
3007
3008    #[test]
3009    fn test_sync_preserves_partial_tip_allocation() {
3010        const PAGE_SIZE: NonZeroU16 = NZU16!(4096);
3011        const BUFFER_SIZE: usize = 8192;
3012        deterministic::Runner::default().start(|context| async move {
3013            let cache = CacheRef::new(PAGE_SIZE, NZUsize!(1));
3014            let (blob, size) = context
3015                .open("test_partition", b"partial_seal")
3016                .await
3017                .unwrap();
3018            let mut writer = Writer::new(blob, size, BUFFER_SIZE, cache).await.unwrap();
3019            (writer, _) = writer.append(&[7; 16]).await.unwrap();
3020            let ptr = writer.buffer.parts().1.as_ptr();
3021
3022            // Active partial-page syncs preserve the reusable write allocation.
3023            writer = writer.sync().await.unwrap();
3024            assert_eq!(writer.buffer.parts().1.as_ptr(), ptr);
3025            (writer, _) = writer.append(&[7; 16]).await.unwrap();
3026            assert_eq!(writer.buffer.parts().1.as_ptr(), ptr);
3027
3028            let (sealed, sync) = writer.seal().await.unwrap();
3029            assert_eq!(
3030                sealed.read_at(0, 32).await.unwrap().coalesce().as_ref(),
3031                &[7; 32]
3032            );
3033            sync.await.unwrap();
3034        });
3035    }
3036
3037    #[test]
3038    fn test_recovery_sync_preserves_truncate_and_append() {
3039        deterministic::Runner::default().start(|context| async move {
3040            let page_size = NZU16!(64);
3041            let cache = CacheRef::new(page_size, NZUsize!(4));
3042            let (blob, size) = context
3043                .open("test_partition", b"compact_recovery")
3044                .await
3045                .unwrap();
3046            let mut recovery = Recovery::open(blob, size, 256, cache.clone())
3047                .await
3048                .unwrap();
3049            let mut expected: Vec<u8> = (0..129).collect();
3050            (recovery, _) = recovery.append(&expected).await.unwrap();
3051            recovery = recovery.sync().await.unwrap();
3052            assert_eq!(recovery.buffer.len(), 1);
3053            assert_eq!(recovery.buffer.capacity, 256);
3054
3055            // The earlier partial page is larger than the compacted tail.
3056            recovery = recovery.truncate(95).await.unwrap();
3057            expected.truncate(95);
3058            let suffix = [7; 80];
3059            (recovery, _) = recovery.append(&suffix).await.unwrap();
3060            expected.extend_from_slice(&suffix);
3061            recovery = recovery.sync().await.unwrap();
3062            assert_eq!(recovery.buffer.capacity, 256);
3063            drop(recovery);
3064
3065            let (blob, size) = context
3066                .open("test_partition", b"compact_recovery")
3067                .await
3068                .unwrap();
3069            let writer = Writer::new(blob, size, 256, cache).await.unwrap();
3070            assert_eq!(writer.size(), expected.len() as u64);
3071            assert_eq!(
3072                writer
3073                    .read_at(0, expected.len())
3074                    .await
3075                    .unwrap()
3076                    .coalesce()
3077                    .as_ref(),
3078                expected
3079            );
3080        });
3081    }
3082
3083    #[test_traced("DEBUG")]
3084    fn test_sync_uses_range_sync_for_single_flush() {
3085        let executor = deterministic::Runner::default();
3086        executor.start(|_: deterministic::Context| async move {
3087            let blob = SyncTrackingBlob::new();
3088            let blob = Arc::new(blob);
3089            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3090            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3091                .await
3092                .unwrap();
3093
3094            // A newly wrapped blob preserves one full barrier before range sync is used.
3095            append = append.sync().await.unwrap();
3096            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3097            assert_eq!(writes, 0);
3098            assert_eq!(full_syncs, 1);
3099            assert_eq!(range_syncs, 0);
3100
3101            // A single buffered write with no remaining dirty state can be made durable directly.
3102            let data = b"hello world";
3103            (append, _) = append.append(data).await.unwrap();
3104            append = append.sync().await.unwrap();
3105
3106            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3107            assert_eq!(writes, 1);
3108            assert_eq!(full_syncs, 1);
3109            assert_eq!(range_syncs, 1);
3110
3111            // With no new writes and no pending full-sync barrier, sync has no work left.
3112            append.sync().await.unwrap();
3113            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3114            assert_eq!(writes, 1);
3115            assert_eq!(full_syncs, 1);
3116            assert_eq!(range_syncs, 1);
3117
3118            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3119            let reopened = Writer::new(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3120                .await
3121                .unwrap();
3122            let read = reopened.read_at(0, data.len()).await.unwrap().coalesce();
3123            assert_eq!(read.as_ref(), data);
3124        });
3125    }
3126
3127    /// Observing a completed started sync lets the next write use range sync.
3128    #[test_traced("DEBUG")]
3129    fn test_start_sync_persists_and_marks_clean() {
3130        let executor = deterministic::Runner::default();
3131        executor.start(|_: deterministic::Context| async move {
3132            let blob = SyncTrackingBlob::new();
3133            let blob = Arc::new(blob);
3134            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3135            let writer = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3136                .await
3137                .unwrap();
3138
3139            // Complete the fresh writer's full sync with no buffered bytes to write.
3140            let (mut writer, handle) = writer.start_sync().await.unwrap();
3141            handle.await.unwrap();
3142            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3143            assert_eq!(writes, 0);
3144            assert_eq!(full_syncs, 1);
3145            assert_eq!(range_syncs, 0);
3146
3147            // The next mutation observes the completed sync and can sync just its new range.
3148            let data = b"hello world";
3149            (writer, _) = writer.append(data).await.unwrap();
3150            writer = writer.sync().await.unwrap();
3151            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3152            assert_eq!(writes, 1);
3153            assert_eq!(full_syncs, 1);
3154            assert_eq!(range_syncs, 1);
3155
3156            // Nothing left to sync, so start_sync does nothing.
3157            let (_, handle) = writer.start_sync().await.unwrap();
3158            handle.await.unwrap();
3159            let (_, _, full_syncs, range_syncs) = blob.snapshot();
3160            assert_eq!(full_syncs, 1);
3161            assert_eq!(range_syncs, 1);
3162
3163            // Durable and readable after reopening.
3164            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3165            let reopened = Writer::new(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3166                .await
3167                .unwrap();
3168            let read = reopened.read_at(0, data.len()).await.unwrap().coalesce();
3169            assert_eq!(read.as_ref(), data);
3170        });
3171    }
3172
3173    /// A failed flush inside `start_sync` returns an error.
3174    #[test_traced("DEBUG")]
3175    fn test_start_sync_flush_failure_returns_err() {
3176        let executor = deterministic::Runner::default();
3177        executor.start(|context: deterministic::Context| async move {
3178            let faults = WriteFaults::default();
3179            let context = WriteFaultContext {
3180                inner: context,
3181                faults: faults.clone(),
3182            };
3183            let (blob, size) = context
3184                .open("test_partition", b"start_sync_flush_failure")
3185                .await
3186                .unwrap();
3187            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3188            let mut writer = Writer::new(blob, size, BUFFER_SIZE, cache_ref)
3189                .await
3190                .unwrap();
3191
3192            // Make a partial page durable, then extend it so the next flush rewrites the page.
3193            (writer, _) = writer.append(&[1u8; 24]).await.unwrap();
3194            writer = writer.sync().await.unwrap();
3195            (writer, _) = writer.append(&[2u8; 8]).await.unwrap();
3196
3197            // The rewrite inside start_sync fails.
3198            faults.arm();
3199            assert!(writer.start_sync().await.is_err());
3200        });
3201    }
3202
3203    /// `needs_sync` reports whether `sync` has work: buffered pages, unsynced mutations, or a
3204    /// started sync that the writer has not observed.
3205    #[test_traced("DEBUG")]
3206    fn test_needs_sync_tracks_sync_work() {
3207        let executor = deterministic::Runner::default();
3208        executor.start(|context: deterministic::Context| async move {
3209            let (blob, size) = context.open("test_partition", b"needs_sync").await.unwrap();
3210            let (blob, pending) = DelayedSyncBlob::new(blob);
3211            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3212            let writer = Writer::new(blob, size, BUFFER_SIZE, cache_ref)
3213                .await
3214                .unwrap();
3215
3216            // A fresh writer starts dirty. Its tail page must be durable before appends, but
3217            // earlier full pages may still hold unsynced writes, so the first sync is a full-blob
3218            // barrier.
3219            assert!(writer.needs_sync());
3220            let mut writer = writer.sync().await.unwrap();
3221            assert!(!writer.needs_sync());
3222
3223            // A buffered partial page is flush work even though the blob is clean.
3224            (writer, _) = writer.append(&[1u8; 20]).await.unwrap();
3225            assert!(writer.needs_sync());
3226            writer = writer.sync().await.unwrap();
3227            assert!(!writer.needs_sync());
3228
3229            // A started sync needs observation while it is in flight and after it completes.
3230            (writer, _) = writer.append(&[2u8; 4]).await.unwrap();
3231            let (writer, handle) = writer.start_sync().await.unwrap();
3232            assert!(writer.needs_sync());
3233            next_pending_sync(&pending).release.send(Ok(())).unwrap();
3234            handle.await.unwrap();
3235            assert!(writer.needs_sync());
3236            let mut writer = writer.wait_for_sync().await.unwrap();
3237            assert!(!writer.needs_sync());
3238
3239            // A failed started sync keeps the writer in need of a sync. The handle reports the
3240            // failure, and so does the next sync.
3241            (writer, _) = writer.append(&[3u8; 8]).await.unwrap();
3242            let (writer, handle) = writer.start_sync().await.unwrap();
3243            next_pending_sync(&pending)
3244                .release
3245                .send(Err(Error::Closed))
3246                .unwrap();
3247            assert!(handle.await.is_err());
3248            assert!(writer.needs_sync());
3249            assert!(writer.sync().await.is_err());
3250        });
3251    }
3252
3253    /// Verifies sync waits for a pending start_sync with no new writes.
3254    #[test_traced("DEBUG")]
3255    fn test_sync_waits_for_outstanding_start_sync() {
3256        let executor = deterministic::Runner::default();
3257        executor.start(|_: deterministic::Context| async move {
3258            let inner = SyncTrackingBlob::new();
3259            let inner = Arc::new(inner);
3260            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3261            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3262            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3263
3264            let (writer, handle) = writer.start_sync().await.unwrap();
3265            let deferred = next_pending_sync(&pending);
3266
3267            // Try to sync while the started sync is still blocked.
3268            let mut sync = Box::pin(writer.sync());
3269            assert!(
3270                sync.as_mut().now_or_never().is_none(),
3271                "sync must wait for the outstanding start_sync handle"
3272            );
3273            let (_, _, full_syncs, range_syncs) = inner.snapshot();
3274            assert_eq!(full_syncs, 0);
3275            assert_eq!(range_syncs, 0);
3276
3277            // Release the started sync and finish the same sync.
3278            deferred.release.send(Ok(())).unwrap();
3279            sync.await.unwrap();
3280            handle.await.unwrap();
3281            let (_, _, full_syncs, range_syncs) = inner.snapshot();
3282            assert_eq!(full_syncs, 1);
3283            assert_eq!(range_syncs, 0);
3284        });
3285    }
3286
3287    /// Verifies a small buffered write cannot range-sync before pending start_sync finishes.
3288    #[test_traced("DEBUG")]
3289    fn test_sync_after_start_sync_and_small_write_waits_before_range_sync() {
3290        let executor = deterministic::Runner::default();
3291        executor.start(|_: deterministic::Context| async move {
3292            let inner = SyncTrackingBlob::new();
3293            let inner = Arc::new(inner);
3294            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3295            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3296            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3297
3298            let (writer, handle) = writer.start_sync().await.unwrap();
3299            let deferred = next_pending_sync(&pending);
3300            let (writer, _) = writer.append(b"hello world").await.unwrap();
3301
3302            // Sync must wait before flushing the buffered write.
3303            let mut sync = Box::pin(writer.sync());
3304            assert!(
3305                sync.as_mut().now_or_never().is_none(),
3306                "sync must join the outstanding barrier before flushing the small write"
3307            );
3308            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3309            assert_eq!(writes, 0);
3310            assert_eq!(full_syncs, 0);
3311            assert_eq!(range_syncs, 0);
3312
3313            // Release the started sync, then let the same sync flush the buffered write.
3314            deferred.release.send(Ok(())).unwrap();
3315            sync.await.unwrap();
3316            handle.await.unwrap();
3317            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3318            assert_eq!(writes, 1);
3319            assert_eq!(full_syncs, 1);
3320            assert_eq!(range_syncs, 1);
3321        });
3322    }
3323
3324    /// Verifies a large append cannot flush before pending start_sync finishes.
3325    #[test_traced("DEBUG")]
3326    fn test_write_flush_waits_for_outstanding_start_sync() {
3327        let executor = deterministic::Runner::default();
3328        executor.start(|context: deterministic::Context| async move {
3329            let inner = SyncTrackingBlob::new();
3330            let inner = Arc::new(inner);
3331            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3332            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3333            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3334
3335            let (mut writer, handle) = writer.start_sync().await.unwrap();
3336            let deferred = next_pending_sync(&pending);
3337
3338            let data = vec![7; BUFFER_SIZE + PAGE_SIZE.get() as usize];
3339            let append = context.child("append").spawn(move |_| async move {
3340                (writer, _) = writer.append(&data).await.unwrap();
3341                writer
3342            });
3343
3344            // The append has reached the pending sync wait.
3345            deferred
3346                .blocked
3347                .await
3348                .expect("append never waited on start_sync");
3349            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3350            assert_eq!(writes, 0);
3351            assert_eq!(full_syncs, 0);
3352            assert_eq!(range_syncs, 0);
3353
3354            // Release the started sync so the append can flush.
3355            deferred.release.send(Ok(())).unwrap();
3356            let writer = append.await.unwrap();
3357            handle.await.unwrap();
3358            writer.sync().await.unwrap();
3359            let (_, writes, full_syncs, _) = inner.snapshot();
3360            assert!(writes > 0);
3361            assert!(full_syncs > 0);
3362        });
3363    }
3364
3365    /// Verifies seal cannot flush buffered bytes before pending start_sync finishes.
3366    #[test_traced("DEBUG")]
3367    fn test_seal_waits_for_outstanding_start_sync_before_flushing() {
3368        let executor = deterministic::Runner::default();
3369        executor.start(|context: deterministic::Context| async move {
3370            let inner = SyncTrackingBlob::new();
3371            let inner = Arc::new(inner);
3372            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3373            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3374            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3375
3376            let (mut writer, prior) = writer.start_sync().await.unwrap();
3377            let deferred = next_pending_sync(&pending);
3378            (writer, _) = writer.append(b"hello world").await.unwrap();
3379
3380            let seal = context
3381                .child("seal")
3382                .spawn(move |_| async move { writer.seal().await });
3383
3384            // The seal has reached the pending sync wait.
3385            deferred
3386                .blocked
3387                .await
3388                .expect("seal never waited on start_sync");
3389            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3390            assert_eq!(writes, 0);
3391            assert_eq!(full_syncs, 0);
3392            assert_eq!(range_syncs, 0);
3393
3394            // Release the started sync so seal can flush.
3395            deferred.release.send(Ok(())).unwrap();
3396            let (sealed, sync) = seal.await.unwrap().unwrap();
3397            prior.await.unwrap();
3398
3399            // Release the sync started by seal itself.
3400            let deferred = next_pending_sync(&pending);
3401            deferred.release.send(Ok(())).unwrap();
3402            sync.await.unwrap();
3403            let read = sealed
3404                .read_at(0, b"hello world".len())
3405                .await
3406                .unwrap()
3407                .coalesce();
3408            assert_eq!(read.as_ref(), b"hello world");
3409            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3410            assert_eq!(writes, 1);
3411            assert_eq!(full_syncs, 2);
3412            assert_eq!(range_syncs, 0);
3413        });
3414    }
3415
3416    /// Verifies snapshot cannot flush buffered bytes before pending start_sync finishes.
3417    #[test_traced("DEBUG")]
3418    fn test_snapshot_waits_for_outstanding_start_sync_before_flushing() {
3419        let executor = deterministic::Runner::default();
3420        executor.start(|context: deterministic::Context| async move {
3421            let inner = SyncTrackingBlob::new();
3422            let inner = Arc::new(inner);
3423            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3424            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3425            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3426
3427            // Start a sync, then buffer a full page and a partial page not covered by it.
3428            let data = [7u8; PAGE_SIZE.get() as usize + 47];
3429            let (mut writer, prior) = writer.start_sync().await.unwrap();
3430            let deferred = next_pending_sync(&pending);
3431            (writer, _) = writer.append(&data).await.unwrap();
3432
3433            let snapshot = context.child("snapshot").spawn(move |_| async move {
3434                let (writer, snapshot) = writer.snapshot().await.unwrap();
3435                let read = snapshot.read_at(0, data.len()).await.unwrap().coalesce();
3436                assert_eq!(read.as_ref(), data.as_slice());
3437                writer
3438            });
3439
3440            // Snapshot must wait before flushing the full page.
3441            deferred
3442                .blocked
3443                .await
3444                .expect("snapshot never waited on start_sync");
3445            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3446            assert_eq!(writes, 0);
3447            assert_eq!(full_syncs, 0);
3448            assert_eq!(range_syncs, 0);
3449
3450            // Releasing the sync lets snapshot flush the full page and read the buffered bytes.
3451            deferred.release.send(Ok(())).unwrap();
3452            let _writer = snapshot.await.unwrap();
3453            prior.await.unwrap();
3454            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3455            assert_eq!(writes, 1);
3456            assert_eq!(full_syncs, 1);
3457            assert_eq!(range_syncs, 0);
3458        });
3459    }
3460
3461    /// A snapshot copies the partial page instead of writing it, and later appends and syncs
3462    /// leave its view unchanged.
3463    #[test_traced("DEBUG")]
3464    fn test_snapshot_copies_partial_page_without_writing() {
3465        let executor = deterministic::Runner::default();
3466        executor.start(|_: deterministic::Context| async move {
3467            let blob = Arc::new(SyncTrackingBlob::new());
3468            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3469            let writer = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3470                .await
3471                .unwrap();
3472
3473            // Snapshot a partial page without writing it.
3474            let (writer, _) = writer.append(b"hello").await.unwrap();
3475            let (writer, snapshot) = writer.snapshot().await.unwrap();
3476            let (_, writes, _, _) = blob.snapshot();
3477            assert_eq!(writes, 0);
3478
3479            // Appending and syncing later bytes writes the page without changing the view.
3480            let (writer, _) = writer.append(b" world").await.unwrap();
3481            let _writer = writer.sync().await.unwrap();
3482            let (_, writes, _, _) = blob.snapshot();
3483            assert_eq!(writes, 1);
3484            assert_eq!(snapshot.size(), 5);
3485            let read = snapshot.read_at(0, 5).await.unwrap().coalesce();
3486            assert_eq!(read.as_ref(), b"hello");
3487        });
3488    }
3489
3490    /// A view without I/O is available only while every full page is already written.
3491    #[test_traced]
3492    fn test_try_snapshot_requires_written_full_pages() {
3493        let executor = deterministic::Runner::default();
3494        executor.start(|_: deterministic::Context| async move {
3495            let blob = Arc::new(SyncTrackingBlob::new());
3496            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3497            let writer = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3498                .await
3499                .unwrap();
3500
3501            // A partial page alone is copied into the view without a write.
3502            let (writer, _) = writer.append(b"hello").await.unwrap();
3503            let view = writer.try_snapshot().expect("partial page needs no write");
3504            assert_eq!(view.size(), 5);
3505            let read = view.read_at(0, 5).await.unwrap().coalesce();
3506            assert_eq!(read.as_ref(), b"hello");
3507            let (_, writes, _, _) = blob.snapshot();
3508            assert_eq!(writes, 0);
3509
3510            // A buffered full page must be written before a view can be taken.
3511            let page = vec![b'x'; PAGE_SIZE.get() as usize];
3512            let (writer, _) = writer.append(&page).await.unwrap();
3513            assert!(writer.try_snapshot().is_none());
3514
3515            // Once written, the view covers every byte and replays the full page from the blob.
3516            let (writer, snapshot) = writer.snapshot().await.unwrap();
3517            let (_, writes, _, _) = blob.snapshot();
3518            assert_eq!(writes, 1);
3519            let view = writer.try_snapshot().expect("full pages are written");
3520            assert_eq!(view.size(), snapshot.size());
3521            let mut replay = view
3522                .replay(NZUsize!(BUFFER_SIZE), ReadOptions::default())
3523                .unwrap();
3524            let total = 5 + page.len();
3525            assert!(replay.ensure(total).await.unwrap());
3526            let bytes = replay.copy_to_bytes(total);
3527            assert_eq!(&bytes[..5], b"hello");
3528            assert!(bytes[5..].iter().all(|byte| *byte == b'x'));
3529            assert!(!replay.ensure(1).await.unwrap());
3530        });
3531    }
3532
3533    /// Verifies replay cannot flush buffered bytes before pending start_sync finishes.
3534    #[test_traced("DEBUG")]
3535    fn test_replay_waits_for_outstanding_start_sync_before_flushing() {
3536        let executor = deterministic::Runner::default();
3537        executor.start(|context: deterministic::Context| async move {
3538            let inner = SyncTrackingBlob::new();
3539            let inner = Arc::new(inner);
3540            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3541            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3542            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3543
3544            // Start a sync, then buffer newer bytes not covered by it.
3545            let (mut writer, prior) = writer.start_sync().await.unwrap();
3546            let deferred = next_pending_sync(&pending);
3547            (writer, _) = writer.append(b"hello world").await.unwrap();
3548
3549            let replay = context.child("replay").spawn(move |_| async move {
3550                let (writer, mut replay) = writer
3551                    .replay(NZUsize!(BUFFER_SIZE), ReadOptions::default())
3552                    .await
3553                    .unwrap();
3554                assert!(replay.ensure(1).await.unwrap());
3555                assert_eq!(replay.chunk()[0], b'h');
3556                writer
3557            });
3558
3559            // Replay must wait before flushing buffered bytes.
3560            deferred
3561                .blocked
3562                .await
3563                .expect("replay never waited on start_sync");
3564            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3565            assert_eq!(writes, 0);
3566            assert_eq!(full_syncs, 0);
3567            assert_eq!(range_syncs, 0);
3568
3569            // Releasing the sync lets replay flush and read the buffered bytes.
3570            deferred.release.send(Ok(())).unwrap();
3571            let _writer = replay.await.unwrap();
3572            prior.await.unwrap();
3573            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3574            assert_eq!(writes, 1);
3575            assert_eq!(full_syncs, 1);
3576            assert_eq!(range_syncs, 0);
3577        });
3578    }
3579
3580    #[test_traced("DEBUG")]
3581    fn test_append_waits_for_outstanding_start_sync_before_writing() {
3582        let executor = deterministic::Runner::default();
3583        executor.start(|context: deterministic::Context| async move {
3584            let inner = SyncTrackingBlob::new();
3585            let inner = Arc::new(inner);
3586            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3587            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3588            let writer = Writer::new(blob, 0, BUFFER_SIZE, cache_ref).await.unwrap();
3589
3590            // Start a sync before growing into the direct-write path.
3591            let (mut writer, prior) = writer.start_sync().await.unwrap();
3592            let deferred = next_pending_sync(&pending);
3593
3594            let target_size = (BUFFER_SIZE + PAGE_SIZE.get() as usize) as u64;
3595            let append = context.child("append").spawn(move |_| async move {
3596                (writer, _) = writer.append(&vec![0; target_size as usize]).await.unwrap();
3597                writer
3598            });
3599
3600            // Growth must wait before writing zero-filled pages.
3601            deferred
3602                .blocked
3603                .await
3604                .expect("append never waited on start_sync");
3605            let (_, writes, full_syncs, range_syncs) = inner.snapshot();
3606            assert_eq!(writes, 0);
3607            assert_eq!(full_syncs, 0);
3608            assert_eq!(range_syncs, 0);
3609
3610            // Releasing the sync lets the append complete.
3611            deferred.release.send(Ok(())).unwrap();
3612            let writer = append.await.unwrap();
3613            prior.await.unwrap();
3614            assert_eq!(writer.size(), target_size);
3615            writer.sync().await.unwrap();
3616            let (_, writes, full_syncs, _) = inner.snapshot();
3617            assert!(writes > 0);
3618            assert!(full_syncs > 0);
3619        });
3620    }
3621
3622    // Recovery cannot resize the blob before a pending start_sync finishes.
3623    #[test_traced("DEBUG")]
3624    fn test_recovery_truncate_shrink_waits_for_outstanding_start_sync_before_resizing() {
3625        let executor = deterministic::Runner::default();
3626        executor.start(|context: deterministic::Context| async move {
3627            let inner = SyncTrackingBlob::new();
3628            let inner = Arc::new(inner);
3629            let (blob, pending) = DelayedSyncBlob::new(inner.clone());
3630            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3631            let mut writer = Recovery::open(blob, 0, BUFFER_SIZE, cache_ref)
3632                .await
3633                .unwrap();
3634
3635            // Build durable pages, then start a sync for a newer partial page.
3636            let data = vec![3; PAGE_SIZE.get() as usize * 2];
3637            (writer, _) = writer.append(&data).await.unwrap();
3638            writer = writer.sync().await.unwrap();
3639            (writer, _) = writer.append(b"x").await.unwrap();
3640            let (mut writer, prior) = writer.start_sync().await.unwrap();
3641            let deferred = next_pending_sync(&pending);
3642            let physical_size = inner.size();
3643
3644            let resize = context.child("resize_shrink").spawn(move |_| async move {
3645                writer = writer.truncate(PAGE_SIZE.get() as u64).await.unwrap();
3646                writer
3647            });
3648
3649            // Shrink must wait before truncating the physical blob.
3650            deferred
3651                .blocked
3652                .await
3653                .expect("resize shrink never waited on start_sync");
3654            assert_eq!(
3655                inner.size(),
3656                physical_size,
3657                "resize must not shrink the blob before the pending sync finishes"
3658            );
3659
3660            // Releasing the sync lets the shrink truncate the blob.
3661            deferred.release.send(Ok(())).unwrap();
3662            let writer = resize.await.unwrap();
3663            prior.await.unwrap();
3664            assert_eq!(writer.size(), PAGE_SIZE.get() as u64);
3665            assert!(inner.size() < physical_size);
3666        });
3667    }
3668
3669    #[test_traced("DEBUG")]
3670    fn test_sync_uses_full_sync_after_prior_plain_flush() {
3671        let executor = deterministic::Runner::default();
3672        executor.start(|_: deterministic::Context| async move {
3673            let blob = SyncTrackingBlob::new();
3674            let blob = Arc::new(blob);
3675            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3676            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3677                .await
3678                .unwrap();
3679
3680            // This append overflows the buffer, so a plain flush happens before sync writes the
3681            // remaining tip.
3682            let data = vec![7u8; BUFFER_SIZE + 1];
3683            (append, _) = append.append(&data).await.unwrap();
3684            append = append.sync().await.unwrap();
3685
3686            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3687            assert_eq!(writes, 2);
3688            assert_eq!(full_syncs, 1);
3689            assert_eq!(range_syncs, 0);
3690
3691            // With no new work, sync should not issue another durability operation.
3692            append = append.sync().await.unwrap();
3693            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3694            assert_eq!(writes, 2);
3695            assert_eq!(full_syncs, 1);
3696            assert_eq!(range_syncs, 0);
3697
3698            // With the earlier flush already durable, extending the partial page is one
3699            // full-page rewrite fused with a range sync.
3700            (append, _) = append.append(b"tip").await.unwrap();
3701            append.sync().await.unwrap();
3702
3703            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3704            assert_eq!(writes, 3);
3705            assert_eq!(full_syncs, 1);
3706            assert_eq!(range_syncs, 1);
3707
3708            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3709            let reopened = Writer::new(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3710                .await
3711                .unwrap();
3712            let mut expected = data;
3713            expected.extend_from_slice(b"tip");
3714            let read = reopened
3715                .read_at(0, expected.len())
3716                .await
3717                .unwrap()
3718                .coalesce();
3719            assert_eq!(read.as_ref(), expected.as_slice());
3720        });
3721    }
3722
3723    #[test_traced("DEBUG")]
3724    fn test_sync_uses_full_sync_after_replay_plain_flush() {
3725        let executor = deterministic::Runner::default();
3726        executor.start(|_: deterministic::Context| async move {
3727            let blob = SyncTrackingBlob::new();
3728            let blob = Arc::new(blob);
3729            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3730            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3731                .await
3732                .unwrap();
3733
3734            // Keep data buffered so replay has to flush it without syncing.
3735            (append, _) = append.append(b"replayed").await.unwrap();
3736
3737            // Replay flushes buffered data for reading, but does not make that write durable.
3738            let (append, mut replay) = append
3739                .replay(NZUsize!(1024), ReadOptions::default())
3740                .await
3741                .unwrap();
3742            assert!(replay.ensure(b"replayed".len()).await.unwrap());
3743            assert_eq!(replay.remaining(), b"replayed".len());
3744            assert_eq!(replay.chunk(), b"replayed");
3745
3746            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3747            assert_eq!(writes, 1);
3748            assert_eq!(full_syncs, 0);
3749            assert_eq!(range_syncs, 0);
3750
3751            // A later sync must use a full barrier for the plain replay flush.
3752            append.sync().await.unwrap();
3753            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3754            assert_eq!(writes, 1);
3755            assert_eq!(full_syncs, 1);
3756            assert_eq!(range_syncs, 0);
3757        });
3758    }
3759
3760    #[test_traced("DEBUG")]
3761    fn test_replay_uses_read_options_for_refills_and_seek() {
3762        let executor = deterministic::Runner::default();
3763        executor.start(|context: deterministic::Context| async move {
3764            let (blob, size) = context
3765                .open("test_partition", b"replay_read_options")
3766                .await
3767                .unwrap();
3768            let blob = PartialWriteBlob::new(blob, usize::MAX, 0);
3769            let read_options = blob.read_options();
3770            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3771            let mut writer = Writer::new(blob, size, BUFFER_SIZE, cache_ref)
3772                .await
3773                .unwrap();
3774
3775            let page_size = PAGE_SIZE.get() as usize;
3776            let data = vec![3; page_size * 2];
3777            (writer, _) = writer.append(&data).await.unwrap();
3778            writer = writer.sync().await.unwrap();
3779            read_options.lock().clear();
3780
3781            let physical_page_size = page_size + CHECKSUM_SIZE as usize;
3782            let (_, mut replay) = writer
3783                .replay(NZUsize!(physical_page_size), ReadOptions::DONT_CACHE)
3784                .await
3785                .unwrap();
3786
3787            // The first fill reads page 0 and starts page 1 in flight, both with the replay's
3788            // read options, so crossing the page boundary needs no further read.
3789            assert!(replay.ensure(1).await.unwrap());
3790            replay.advance(page_size);
3791            assert!(replay.ensure(1).await.unwrap());
3792            assert_eq!(*read_options.lock(), vec![ReadOptions::DONT_CACHE; 2]);
3793
3794            // Seeking discards the buffered pages and reads both again with the same options.
3795            replay.seek_to(0).unwrap();
3796            assert!(replay.ensure(1).await.unwrap());
3797            assert_eq!(*read_options.lock(), vec![ReadOptions::DONT_CACHE; 4]);
3798        });
3799    }
3800
3801    #[test_traced("DEBUG")]
3802    fn test_recreated_sync_preserves_replay_plain_flush_barrier() {
3803        let executor = deterministic::Runner::default();
3804        executor.start(|_: deterministic::Context| async move {
3805            let blob = SyncTrackingBlob::new();
3806            let blob = Arc::new(blob);
3807            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3808            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3809                .await
3810                .unwrap();
3811
3812            (append, _) = append.append(b"replayed").await.unwrap();
3813            let (append, mut replay) = append
3814                .replay(NZUsize!(1024), ReadOptions::default())
3815                .await
3816                .unwrap();
3817            assert!(replay.ensure(b"replayed".len()).await.unwrap());
3818            assert_eq!(replay.remaining(), b"replayed".len());
3819            assert_eq!(replay.chunk(), b"replayed");
3820            drop(replay);
3821            drop(append);
3822
3823            let (durable, writes, full_syncs, range_syncs) = blob.snapshot();
3824            assert!(durable.is_empty());
3825            assert_eq!(writes, 1);
3826            assert_eq!(full_syncs, 0);
3827            assert_eq!(range_syncs, 0);
3828
3829            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3830            let reopened = Recovery::open(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3831                .await
3832                .unwrap();
3833            assert_eq!(reopened.size(), b"replayed".len() as u64);
3834            reopened.sync().await.unwrap();
3835
3836            let (durable, writes, full_syncs, range_syncs) = blob.snapshot();
3837            assert_eq!(durable.len(), blob.size() as usize);
3838            assert_eq!(writes, 1);
3839            assert_eq!(full_syncs, 1);
3840            assert_eq!(range_syncs, 0);
3841        });
3842    }
3843
3844    #[test_traced("DEBUG")]
3845    fn test_recreated_sync_skips_barrier_after_invalid_truncation() {
3846        let executor = deterministic::Runner::default();
3847        executor.start(|_: deterministic::Context| async move {
3848            let blob = SyncTrackingBlob::new();
3849            let blob = Arc::new(blob);
3850            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3851            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3852                .await
3853                .unwrap();
3854            append = append.sync().await.unwrap();
3855            (append, _) = append.append(b"valid").await.unwrap();
3856            append = append.sync().await.unwrap();
3857            drop(append);
3858
3859            blob.write_at(blob.size(), b"junk", WriteOptions::default())
3860                .await
3861                .unwrap();
3862
3863            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3864            let reopened = Writer::new(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3865                .await
3866                .unwrap();
3867            assert_eq!(reopened.size(), b"valid".len() as u64);
3868
3869            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3870            assert_eq!(writes, 2);
3871            assert_eq!(full_syncs, 2);
3872            assert_eq!(range_syncs, 1);
3873
3874            reopened.sync().await.unwrap();
3875
3876            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3877            assert_eq!(writes, 2);
3878            assert_eq!(full_syncs, 2);
3879            assert_eq!(range_syncs, 1);
3880        });
3881    }
3882
3883    #[test_traced("DEBUG")]
3884    fn test_sync_fuses_partial_page_rewrite() {
3885        let executor = deterministic::Runner::default();
3886        executor.start(|_: deterministic::Context| async move {
3887            let blob = SyncTrackingBlob::new();
3888            let blob = Arc::new(blob);
3889            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3890            let mut append = Writer::new(blob.clone(), 0, BUFFER_SIZE, cache_ref)
3891                .await
3892                .unwrap();
3893            append = append.sync().await.unwrap();
3894
3895            // Establish a persisted partial page with the authoritative CRC in slot 0.
3896            (append, _) = append.append(b"abc").await.unwrap();
3897            append = append.sync().await.unwrap();
3898
3899            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3900            assert_eq!(writes, 1);
3901            assert_eq!(full_syncs, 1);
3902            assert_eq!(range_syncs, 1);
3903
3904            let slot0_offset = PAGE_SIZE.get() as u64;
3905            let slot1_offset = slot0_offset + CHECKSUM_SLOT_SIZE as u64;
3906            let slot0_before: Vec<u8> = blob
3907                .read_at(slot0_offset, CHECKSUM_SLOT_SIZE, ReadOptions::default())
3908                .await
3909                .unwrap()
3910                .coalesce()
3911                .freeze()
3912                .into();
3913
3914            // Extending that partial page rewrites the whole physical page in one write fused
3915            // with a range sync, resubmitting the protected slot 0 byte-identically and placing
3916            // the new CRC in slot 1.
3917            (append, _) = append.append(b"de").await.unwrap();
3918            append = append.sync().await.unwrap();
3919
3920            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3921            assert_eq!(writes, 2);
3922            assert_eq!(full_syncs, 1);
3923            assert_eq!(range_syncs, 2);
3924
3925            let slot0_after: Vec<u8> = blob
3926                .read_at(slot0_offset, CHECKSUM_SLOT_SIZE, ReadOptions::default())
3927                .await
3928                .unwrap()
3929                .coalesce()
3930                .freeze()
3931                .into();
3932            assert_eq!(
3933                slot0_before, slot0_after,
3934                "protected slot must be resubmitted byte-identically"
3935            );
3936            let slot1_between: Vec<u8> = blob
3937                .read_at(slot1_offset, CHECKSUM_SLOT_SIZE, ReadOptions::default())
3938                .await
3939                .unwrap()
3940                .coalesce()
3941                .freeze()
3942                .into();
3943
3944            // The next extension protects slot 1 and rewrites slot 0, again as one fused write.
3945            (append, _) = append.append(b"fg").await.unwrap();
3946            append.sync().await.unwrap();
3947
3948            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
3949            assert_eq!(writes, 3);
3950            assert_eq!(full_syncs, 1);
3951            assert_eq!(range_syncs, 3);
3952
3953            let slot1_after: Vec<u8> = blob
3954                .read_at(slot1_offset, CHECKSUM_SLOT_SIZE, ReadOptions::default())
3955                .await
3956                .unwrap()
3957                .coalesce()
3958                .freeze()
3959                .into();
3960            assert_eq!(
3961                slot1_between, slot1_after,
3962                "protected slot must be resubmitted byte-identically"
3963            );
3964
3965            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3966            let reopened = Writer::new(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
3967                .await
3968                .unwrap();
3969            let read = reopened.read_at(0, 7).await.unwrap().coalesce();
3970            assert_eq!(read.as_ref(), b"abcdefg");
3971        });
3972    }
3973
3974    #[test_traced("DEBUG")]
3975    fn test_read_up_to_zero_len_truncates_buffer() {
3976        let executor = deterministic::Runner::default();
3977        executor.start(|context: deterministic::Context| async move {
3978            // Open a new blob.
3979            let (blob, blob_size) = context
3980                .open("test_partition", b"read_up_to_zero_len")
3981                .await
3982                .unwrap();
3983            assert_eq!(blob_size, 0);
3984
3985            // Create a page cache reference.
3986            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
3987
3988            // Create a Writer and write some data.
3989            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
3990                .await
3991                .unwrap();
3992            (append, _) = append.append(&[1, 2, 3, 4]).await.unwrap();
3993
3994            // Request a zero-length read with a reused, non-empty buffer.
3995            let stale = vec![9u8, 8, 7, 6];
3996            let (buf, read) = append.read_up_to(0, 0, stale).await.unwrap();
3997
3998            assert_eq!(read, 0);
3999            assert_eq!(buf.len(), 0, "read_up_to must truncate returned buffer");
4000            assert_eq!(buf.freeze().as_ref(), b"");
4001        });
4002    }
4003
4004    /// Helper to read the CRC record from raw blob bytes at the end of a physical page.
4005    fn read_crc_record_from_page(page_bytes: &[u8]) -> Checksum {
4006        let crc_start = page_bytes.len() - CHECKSUM_SIZE as usize;
4007        Checksum::read(&mut Copying(&page_bytes[crc_start..])).unwrap()
4008    }
4009
4010    /// Blob wrapper that makes only some bytes of one write durable and then fails that write.
4011    struct PartialWriteBlob<B: Blob> {
4012        inner: B,
4013        writes: Arc<AtomicUsize>,
4014        read_options: Arc<Mutex<Vec<ReadOptions>>>,
4015        failed_write_len: Arc<AtomicUsize>,
4016        fail_on: usize,
4017        kept: [Range<usize>; 2],
4018    }
4019
4020    impl<B: Blob> PartialWriteBlob<B> {
4021        /// Wraps `inner` to fail write `fail_on` after its first `partial_len` bytes are durable.
4022        fn new(inner: B, fail_on: usize, partial_len: usize) -> Self {
4023            Self::keeping(inner, fail_on, 0..partial_len)
4024        }
4025
4026        /// Wraps `inner` to fail write `fail_on` after only its `kept` bytes are durable.
4027        fn keeping(inner: B, fail_on: usize, kept: Range<usize>) -> Self {
4028            Self::torn(inner, fail_on, [kept, 0..0])
4029        }
4030
4031        /// Wraps `inner` to fail write `fail_on` after its `kept` byte ranges are durable.
4032        fn torn(inner: B, fail_on: usize, kept: [Range<usize>; 2]) -> Self {
4033            Self {
4034                inner,
4035                writes: Arc::new(AtomicUsize::new(0)),
4036                read_options: Arc::new(Mutex::new(Vec::new())),
4037                failed_write_len: Arc::new(AtomicUsize::new(0)),
4038                fail_on,
4039                kept,
4040            }
4041        }
4042
4043        fn failed_write_len(&self) -> Arc<AtomicUsize> {
4044            self.failed_write_len.clone()
4045        }
4046
4047        fn write_count(&self) -> Arc<AtomicUsize> {
4048            self.writes.clone()
4049        }
4050
4051        fn read_options(&self) -> Arc<Mutex<Vec<ReadOptions>>> {
4052            self.read_options.clone()
4053        }
4054    }
4055
4056    impl<B: Blob> crate::Blob for PartialWriteBlob<B> {
4057        async fn read_at(
4058            &self,
4059            offset: u64,
4060            len: usize,
4061            options: ReadOptions,
4062        ) -> Result<IoBufsMut, Error> {
4063            self.read_options.lock().push(options);
4064            self.inner.read_at(offset, len, options).await
4065        }
4066
4067        async fn read_at_buf(
4068            &self,
4069            offset: u64,
4070            len: usize,
4071            bufs: impl Into<IoBufsMut> + Send,
4072            options: ReadOptions,
4073        ) -> Result<IoBufsMut, Error> {
4074            self.read_options.lock().push(options);
4075            self.inner.read_at_buf(offset, len, bufs, options).await
4076        }
4077
4078        async fn write_at(
4079            &self,
4080            offset: u64,
4081            bufs: impl Into<IoBufs> + Send,
4082            options: WriteOptions,
4083        ) -> Result<(), Error> {
4084            let bufs = bufs.into();
4085            let write = self.writes.fetch_add(1, Ordering::SeqCst) + 1;
4086            if write == self.fail_on {
4087                let bytes = bufs.coalesce();
4088                self.failed_write_len.store(bytes.len(), Ordering::SeqCst);
4089
4090                // Only the kept ranges reach the blob, clamped to this write, and they are durable
4091                // before the write fails.
4092                for kept in &self.kept {
4093                    let kept = kept.start.min(bytes.len())..kept.end.min(bytes.len());
4094                    if kept.is_empty() {
4095                        continue;
4096                    }
4097                    self.inner
4098                        .write_at(
4099                            offset + Widen::<u64>::widen(kept.start),
4100                            bytes.slice(kept),
4101                            options,
4102                        )
4103                        .await?;
4104                }
4105                if !options.contains(WriteOptions::SYNC) {
4106                    self.inner.sync().await?;
4107                }
4108                return Err(Error::Io(
4109                    std::io::Error::other("injected partial write").into(),
4110                ));
4111            }
4112
4113            self.inner.write_at(offset, bufs, options).await
4114        }
4115
4116        async fn resize(&self, len: u64) -> Result<(), Error> {
4117            self.inner.resize(len).await
4118        }
4119
4120        async fn sync(&self) -> Result<(), Error> {
4121            self.inner.sync().await
4122        }
4123
4124        async fn start_sync(&self) -> Handle<()> {
4125            self.inner.start_sync().await
4126        }
4127    }
4128
4129    /// Blob wrapper that durably writes a torn extension and its complete incoming footer.
4130    struct TornExtensionBlob<B: Blob> {
4131        inner: B,
4132        writes: Arc<AtomicUsize>,
4133        fail_on: usize,
4134        durable_payload_len: usize,
4135    }
4136
4137    impl<B: Blob> crate::Blob for TornExtensionBlob<B> {
4138        async fn read_at(
4139            &self,
4140            offset: u64,
4141            len: usize,
4142            options: ReadOptions,
4143        ) -> Result<IoBufsMut, Error> {
4144            self.inner.read_at(offset, len, options).await
4145        }
4146
4147        async fn read_at_buf(
4148            &self,
4149            offset: u64,
4150            len: usize,
4151            bufs: impl Into<IoBufsMut> + Send,
4152            options: ReadOptions,
4153        ) -> Result<IoBufsMut, Error> {
4154            self.inner.read_at_buf(offset, len, bufs, options).await
4155        }
4156
4157        async fn write_at(
4158            &self,
4159            offset: u64,
4160            bufs: impl Into<IoBufs> + Send,
4161            options: WriteOptions,
4162        ) -> Result<(), Error> {
4163            let write = self.writes.fetch_add(1, Ordering::SeqCst) + 1;
4164            if write != self.fail_on {
4165                return self.inner.write_at(offset, bufs, options).await;
4166            }
4167
4168            let bytes = bufs.into().coalesce();
4169            let footer_start = bytes
4170                .len()
4171                .checked_sub(CHECKSUM_SIZE as usize)
4172                .expect("physical page must contain a checksum footer");
4173            assert!(self.durable_payload_len <= footer_start);
4174            let footer_offset = offset
4175                .checked_add(footer_start as u64)
4176                .ok_or(Error::OffsetOverflow)?;
4177            let write_options = options.without(WriteOptions::SYNC);
4178
4179            self.inner
4180                .write_at(
4181                    offset,
4182                    bytes.slice(..self.durable_payload_len),
4183                    write_options,
4184                )
4185                .await?;
4186            self.inner
4187                .write_at(footer_offset, bytes.slice(footer_start..), write_options)
4188                .await?;
4189            self.inner.sync().await?;
4190
4191            Err(Error::Io(
4192                std::io::Error::other("injected torn extension").into(),
4193            ))
4194        }
4195
4196        async fn resize(&self, len: u64) -> Result<(), Error> {
4197            self.inner.resize(len).await
4198        }
4199
4200        async fn sync(&self) -> Result<(), Error> {
4201            self.inner.sync().await
4202        }
4203
4204        async fn start_sync(&self) -> Handle<()> {
4205            self.inner.start_sync().await
4206        }
4207    }
4208
4209    #[test_traced("DEBUG")]
4210    fn test_torn_extension_with_new_footer_recovers_previous_prefix() {
4211        let executor = deterministic::Runner::default();
4212        executor.start(|context: deterministic::Context| async move {
4213            let (blob, blob_size) = context
4214                .open("test_partition", b"torn_extension_footer")
4215                .await
4216                .unwrap();
4217            let blob = Arc::new(blob);
4218            let write_count = Arc::new(AtomicUsize::new(0));
4219            let faulty_blob = TornExtensionBlob {
4220                inner: blob.clone(),
4221                writes: write_count.clone(),
4222                fail_on: 2,
4223                durable_payload_len: 4,
4224            };
4225            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4226            let mut writer = Writer::new(faulty_blob, blob_size, BUFFER_SIZE, cache_ref)
4227                .await
4228                .unwrap();
4229
4230            (writer, _) = writer.append(b"abc").await.unwrap();
4231            writer = writer.sync().await.unwrap();
4232            assert_eq!(write_count.load(Ordering::SeqCst), 1);
4233
4234            (writer, _) = writer.append(b"def").await.unwrap();
4235            assert!(writer.sync().await.is_err(), "extension write should fail");
4236            assert_eq!(write_count.load(Ordering::SeqCst), 2);
4237
4238            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4239            let page = blob
4240                .read_at(0, physical_page_size, ReadOptions::default())
4241                .await
4242                .unwrap()
4243                .coalesce();
4244            assert_eq!(&page.as_ref()[..6], b"abcd\0\0");
4245            let checksum = read_crc_record_from_page(page.as_ref());
4246            assert_eq!(checksum.len1, 3);
4247            assert_eq!(checksum.len2, 6);
4248
4249            drop(blob);
4250            let (blob, blob_size) = context
4251                .open("test_partition", b"torn_extension_footer")
4252                .await
4253                .unwrap();
4254            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4255            let recovered = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
4256                .await
4257                .unwrap();
4258            assert_eq!(recovered.size(), 3);
4259
4260            // The protected slot proves exactly the previously committed boundary: the torn
4261            // extension cannot make any later byte part of the recoverable prefix.
4262            assert_eq!(
4263                recovered
4264                    .recoverable_prefix_len(0, NZUsize!(BUFFER_SIZE), ReadOptions::default())
4265                    .await
4266                    .unwrap(),
4267                3
4268            );
4269            let data = recovered.read_at(0, 3).await.unwrap().coalesce();
4270            assert_eq!(data.as_ref(), b"abc");
4271        });
4272    }
4273
4274    /// Blob wrapper that delays one selected read after capturing its current bytes.
4275    struct DelayedReadBlob<B: Blob> {
4276        inner: B,
4277        offset: u64,
4278        len: usize,
4279        reads: AtomicUsize,
4280        started: Mutex<Option<oneshot::Sender<()>>>,
4281        release: Mutex<Option<oneshot::Receiver<()>>>,
4282    }
4283
4284    impl<B: Blob> DelayedReadBlob<B> {
4285        const fn new(
4286            inner: B,
4287            offset: u64,
4288            len: usize,
4289            started: oneshot::Sender<()>,
4290            release: oneshot::Receiver<()>,
4291        ) -> Self {
4292            Self {
4293                inner,
4294                offset,
4295                len,
4296                reads: AtomicUsize::new(0),
4297                started: Mutex::new(Some(started)),
4298                release: Mutex::new(Some(release)),
4299            }
4300        }
4301    }
4302
4303    impl<B: Blob> crate::Blob for DelayedReadBlob<B> {
4304        async fn read_at(
4305            &self,
4306            offset: u64,
4307            len: usize,
4308            options: ReadOptions,
4309        ) -> Result<IoBufsMut, Error> {
4310            if offset == self.offset
4311                && len == self.len
4312                && self.reads.fetch_add(1, Ordering::SeqCst) == 0
4313            {
4314                let bytes = self.inner.read_at(offset, len, options).await?;
4315
4316                let sender = self
4317                    .started
4318                    .lock()
4319                    .take()
4320                    .expect("delayed read start signal consumed more than once");
4321                let _ = sender.send(());
4322
4323                let release = self
4324                    .release
4325                    .lock()
4326                    .take()
4327                    .expect("delayed read release receiver consumed more than once");
4328                release.await.expect("release signal dropped");
4329
4330                return Ok(bytes);
4331            }
4332
4333            self.inner.read_at(offset, len, options).await
4334        }
4335
4336        async fn read_at_buf(
4337            &self,
4338            offset: u64,
4339            len: usize,
4340            bufs: impl Into<IoBufsMut> + Send,
4341            options: ReadOptions,
4342        ) -> Result<IoBufsMut, Error> {
4343            if offset == self.offset
4344                && len == self.len
4345                && self.reads.fetch_add(1, Ordering::SeqCst) == 0
4346            {
4347                let bytes = self.inner.read_at_buf(offset, len, bufs, options).await?;
4348
4349                let sender = self
4350                    .started
4351                    .lock()
4352                    .take()
4353                    .expect("delayed read start signal consumed more than once");
4354                let _ = sender.send(());
4355
4356                let release = self
4357                    .release
4358                    .lock()
4359                    .take()
4360                    .expect("delayed read release receiver consumed more than once");
4361                release.await.expect("release signal dropped");
4362
4363                return Ok(bytes);
4364            }
4365
4366            self.inner.read_at_buf(offset, len, bufs, options).await
4367        }
4368
4369        async fn write_at(
4370            &self,
4371            offset: u64,
4372            bufs: impl Into<IoBufs> + Send,
4373            options: WriteOptions,
4374        ) -> Result<(), Error> {
4375            self.inner.write_at(offset, bufs, options).await
4376        }
4377
4378        async fn resize(&self, len: u64) -> Result<(), Error> {
4379            self.inner.resize(len).await
4380        }
4381
4382        async fn sync(&self) -> Result<(), Error> {
4383            self.inner.sync().await
4384        }
4385
4386        async fn start_sync(&self) -> Handle<()> {
4387            self.inner.start_sync().await
4388        }
4389    }
4390
4391    /// Dummy marker bytes with len=0 so the mangled slot is never authoritative.
4392    /// Format: [len_hi=0, len_lo=0, 0xDE, 0xAD, 0xBE, 0xEF]
4393    const DUMMY_MARKER: [u8; 6] = [0x00, 0x00, 0xDE, 0xAD, 0xBE, 0xEF];
4394
4395    /// Physical encoding retains full-page owners and preserves the first page's durable checksum.
4396    #[rstest::rstest]
4397    #[case(103)]
4398    #[case(4084)]
4399    #[case(4096)]
4400    fn test_to_physical_pages_preserves_chunk_owners(#[case] page_size: u16) {
4401        deterministic::Runner::default().start(|context| async move {
4402            let page_size = NonZeroU16::new(page_size).unwrap();
4403            let cache = CacheRef::new(page_size, NZUsize!(4));
4404            let (blob, size) = context
4405                .open("test_partition", b"physical_chunks")
4406                .await
4407                .unwrap();
4408            let page_size = usize::from(page_size.get());
4409            let capacity = page_size * 32;
4410            let writer = Writer::new(blob, size, capacity, cache).await.unwrap();
4411
4412            // Span several allocations with 17 full pages and a partial tail without flushing.
4413            let data: Vec<_> = (0..page_size * 17 + 17).map(|i| (i % 251) as u8).collect();
4414            let mut buffer = Buffer::from(0, &[], capacity, page_size);
4415            for chunk in data.chunks(page_size) {
4416                assert!(!buffer.append(chunk));
4417            }
4418            assert!(buffer.parts().0.chunk_count() >= 4);
4419
4420            // Record full-page addresses before draining so a payload copy cannot pass unnoticed.
4421            let (prefix, tail) = buffer.parts();
4422            let pointers: Vec<_> = prefix
4423                .iter()
4424                .map(AsRef::as_ref)
4425                .chain(std::iter::once(tail))
4426                .flat_map(|chunk| chunk.chunks_exact(page_size))
4427                .map(|page| page.as_ptr())
4428                .collect();
4429
4430            // Encode two slices per full page and one padded partial page. Keep a durable checksum
4431            // in the first page's second slot, and verify that full-page payload addresses survive.
4432            let full_pages = buffer.drain_full_pages();
4433            let durable = ActiveChecksum::new(Slot::Second, 7, Crc32::checksum(&data[..7]));
4434            let (physical, partial) =
4435                writer.to_physical_pages(&full_pages, buffer.parts().1, true, None, Some(&durable));
4436            assert_eq!(physical.chunk_count(), 17 * 2 + 1);
4437            assert_eq!(partial.unwrap().len, 17);
4438            for (page, ptr) in pointers.into_iter().enumerate() {
4439                assert_eq!(physical.chunk_at(page * 2).unwrap().as_ptr(), ptr);
4440            }
4441
4442            // After the ownership checks, coalesce to validate payload bytes, padding, and CRCs.
4443            // The protected checksum belongs only to the first page.
4444            let physical = physical.coalesce();
4445            let physical_size = page_size + CHECKSUM_SIZE as usize;
4446            for (idx, page) in physical.as_ref().chunks_exact(physical_size).enumerate() {
4447                let logical = &data[idx * page_size..data.len().min((idx + 1) * page_size)];
4448                assert_eq!(&page[..logical.len()], logical);
4449                assert!(page[logical.len()..page_size].iter().all(|byte| *byte == 0));
4450                assert_eq!(
4451                    Checksum::validate_page(page).unwrap().len as usize,
4452                    logical.len()
4453                );
4454                let record = read_crc_record_from_page(page);
4455                if idx == 0 {
4456                    assert_eq!(record.get_slot(Slot::Second), (durable.len, durable.crc));
4457                } else {
4458                    assert_eq!(record.get_slot(Slot::Second), (0, 0));
4459                }
4460            }
4461        });
4462    }
4463
4464    /// Test that slot 1's durable bytes are unchanged when it's the protected slot.
4465    ///
4466    /// Strategy: After extending twice (so slot 1 becomes authoritative with larger len),
4467    /// mangle the non-authoritative slot 0. Then extend again. Slot 0 should be overwritten
4468    /// with the new CRC, while slot 1 (protected) is resubmitted byte-identically.
4469    #[test_traced("DEBUG")]
4470    fn test_crc_slot1_protected() {
4471        let executor = deterministic::Runner::default();
4472        executor.start(|context: deterministic::Context| async move {
4473            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4474            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4475            let slot0_offset = PAGE_SIZE.get() as u64;
4476            let slot1_offset = PAGE_SIZE.get() as u64 + 6;
4477
4478            // Write 10 bytes: slot 0 authoritative (len=10).
4479            let (blob, _) = context.open("test_partition", b"slot1_prot").await.unwrap();
4480            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
4481                .await
4482                .unwrap();
4483            (append, _) = append.append(&(1..=10).collect::<Vec<u8>>()).await.unwrap();
4484            append = append.sync().await.unwrap();
4485            drop(append);
4486
4487            // Extend to 30 bytes: slot 1 authoritative (len=30).
4488            let (blob, size) = context.open("test_partition", b"slot1_prot").await.unwrap();
4489            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4490                .await
4491                .unwrap();
4492            (append, _) = append
4493                .append(&(11..=30).collect::<Vec<u8>>())
4494                .await
4495                .unwrap();
4496            append = append.sync().await.unwrap();
4497            drop(append);
4498
4499            // Verify slot 1 is now authoritative
4500            let (blob, size) = context.open("test_partition", b"slot1_prot").await.unwrap();
4501            let page = blob
4502                .read_at(0, physical_page_size, ReadOptions::default())
4503                .await
4504                .unwrap()
4505                .coalesce();
4506            let crc = read_crc_record_from_page(page.as_ref());
4507            assert!(
4508                crc.len2 > crc.len1,
4509                "Slot 1 should be authoritative (len2={} > len1={})",
4510                crc.len2,
4511                crc.len1
4512            );
4513
4514            // Capture slot 1 bytes before mangling slot 0
4515            let slot1_before: Vec<u8> = blob
4516                .read_at(slot1_offset, 6, ReadOptions::default())
4517                .await
4518                .unwrap()
4519                .coalesce()
4520                .freeze()
4521                .into();
4522
4523            // Mangle slot 0 (non-authoritative).
4524            blob.write_at(slot0_offset, DUMMY_MARKER.to_vec(), WriteOptions::default())
4525                .await
4526                .unwrap();
4527            blob.sync().await.unwrap();
4528
4529            // Verify mangle worked
4530            let slot0_mangled: Vec<u8> = blob
4531                .read_at(slot0_offset, 6, ReadOptions::default())
4532                .await
4533                .unwrap()
4534                .coalesce()
4535                .freeze()
4536                .into();
4537            assert_eq!(slot0_mangled, DUMMY_MARKER, "Mangle failed");
4538
4539            // Extend to 50 bytes: new CRC goes to slot 0, slot 1 protected.
4540            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4541                .await
4542                .unwrap();
4543            (append, _) = append
4544                .append(&(31..=50).collect::<Vec<u8>>())
4545                .await
4546                .unwrap();
4547            append = append.sync().await.unwrap();
4548            drop(append);
4549
4550            // Verify slot 0 was overwritten, slot 1 unchanged.
4551            let (blob, _) = context.open("test_partition", b"slot1_prot").await.unwrap();
4552
4553            // Slot 0 should have new CRC (not our dummy marker)
4554            let slot0_after: Vec<u8> = blob
4555                .read_at(slot0_offset, 6, ReadOptions::default())
4556                .await
4557                .unwrap()
4558                .coalesce()
4559                .freeze()
4560                .into();
4561            assert_ne!(
4562                slot0_after, DUMMY_MARKER,
4563                "Slot 0 should have been overwritten with new CRC"
4564            );
4565
4566            // Slot 1 should be UNCHANGED (protected)
4567            let slot1_after: Vec<u8> = blob
4568                .read_at(slot1_offset, 6, ReadOptions::default())
4569                .await
4570                .unwrap()
4571                .coalesce()
4572                .freeze()
4573                .into();
4574            assert_eq!(
4575                slot1_before, slot1_after,
4576                "Slot 1 was modified! Protected region violated."
4577            );
4578
4579            // Verify the new CRC in slot 0 has len=50
4580            let page = blob
4581                .read_at(0, physical_page_size, ReadOptions::default())
4582                .await
4583                .unwrap()
4584                .coalesce();
4585            let crc = read_crc_record_from_page(page.as_ref());
4586            assert_eq!(crc.len1, 50, "Slot 0 should have len=50");
4587        });
4588    }
4589
4590    /// Test that slot 0's durable bytes are unchanged when it's the protected slot.
4591    ///
4592    /// Strategy: After extending three times (slot 0 becomes authoritative again with largest len),
4593    /// mangle the non-authoritative slot 1. Then extend again. Slot 1 should be overwritten with
4594    /// the new CRC, while slot 0 (protected) is resubmitted byte-identically.
4595    #[test_traced("DEBUG")]
4596    fn test_crc_slot0_protected() {
4597        let executor = deterministic::Runner::default();
4598        executor.start(|context: deterministic::Context| async move {
4599            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4600            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4601            let slot0_offset = PAGE_SIZE.get() as u64;
4602            let slot1_offset = PAGE_SIZE.get() as u64 + 6;
4603
4604            // Write 10 bytes: slot 0 authoritative (len=10).
4605            let (blob, _) = context.open("test_partition", b"slot0_prot").await.unwrap();
4606            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
4607                .await
4608                .unwrap();
4609            (append, _) = append.append(&(1..=10).collect::<Vec<u8>>()).await.unwrap();
4610            append = append.sync().await.unwrap();
4611            drop(append);
4612
4613            // Extend to 30 bytes: slot 1 authoritative (len=30).
4614            let (blob, size) = context.open("test_partition", b"slot0_prot").await.unwrap();
4615            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4616                .await
4617                .unwrap();
4618            (append, _) = append
4619                .append(&(11..=30).collect::<Vec<u8>>())
4620                .await
4621                .unwrap();
4622            append = append.sync().await.unwrap();
4623            drop(append);
4624
4625            // Extend to 50 bytes: slot 0 authoritative (len=50).
4626            let (blob, size) = context.open("test_partition", b"slot0_prot").await.unwrap();
4627            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4628                .await
4629                .unwrap();
4630            (append, _) = append
4631                .append(&(31..=50).collect::<Vec<u8>>())
4632                .await
4633                .unwrap();
4634            append = append.sync().await.unwrap();
4635            drop(append);
4636
4637            // Verify slot 0 is now authoritative
4638            let (blob, size) = context.open("test_partition", b"slot0_prot").await.unwrap();
4639            let page = blob
4640                .read_at(0, physical_page_size, ReadOptions::default())
4641                .await
4642                .unwrap()
4643                .coalesce();
4644            let crc = read_crc_record_from_page(page.as_ref());
4645            assert!(
4646                crc.len1 > crc.len2,
4647                "Slot 0 should be authoritative (len1={} > len2={})",
4648                crc.len1,
4649                crc.len2
4650            );
4651
4652            // Capture slot 0 bytes before mangling slot 1
4653            let slot0_before: Vec<u8> = blob
4654                .read_at(slot0_offset, 6, ReadOptions::default())
4655                .await
4656                .unwrap()
4657                .coalesce()
4658                .freeze()
4659                .into();
4660
4661            // Mangle slot 1 (non-authoritative).
4662            blob.write_at(slot1_offset, DUMMY_MARKER.to_vec(), WriteOptions::default())
4663                .await
4664                .unwrap();
4665            blob.sync().await.unwrap();
4666
4667            // Verify mangle worked
4668            let slot1_mangled: Vec<u8> = blob
4669                .read_at(slot1_offset, 6, ReadOptions::default())
4670                .await
4671                .unwrap()
4672                .coalesce()
4673                .freeze()
4674                .into();
4675            assert_eq!(slot1_mangled, DUMMY_MARKER, "Mangle failed");
4676
4677            // Extend to 70 bytes: new CRC goes to slot 1, slot 0 protected.
4678            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4679                .await
4680                .unwrap();
4681            (append, _) = append
4682                .append(&(51..=70).collect::<Vec<u8>>())
4683                .await
4684                .unwrap();
4685            append = append.sync().await.unwrap();
4686            drop(append);
4687
4688            // Verify slot 1 was overwritten, slot 0 unchanged.
4689            let (blob, _) = context.open("test_partition", b"slot0_prot").await.unwrap();
4690
4691            // Slot 1 should have new CRC (not our dummy marker)
4692            let slot1_after: Vec<u8> = blob
4693                .read_at(slot1_offset, 6, ReadOptions::default())
4694                .await
4695                .unwrap()
4696                .coalesce()
4697                .freeze()
4698                .into();
4699            assert_ne!(
4700                slot1_after, DUMMY_MARKER,
4701                "Slot 1 should have been overwritten with new CRC"
4702            );
4703
4704            // Slot 0 should be UNCHANGED (protected)
4705            let slot0_after: Vec<u8> = blob
4706                .read_at(slot0_offset, 6, ReadOptions::default())
4707                .await
4708                .unwrap()
4709                .coalesce()
4710                .freeze()
4711                .into();
4712            assert_eq!(
4713                slot0_before, slot0_after,
4714                "Slot 0 was modified! Protected region violated."
4715            );
4716
4717            // Verify the new CRC in slot 1 has len=70
4718            let page = blob
4719                .read_at(0, physical_page_size, ReadOptions::default())
4720                .await
4721                .unwrap()
4722                .coalesce();
4723            let crc = read_crc_record_from_page(page.as_ref());
4724            assert_eq!(crc.len2, 70, "Slot 1 should have len=70");
4725        });
4726    }
4727
4728    /// Test that the data prefix content is preserved when extending a partial page: the
4729    /// rewrite resubmits the committed prefix byte-identically.
4730    ///
4731    /// Strategy: Write data, then mangle the padding area (between data end and CRC start).
4732    /// After extending, the original data should be unchanged but the mangled padding
4733    /// should be overwritten with new data.
4734    #[test_traced("DEBUG")]
4735    fn test_data_prefix_preserved_when_extending() {
4736        let executor = deterministic::Runner::default();
4737        executor.start(|context: deterministic::Context| async move {
4738            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4739            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4740
4741            // Write 20 bytes.
4742            let (blob, _) = context
4743                .open("test_partition", b"prefix_test")
4744                .await
4745                .unwrap();
4746            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
4747                .await
4748                .unwrap();
4749            let data1: Vec<u8> = (1..=20).collect();
4750            (append, _) = append.append(&data1).await.unwrap();
4751            append = append.sync().await.unwrap();
4752            drop(append);
4753
4754            // Capture the first 20 bytes and mangle bytes 25-30 (in padding area).
4755            let (blob, size) = context
4756                .open("test_partition", b"prefix_test")
4757                .await
4758                .unwrap();
4759            assert_eq!(size, physical_page_size as u64);
4760
4761            let prefix_before: Vec<u8> = blob
4762                .read_at(0, 20, ReadOptions::default())
4763                .await
4764                .unwrap()
4765                .coalesce()
4766                .freeze()
4767                .into();
4768
4769            // Mangle bytes 25-30 (safely in the padding area, after our 20 bytes of data)
4770            blob.write_at(25, DUMMY_MARKER.to_vec(), WriteOptions::default())
4771                .await
4772                .unwrap();
4773            blob.sync().await.unwrap();
4774
4775            // Extend to 40 bytes.
4776            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4777                .await
4778                .unwrap();
4779            (append, _) = append
4780                .append(&(21..=40).collect::<Vec<u8>>())
4781                .await
4782                .unwrap();
4783            append = append.sync().await.unwrap();
4784            drop(append);
4785
4786            // Verify prefix unchanged, mangled area overwritten.
4787            let (blob, _) = context
4788                .open("test_partition", b"prefix_test")
4789                .await
4790                .unwrap();
4791
4792            // Original 20 bytes should be unchanged
4793            let prefix_after: Vec<u8> = blob
4794                .read_at(0, 20, ReadOptions::default())
4795                .await
4796                .unwrap()
4797                .coalesce()
4798                .freeze()
4799                .into();
4800            assert_eq!(prefix_before, prefix_after, "Data prefix was modified!");
4801
4802            // Bytes at offset 25-30: data (21..=40) starts at offset 20, so offset 25 has value 26
4803            let overwritten: Vec<u8> = blob
4804                .read_at(25, 6, ReadOptions::default())
4805                .await
4806                .unwrap()
4807                .coalesce()
4808                .freeze()
4809                .into();
4810            assert_eq!(
4811                overwritten,
4812                vec![26, 27, 28, 29, 30, 31],
4813                "New data should overwrite padding area"
4814            );
4815        });
4816    }
4817
4818    /// Test CRC slot protection when extending past a page boundary.
4819    ///
4820    /// Strategy: Write partial page, mangle slot 0 (non-authoritative after we do first extend),
4821    /// then extend past page boundary. Verify slot 0 gets new full-page CRC while
4822    /// the mangled marker is overwritten, and second page is written correctly.
4823    #[test_traced("DEBUG")]
4824    fn test_crc_slot_protection_across_page_boundary() {
4825        let executor = deterministic::Runner::default();
4826        executor.start(|context: deterministic::Context| async move {
4827            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4828            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4829            let slot0_offset = PAGE_SIZE.get() as u64;
4830            let slot1_offset = PAGE_SIZE.get() as u64 + 6;
4831
4832            // Write 50 bytes: slot 0 authoritative.
4833            let (blob, _) = context.open("test_partition", b"boundary").await.unwrap();
4834            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
4835                .await
4836                .unwrap();
4837            (append, _) = append.append(&(1..=50).collect::<Vec<u8>>()).await.unwrap();
4838            append = append.sync().await.unwrap();
4839            drop(append);
4840
4841            // Extend to 80 bytes: slot 1 authoritative.
4842            let (blob, size) = context.open("test_partition", b"boundary").await.unwrap();
4843            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4844                .await
4845                .unwrap();
4846            (append, _) = append
4847                .append(&(51..=80).collect::<Vec<u8>>())
4848                .await
4849                .unwrap();
4850            append = append.sync().await.unwrap();
4851            drop(append);
4852
4853            // Verify slot 1 is authoritative
4854            let (blob, size) = context.open("test_partition", b"boundary").await.unwrap();
4855            let page = blob
4856                .read_at(0, physical_page_size, ReadOptions::default())
4857                .await
4858                .unwrap()
4859                .coalesce();
4860            let crc = read_crc_record_from_page(page.as_ref());
4861            assert!(crc.len2 > crc.len1, "Slot 1 should be authoritative");
4862
4863            // Capture slot 1 before extending past page boundary
4864            let slot1_before: Vec<u8> = blob
4865                .read_at(slot1_offset, 6, ReadOptions::default())
4866                .await
4867                .unwrap()
4868                .coalesce()
4869                .freeze()
4870                .into();
4871
4872            // Mangle slot 0 (non-authoritative)
4873            blob.write_at(slot0_offset, DUMMY_MARKER.to_vec(), WriteOptions::default())
4874                .await
4875                .unwrap();
4876            blob.sync().await.unwrap();
4877
4878            // Extend past page boundary (80 + 40 = 120, PAGE_SIZE=103).
4879            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4880                .await
4881                .unwrap();
4882            (append, _) = append
4883                .append(&(81..=120).collect::<Vec<u8>>())
4884                .await
4885                .unwrap();
4886            append = append.sync().await.unwrap();
4887            drop(append);
4888
4889            // Verify results.
4890            let (blob, size) = context.open("test_partition", b"boundary").await.unwrap();
4891            assert_eq!(size, (physical_page_size * 2) as u64, "Should have 2 pages");
4892
4893            // Slot 0 should have been overwritten with full-page CRC (not dummy marker)
4894            let slot0_after: Vec<u8> = blob
4895                .read_at(slot0_offset, 6, ReadOptions::default())
4896                .await
4897                .unwrap()
4898                .coalesce()
4899                .freeze()
4900                .into();
4901            assert_ne!(
4902                slot0_after, DUMMY_MARKER,
4903                "Slot 0 should have full-page CRC"
4904            );
4905
4906            // Slot 1 should be UNCHANGED (protected during boundary crossing)
4907            let slot1_after: Vec<u8> = blob
4908                .read_at(slot1_offset, 6, ReadOptions::default())
4909                .await
4910                .unwrap()
4911                .coalesce()
4912                .freeze()
4913                .into();
4914            assert_eq!(
4915                slot1_before, slot1_after,
4916                "Slot 1 was modified during page boundary crossing!"
4917            );
4918
4919            // Verify page 0 has correct CRC structure
4920            let page0 = blob
4921                .read_at(0, physical_page_size, ReadOptions::default())
4922                .await
4923                .unwrap()
4924                .coalesce();
4925            let crc0 = read_crc_record_from_page(page0.as_ref());
4926            assert_eq!(
4927                crc0.len1,
4928                PAGE_SIZE.get(),
4929                "Slot 0 should have full page length"
4930            );
4931
4932            // Verify data integrity
4933            let append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4934                .await
4935                .unwrap();
4936            assert_eq!(append.size(), 120);
4937            let all_data: Vec<u8> = append.read_at(0, 120).await.unwrap().coalesce().into();
4938            let expected: Vec<u8> = (1..=120).collect();
4939            assert_eq!(all_data, expected);
4940        });
4941    }
4942
4943    /// Test that corrupting the primary CRC (but not its length) causes fallback to the previous
4944    /// partial page contents.
4945    ///
4946    /// Strategy:
4947    /// 1. Write 10 bytes: slot 0 authoritative (len=10, valid crc)
4948    /// 2. Extend to 30 bytes: slot 1 authoritative (len=30, valid crc)
4949    /// 3. Corrupt ONLY the crc2 value in slot 1 (not the length)
4950    /// 4. Re-open and verify we fall back to slot 0's 10 bytes
4951    #[test_traced("DEBUG")]
4952    fn test_crc_fallback_on_corrupted_primary() {
4953        let executor = deterministic::Runner::default();
4954        executor.start(|context: deterministic::Context| async move {
4955            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
4956            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
4957
4958            // crc2 is at offset: PAGE_SIZE + 6 (for len2) + 2 (skip len2 bytes) = PAGE_SIZE + 8
4959            let crc2_offset = PAGE_SIZE.get() as u64 + 8;
4960
4961            // Write 10 bytes: slot 0 authoritative (len=10).
4962            let (blob, _) = context
4963                .open("test_partition", b"crc_fallback")
4964                .await
4965                .unwrap();
4966            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
4967                .await
4968                .unwrap();
4969            let data1: Vec<u8> = (1..=10).collect();
4970            (append, _) = append.append(&data1).await.unwrap();
4971            append = append.sync().await.unwrap();
4972            drop(append);
4973
4974            // Extend to 30 bytes: slot 1 authoritative (len=30).
4975            let (blob, size) = context
4976                .open("test_partition", b"crc_fallback")
4977                .await
4978                .unwrap();
4979            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
4980                .await
4981                .unwrap();
4982            (append, _) = append
4983                .append(&(11..=30).collect::<Vec<u8>>())
4984                .await
4985                .unwrap();
4986            append = append.sync().await.unwrap();
4987            drop(append);
4988
4989            // Verify slot 1 is now authoritative and data reads correctly
4990            let (blob, size) = context
4991                .open("test_partition", b"crc_fallback")
4992                .await
4993                .unwrap();
4994            let blob = Arc::new(blob);
4995            assert_eq!(size, physical_page_size as u64);
4996
4997            let page = blob
4998                .read_at(0, physical_page_size, ReadOptions::default())
4999                .await
5000                .unwrap()
5001                .coalesce();
5002            let crc = read_crc_record_from_page(page.as_ref());
5003            assert!(
5004                crc.len2 > crc.len1,
5005                "Slot 1 should be authoritative (len2={} > len1={})",
5006                crc.len2,
5007                crc.len1
5008            );
5009            assert_eq!(crc.len2, 30, "Slot 1 should have len=30");
5010            assert_eq!(crc.len1, 10, "Slot 0 should have len=10");
5011
5012            // Verify we can read all 30 bytes before corruption
5013            let append = Writer::new(blob.clone(), size, BUFFER_SIZE, cache_ref.clone())
5014                .await
5015                .unwrap();
5016            assert_eq!(append.size(), 30);
5017            let all_data: Vec<u8> = append.read_at(0, 30).await.unwrap().coalesce().into();
5018            let expected: Vec<u8> = (1..=30).collect();
5019            assert_eq!(all_data, expected);
5020            drop(append);
5021
5022            // Corrupt ONLY crc2 (not len2).
5023            // crc2 is 4 bytes at offset PAGE_SIZE + 8
5024            blob.write_at(
5025                crc2_offset,
5026                vec![0xDE, 0xAD, 0xBE, 0xEF],
5027                WriteOptions::default(),
5028            )
5029            .await
5030            .unwrap();
5031            blob.sync().await.unwrap();
5032
5033            // Verify corruption: len2 should still be 30, but crc2 is now garbage
5034            let page = blob
5035                .read_at(0, physical_page_size, ReadOptions::default())
5036                .await
5037                .unwrap()
5038                .coalesce();
5039            let crc = read_crc_record_from_page(page.as_ref());
5040            assert_eq!(crc.len2, 30, "len2 should still be 30 after corruption");
5041            assert_eq!(crc.crc2, 0xDEADBEEF, "crc2 should be our corrupted value");
5042
5043            // Re-open and verify fallback to slot 0's 10 bytes.
5044            let append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
5045                .await
5046                .unwrap();
5047
5048            // Should fall back to 10 bytes (slot 0's length)
5049            assert_eq!(
5050                append.size(),
5051                10,
5052                "Should fall back to slot 0's 10 bytes after primary CRC corruption"
5053            );
5054
5055            // Verify the data is the original 10 bytes
5056            let fallback_data: Vec<u8> = append.read_at(0, 10).await.unwrap().coalesce().into();
5057            assert_eq!(
5058                fallback_data, data1,
5059                "Fallback data should match original 10 bytes"
5060            );
5061
5062            // Reading beyond 10 bytes should fail
5063            let result = append.read_at(0, 11).await;
5064            assert!(result.is_err(), "Reading beyond fallback size should fail");
5065        });
5066    }
5067
5068    /// Test that corrupting a non-last page's primary CRC fails even if fallback is valid.
5069    ///
5070    /// Non-last pages must always be full. If the primary CRC is corrupted and the fallback
5071    /// indicates a partial page, validation should fail entirely (not fall back to partial).
5072    ///
5073    /// Strategy:
5074    /// 1. Write 10 bytes: slot 0 has len=10 (partial)
5075    /// 2. Extend to full page (103 bytes): slot 1 has len=103 (full, authoritative)
5076    /// 3. Extend past page boundary (e.g., 110 bytes): page 0 is now non-last
5077    /// 4. Corrupt the primary CRC of page 0 (slot 1's crc, which has len=103)
5078    /// 5. Re-open and verify that reading from page 0 fails (fallback has len=10, not full)
5079    #[test_traced("DEBUG")]
5080    fn test_non_last_page_rejects_partial_fallback() {
5081        let executor = deterministic::Runner::default();
5082        executor.start(|context: deterministic::Context| async move {
5083            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5084            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
5085
5086            // crc2 for page 0 is at offset: PAGE_SIZE + 8
5087            let page0_crc2_offset = PAGE_SIZE.get() as u64 + 8;
5088
5089            // Write 10 bytes: slot 0 has len=10.
5090            let (blob, _) = context
5091                .open("test_partition", b"non_last_page")
5092                .await
5093                .unwrap();
5094            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
5095                .await
5096                .unwrap();
5097            (append, _) = append.append(&(1..=10).collect::<Vec<u8>>()).await.unwrap();
5098            append = append.sync().await.unwrap();
5099            drop(append);
5100
5101            // Extend to exactly full page (103 bytes): slot 1 has len=103.
5102            let (blob, size) = context
5103                .open("test_partition", b"non_last_page")
5104                .await
5105                .unwrap();
5106            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
5107                .await
5108                .unwrap();
5109            // Add bytes 11 through 103 (93 more bytes)
5110            (append, _) = append
5111                .append(&(11..=PAGE_SIZE.get() as u8).collect::<Vec<u8>>())
5112                .await
5113                .unwrap();
5114            append = append.sync().await.unwrap();
5115            drop(append);
5116
5117            // Verify page 0 slot 1 is authoritative with len=103 (full page)
5118            let (blob, size) = context
5119                .open("test_partition", b"non_last_page")
5120                .await
5121                .unwrap();
5122            let page = blob
5123                .read_at(0, physical_page_size, ReadOptions::default())
5124                .await
5125                .unwrap()
5126                .coalesce();
5127            let crc = read_crc_record_from_page(page.as_ref());
5128            assert_eq!(crc.len1, 10, "Slot 0 should have len=10");
5129            assert_eq!(
5130                crc.len2,
5131                PAGE_SIZE.get(),
5132                "Slot 1 should have len=103 (full page)"
5133            );
5134            assert!(crc.len2 > crc.len1, "Slot 1 should be authoritative");
5135
5136            // Extend past page boundary (add 10 more bytes for total of 113).
5137            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
5138                .await
5139                .unwrap();
5140            // Add bytes 104 through 113 (10 more bytes, now on page 1)
5141            (append, _) = append
5142                .append(&(104..=113).collect::<Vec<u8>>())
5143                .await
5144                .unwrap();
5145            append = append.sync().await.unwrap();
5146            drop(append);
5147
5148            // Verify we now have 2 pages
5149            let (blob, size) = context
5150                .open("test_partition", b"non_last_page")
5151                .await
5152                .unwrap();
5153            let blob = Arc::new(blob);
5154            assert_eq!(
5155                size,
5156                (physical_page_size * 2) as u64,
5157                "Should have 2 physical pages"
5158            );
5159
5160            // Verify data is readable before corruption
5161            let append = Writer::new(blob.clone(), size, BUFFER_SIZE, cache_ref.clone())
5162                .await
5163                .unwrap();
5164            assert_eq!(append.size(), 113);
5165            let all_data: Vec<u8> = append.read_at(0, 113).await.unwrap().coalesce().into();
5166            let expected: Vec<u8> = (1..=113).collect();
5167            assert_eq!(all_data, expected);
5168            drop(append);
5169
5170            // Corrupt page 0's primary CRC (slot 1's crc2).
5171            blob.write_at(
5172                page0_crc2_offset,
5173                vec![0xDE, 0xAD, 0xBE, 0xEF],
5174                WriteOptions::default(),
5175            )
5176            .await
5177            .unwrap();
5178            blob.sync().await.unwrap();
5179
5180            // Verify corruption: page 0's slot 1 still has len=103 but bad CRC
5181            let page = blob
5182                .read_at(0, physical_page_size, ReadOptions::default())
5183                .await
5184                .unwrap()
5185                .coalesce();
5186            let crc = read_crc_record_from_page(page.as_ref());
5187            assert_eq!(crc.len2, PAGE_SIZE.get(), "len2 should still be 103");
5188            assert_eq!(crc.crc2, 0xDEADBEEF, "crc2 should be corrupted");
5189            // Slot 0 fallback has len=10 (partial), which is invalid for non-last page
5190            assert_eq!(crc.len1, 10, "Fallback slot 0 has partial length");
5191
5192            // Re-open and try to read from page 0.
5193            // The first page's primary CRC is bad, and fallback indicates partial (len=10).
5194            // Since page 0 is not the last page, a partial fallback is invalid.
5195            // Reading from page 0 should fail because the fallback CRC indicates a partial
5196            // page, which is not allowed for non-last pages.
5197            let append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
5198                .await
5199                .unwrap();
5200
5201            // The blob still reports 113 bytes because init only validates the last page.
5202            // But reading from page 0 should fail because the CRC fallback is partial.
5203            assert_eq!(append.size(), 113);
5204
5205            // Reading from page 0 should fail with InvalidChecksum because the fallback CRC has
5206            // len=10 (partial), which is invalid for a non-last page.
5207            let result = append.read_at(0, 10).await;
5208            assert!(
5209                result.is_err(),
5210                "Reading from corrupted non-last page via Append should fail, but got: {:?}",
5211                result
5212            );
5213            drop(append);
5214
5215            // Also verify that reading via Replay fails the same way.
5216            let (blob, size) = context
5217                .open("test_partition", b"non_last_page")
5218                .await
5219                .unwrap();
5220            let append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
5221                .await
5222                .unwrap();
5223            let (_, mut replay) = append
5224                .replay(NZUsize!(1024), ReadOptions::default())
5225                .await
5226                .unwrap();
5227
5228            // Filling pages should fail on CRC validation.
5229            let result = replay.ensure(1).await;
5230            assert!(
5231                result.is_err(),
5232                "Reading from corrupted non-last page via Replay should fail, but got: {:?}",
5233                result
5234            );
5235        });
5236    }
5237
5238    /// A crash can cut a flush so that the pages after a filled page persist while that page
5239    /// keeps only its earlier, shorter checksum slot. A replay fails the fill that reaches that
5240    /// page with [Error::InvalidChecksum], and so does a fill after seeking into it. While the
5241    /// full-page slot persisted, the replay yields every byte.
5242    #[test]
5243    fn test_replay_rejects_short_interior_page() {
5244        let executor = deterministic::Runner::default();
5245        executor.start(|context: deterministic::Context| async move {
5246            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5247            let page_size: u64 = PAGE_SIZE.widen();
5248
5249            // Page 0 keeps a 10-byte slot from its partial era and a full-page slot once it
5250            // fills. Page 1 holds the final 10 bytes, so page 0 is an interior page.
5251            let (blob, _) = context
5252                .open("test_partition", b"short_bound")
5253                .await
5254                .unwrap();
5255            let mut append = Writer::new(blob, 0, BUFFER_SIZE, cache_ref.clone())
5256                .await
5257                .unwrap();
5258            (append, _) = append.append(&(1..=10).collect::<Vec<u8>>()).await.unwrap();
5259            append = append.sync().await.unwrap();
5260            (append, _) = append
5261                .append(&(11..=113).collect::<Vec<u8>>())
5262                .await
5263                .unwrap();
5264            append = append.sync().await.unwrap();
5265            drop(append);
5266
5267            let (blob, size) = context
5268                .open("test_partition", b"short_bound")
5269                .await
5270                .unwrap();
5271            let blob = Arc::new(blob);
5272
5273            // While the full-page slot persisted, the replay yields every byte.
5274            let append = Writer::new(blob.clone(), size, BUFFER_SIZE, cache_ref.clone())
5275                .await
5276                .unwrap();
5277            let (_, mut replay) = append
5278                .replay(NZUsize!(1024), ReadOptions::default())
5279                .await
5280                .unwrap();
5281            assert!(replay.ensure(113).await.unwrap());
5282            assert_eq!(replay.remaining(), 113);
5283            assert_eq!(
5284                replay.copy_to_bytes(113).as_ref(),
5285                (1..=113).collect::<Vec<u8>>()
5286            );
5287            drop(replay);
5288
5289            // Model the crash cut that persisted page 1 but not page 0's full-page slot: overwrite
5290            // that slot's CRC so page 0 validates only through its 10-byte slot.
5291            let page = blob
5292                .read_at(
5293                    0,
5294                    usize::from(PAGE_SIZE.get()) + CHECKSUM_SIZE as usize,
5295                    ReadOptions::default(),
5296                )
5297                .await
5298                .unwrap()
5299                .coalesce();
5300            let crc = read_crc_record_from_page(page.as_ref());
5301            assert_eq!((crc.len1, crc.len2), (10, PAGE_SIZE.get()));
5302            blob.write_at(
5303                page_size + 8,
5304                vec![0xDE, 0xAD, 0xBE, 0xEF],
5305                WriteOptions::default(),
5306            )
5307            .await
5308            .unwrap();
5309            blob.sync().await.unwrap();
5310
5311            // Page 0 is an interior page that validates only 10 of its bytes.
5312            let append = Writer::new(blob, size, BUFFER_SIZE, cache_ref)
5313                .await
5314                .unwrap();
5315            assert_eq!(append.size(), 113);
5316            let (_, mut replay) = append
5317                .replay(NZUsize!(1024), ReadOptions::default())
5318                .await
5319                .unwrap();
5320            assert_eq!(replay.blob_size(), 113);
5321            assert!(
5322                matches!(replay.ensure(50).await, Err(Error::InvalidChecksum)),
5323                "an interior page covering fewer bytes than a page must fail validation"
5324            );
5325
5326            // A fill after seeking past the surviving slot's bytes fails the same way.
5327            replay.seek_to(40).unwrap();
5328            assert!(matches!(
5329                replay.ensure(1).await,
5330                Err(Error::InvalidChecksum)
5331            ));
5332            assert!(replay.chunk().is_empty());
5333            assert_eq!(replay.remaining(), 0);
5334        });
5335    }
5336
5337    #[test]
5338    fn test_recovery_truncate_partial_shrink_uses_uncached_read_hint() {
5339        let executor = deterministic::Runner::default();
5340        executor.start(|context| async move {
5341            let (blob, size) = context
5342                .open("test_partition", b"resize_read_options")
5343                .await
5344                .unwrap();
5345            let blob = PartialWriteBlob::new(blob, usize::MAX, 0);
5346            let read_options = blob.read_options();
5347            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5348            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
5349                .await
5350                .unwrap();
5351
5352            let data = vec![7; PAGE_SIZE.get() as usize];
5353            (writer, _) = writer.append(&data).await.unwrap();
5354            writer = writer.sync().await.unwrap();
5355
5356            // The shrink retains the prefix in the in-memory tip, so its backing read requests
5357            // DONT_CACHE.
5358            writer.truncate(50).await.unwrap();
5359
5360            assert_eq!(*read_options.lock(), vec![ReadOptions::DONT_CACHE]);
5361        });
5362    }
5363
5364    #[test]
5365    fn test_recovery_truncate_shrink_validates_crc() {
5366        // Verify that shrinking a blob to a partial page validates the CRC, rather than
5367        // blindly reading raw bytes which could silently load corrupted data.
5368        let executor = deterministic::Runner::default();
5369        executor.start(|context| async move {
5370            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5371            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
5372
5373            let (blob, size) = context
5374                .open("test_partition", b"resize_crc_test")
5375                .await
5376                .unwrap();
5377
5378            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5379                .await
5380                .unwrap();
5381
5382            // Write two full pages and one partial page.
5383            // PAGE_SIZE = 103, so 250 bytes = 103 + 103 + 44.
5384            let data: Vec<u8> = (0..=249).collect();
5385            (append, _) = append.append(&data).await.unwrap();
5386            append = append.sync().await.unwrap();
5387            assert_eq!(append.size(), 250);
5388            drop(append);
5389
5390            // Corrupt the CRC record of page 1 (middle page).
5391            let (blob, size) = context
5392                .open("test_partition", b"resize_crc_test")
5393                .await
5394                .unwrap();
5395            assert_eq!(size as usize, physical_page_size * 3);
5396
5397            // Page 1 CRC record is at the end of the second physical page.
5398            let page1_crc_offset = (physical_page_size * 2 - CHECKSUM_SIZE as usize) as u64;
5399            blob.write_at(
5400                page1_crc_offset,
5401                vec![0xFF; CHECKSUM_SIZE as usize],
5402                WriteOptions::default(),
5403            )
5404            .await
5405            .unwrap();
5406            blob.sync().await.unwrap();
5407
5408            // Recovery validates only the terminal page. Truncation discovers page 1 corruption.
5409            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5410                .await
5411                .unwrap();
5412            assert_eq!(append.size(), 250);
5413
5414            // Try to shrink to 150 bytes, which ends in page 1 (the corrupted page).
5415            // 150 bytes = page 0 (103 full) + page 1 (47 partial).
5416            // This should fail because page 1's CRC is corrupted.
5417            let result = append.truncate(150).await.err();
5418            assert!(
5419                matches!(result, Some(crate::Error::InvalidChecksum)),
5420                "Expected InvalidChecksum when shrinking to corrupted page, got: {:?}",
5421                result
5422            );
5423        });
5424    }
5425
5426    #[test]
5427    fn test_recovery_preserves_cached_prefix_on_publication() {
5428        // Exercise publication with an unchanged tail and with two shorter retained prefixes.
5429        let page = PAGE_SIZE.get() as u64;
5430        for end in [None, Some(page * 2 + 10), Some(page + 10)] {
5431            deterministic::Runner::default().start(|context| async move {
5432                // Persist several pages and prime the first page in the recovery cache.
5433                let cache = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5434                let (blob, size) = context.open("recovery-cache", b"blob").await.unwrap();
5435                let mut recovery = Recovery::open(blob, size, BUFFER_SIZE, cache)
5436                    .await
5437                    .unwrap();
5438                let page = PAGE_SIZE.get() as usize;
5439                (recovery, _) = recovery.append(&vec![0xA5; page * 2 + 20]).await.unwrap();
5440                recovery = recovery.sync().await.unwrap();
5441                recovery.read_at(0, page).await.unwrap();
5442
5443                // Shortening the tail must leave the retained first page cached.
5444                if let Some(end) = end {
5445                    recovery = recovery.truncate(end).await.unwrap();
5446                }
5447
5448                // Publishing the append owner keeps the retained cache available.
5449                let writer: Writer<_> = recovery.into();
5450                let mut cached = vec![0; page];
5451                assert!(writer.try_read_sync_into(&mut cached, 0));
5452                assert_eq!(cached, vec![0xA5; page]);
5453            });
5454        }
5455    }
5456
5457    #[test]
5458    fn test_recovery_truncate_direct_append_replaces_cached_pages() {
5459        deterministic::Runner::default().start(|context| async move {
5460            // Persist a prefix and cache pages that the replacement will overlap.
5461            let cache = CacheRef::new(PAGE_SIZE, NZUsize!(2));
5462            let (blob, size) = context.open("recovery-cache", b"direct").await.unwrap();
5463            let mut recovery = Recovery::open(blob, size, BUFFER_SIZE, cache.clone())
5464                .await
5465                .unwrap();
5466            let page = PAGE_SIZE.get() as usize;
5467            let mut model: Vec<u8> = (0..5 * page + 20).map(|i| (i % 251) as u8).collect();
5468            (recovery, _) = recovery.append(&model).await.unwrap();
5469            recovery = recovery.sync().await.unwrap();
5470            cache.clear();
5471            recovery.read_at(page as u64, page).await.unwrap();
5472            recovery.read_at((2 * page) as u64, page).await.unwrap();
5473
5474            // Shorten into a cached page, then bypass the buffer with a multi-page replacement.
5475            recovery = recovery.truncate((page + 10) as u64).await.unwrap();
5476            model.truncate(page + 10);
5477            let replacement = vec![0xCC; 3 * page + 7];
5478            (recovery, _) = recovery
5479                .append_owned(replacement.clone().into())
5480                .await
5481                .unwrap();
5482            model.extend_from_slice(&replacement);
5483
5484            // Reads must use replacement bytes rather than the discarded cached suffix.
5485            assert_eq!(
5486                recovery
5487                    .read_at((2 * page) as u64, page)
5488                    .await
5489                    .unwrap()
5490                    .coalesce()
5491                    .as_ref(),
5492                &model[2 * page..3 * page]
5493            );
5494            assert_eq!(
5495                recovery
5496                    .read_at(0, model.len())
5497                    .await
5498                    .unwrap()
5499                    .coalesce()
5500                    .as_ref(),
5501                model
5502            );
5503            recovery = recovery.sync().await.unwrap();
5504
5505            // A published snapshot retains its prefix while later appends extend the live writer.
5506            let writer: Writer<_> = recovery.into();
5507            let (mut writer, snapshot) = writer.snapshot().await.unwrap();
5508            (writer, _) = writer.append(&vec![0xDD; page - 17]).await.unwrap();
5509            writer = writer.sync().await.unwrap();
5510            assert_eq!(
5511                snapshot
5512                    .read_at(0, model.len())
5513                    .await
5514                    .unwrap()
5515                    .coalesce()
5516                    .as_ref(),
5517                model
5518            );
5519            model.extend_from_slice(&vec![0xDD; page - 17]);
5520            assert_eq!(
5521                writer
5522                    .read_at(0, model.len())
5523                    .await
5524                    .unwrap()
5525                    .coalesce()
5526                    .as_ref(),
5527                model
5528            );
5529        });
5530    }
5531
5532    #[test]
5533    fn test_cancelled_recovery_read_cannot_repopulate_after_truncate() {
5534        let cfg =
5535            deterministic::Config::default().with_timeout(Some(std::time::Duration::from_secs(5)));
5536        deterministic::Runner::new(cfg).start(|context| async move {
5537            // Park a read of the second page after it has captured the persisted bytes.
5538            let page = PAGE_SIZE.get() as usize;
5539            let physical = page + CHECKSUM_SIZE as usize;
5540            let cache = CacheRef::new(PAGE_SIZE, NZUsize!(1));
5541            let (inner, size) = context.open("recovery-cache", b"cancelled").await.unwrap();
5542            let (started_tx, started_rx) = oneshot::channel();
5543            let (release_tx, release_rx) = oneshot::channel();
5544            let blob =
5545                DelayedReadBlob::new(inner, physical as u64, physical, started_tx, release_rx);
5546            let mut recovery = Recovery::open(blob, size, BUFFER_SIZE, cache.clone())
5547                .await
5548                .unwrap();
5549            (recovery, _) = recovery.append(&vec![0xAA; 3 * page + 20]).await.unwrap();
5550            recovery = recovery.sync().await.unwrap();
5551            cache.clear();
5552
5553            // Drop the parked read before replacing its source page, cancelling its cache
5554            // publication.
5555            {
5556                let mut read = Box::pin(recovery.read_at(page as u64, page));
5557                commonware_macros::select! {
5558                    _ = started_rx => {},
5559                    _ = read.as_mut() => panic!("read completed before release"),
5560                }
5561            }
5562
5563            // Replace the discarded suffix and evict its page from the single-page cache.
5564            recovery = recovery.truncate((page + 10) as u64).await.unwrap();
5565            (recovery, _) = recovery.append(&vec![0xBB; page - 10]).await.unwrap();
5566            recovery = recovery.sync().await.unwrap();
5567            recovery.read_at(0, page).await.unwrap();
5568
5569            // Releasing the abandoned read must not restore old bytes to the cache.
5570            let _ = release_tx.send(());
5571            let actual = recovery
5572                .read_at(page as u64, page)
5573                .await
5574                .unwrap()
5575                .coalesce();
5576            assert_eq!(&actual.as_ref()[..10], &[0xAA; 10]);
5577            assert_eq!(&actual.as_ref()[10..], vec![0xBB; page - 10]);
5578        });
5579    }
5580
5581    #[test]
5582    fn test_recovery_truncate_replaces_cached_tail() {
5583        deterministic::Runner::default().start(|context| async move {
5584            let cache = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5585            let (blob, size) = context.open("recovery-cache", b"truncate").await.unwrap();
5586            let mut recovery = Recovery::open(blob, size, BUFFER_SIZE, cache)
5587                .await
5588                .unwrap();
5589            let page = PAGE_SIZE.get() as usize;
5590            (recovery, _) = recovery.append(&vec![0xAA; page * 2 + 16]).await.unwrap();
5591            recovery = recovery.sync().await.unwrap();
5592            recovery.read_at(0, page * 2).await.unwrap();
5593            let mut cached = vec![0; page * 2];
5594            assert!(recovery.try_read_sync_into(&mut cached, 0));
5595            assert_eq!(cached, vec![0xAA; page * 2]);
5596
5597            recovery = recovery.truncate((page + 16) as u64).await.unwrap();
5598            recovery.read_at(0, page).await.unwrap();
5599            recovery = recovery.truncate((page + 8) as u64).await.unwrap();
5600            assert!(recovery.try_read_sync_into(&mut cached[..page], 0));
5601
5602            (recovery, _) = recovery.append(&vec![0xBB; page - 8]).await.unwrap();
5603            recovery = recovery.sync().await.unwrap();
5604
5605            // Page 1 is now full, so this read exercises cached bytes rather than the tip.
5606            let mut rewritten = vec![0; page];
5607            assert!(recovery.try_read_sync_into(&mut rewritten, page as u64));
5608            assert_eq!(&rewritten[..8], &[0xAA; 8]);
5609            assert_eq!(&rewritten[8..], vec![0xBB; page - 8]);
5610        });
5611    }
5612
5613    #[test]
5614    fn test_snapshot_fetch_populates_shared_cache_across_append() {
5615        let executor = deterministic::Runner::default();
5616        executor.start(|context: deterministic::Context| async move {
5617            // Delay a snapshot read of the second persisted page until after a later append.
5618            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5619            let page_size = PAGE_SIZE.get() as usize;
5620            let physical_page_size = page_size + CHECKSUM_SIZE as usize;
5621            let (inner, blob_size) = context
5622                .open("test_partition", b"snapshot_resize_cache")
5623                .await
5624                .unwrap();
5625            let (started_tx, started_rx) = oneshot::channel();
5626            let (release_tx, release_rx) = oneshot::channel();
5627            let blob = DelayedReadBlob::new(
5628                inner,
5629                physical_page_size as u64,
5630                physical_page_size,
5631                started_tx,
5632                release_rx,
5633            );
5634            let mut writer = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
5635                .await
5636                .unwrap();
5637
5638            // Create two immutable pages that both the writer and snapshot can cache.
5639            let old_page0 = vec![0x11u8; page_size];
5640            let old_page1 = vec![0x22u8; page_size];
5641            (writer, _) = writer.append(&old_page0).await.unwrap();
5642            (writer, _) = writer.append(&old_page1).await.unwrap();
5643            writer = writer.sync().await.unwrap();
5644
5645            writer.cache_ref.clear();
5646
5647            // Start a cache miss through the snapshot and park the captured read.
5648            let (mut writer, snapshot) = writer.snapshot().await.unwrap();
5649            let snapshot_task = context
5650                .child("snapshot")
5651                .spawn(move |_| async move { snapshot.read_at(page_size as u64, page_size).await });
5652            started_rx.await.expect("snapshot read never started");
5653
5654            // Append another page while the snapshot still owns its earlier view.
5655            let new_page1 = vec![0x33u8; page_size];
5656            (writer, _) = writer.append(&new_page1).await.unwrap();
5657            writer = writer.sync().await.unwrap();
5658
5659            // Finish the snapshot read and verify it fills the cache shared with the writer.
5660            let _ = release_tx.send(());
5661            let stale = snapshot_task
5662                .await
5663                .expect("snapshot task failed")
5664                .expect("snapshot read failed")
5665                .coalesce();
5666            assert_eq!(stale.as_ref(), old_page1.as_slice());
5667
5668            let mut probe = vec![0u8; page_size];
5669            assert!(writer.try_read_sync_into(&mut probe, page_size as u64));
5670            assert_eq!(probe, old_page1);
5671        });
5672    }
5673
5674    #[test]
5675    fn test_append_preserves_snapshot_partial_page() {
5676        let executor = deterministic::Runner::default();
5677        executor.start(|context: deterministic::Context| async move {
5678            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5679            let (blob, blob_size) = context
5680                .open("test_partition", b"snapshot_blocks_shrink")
5681                .await
5682                .unwrap();
5683            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
5684                .await
5685                .unwrap();
5686
5687            let page_size = PAGE_SIZE.get() as usize;
5688            let data: Vec<u8> = (0u8..=255).cycle().take(page_size * 2 + 7).collect();
5689            (append, _) = append.append(&data).await.unwrap();
5690            append = append.sync().await.unwrap();
5691
5692            let tail_ptr = append.buffer.parts().1.as_ptr();
5693            let (mut append, snapshot) = append.snapshot().await.unwrap();
5694            let snapshot_clone = snapshot.clone();
5695            let snapshot_size = snapshot.size();
5696
5697            let read = snapshot.read_at(0, data.len()).await.unwrap().coalesce();
5698            assert_eq!(read.as_ref(), data.as_slice());
5699
5700            // The snapshot owns a copied partial page, so appends can reuse the writer's unique
5701            // tail while the snapshot continues serving its original bytes.
5702            (append, _) = append.append(&[0; 3]).await.unwrap();
5703            assert_eq!(append.size(), snapshot_size + 3);
5704            assert_eq!(append.buffer.parts().1.as_ptr(), tail_ptr);
5705
5706            let original = snapshot_clone
5707                .read_at(0, data.len())
5708                .await
5709                .unwrap()
5710                .coalesce();
5711            assert_eq!(original.as_ref(), data.as_slice());
5712            assert_eq!(snapshot_clone.size(), snapshot_size);
5713        });
5714    }
5715
5716    #[test]
5717    fn test_snapshot_read_many_into_matches_read_at() {
5718        let executor = deterministic::Runner::default();
5719        executor.start(|context: deterministic::Context| async move {
5720            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5721            let (blob, blob_size) = context
5722                .open("test_partition", b"snapshot_read_many")
5723                .await
5724                .unwrap();
5725            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
5726                .await
5727                .unwrap();
5728
5729            let item_size = 4;
5730            let page_size = PAGE_SIZE.get() as usize;
5731            let total = page_size * 3 + 13;
5732            let data: Vec<u8> = (0u8..=255).cycle().take(total).collect();
5733            (append, _) = append.append(&data).await.unwrap();
5734            append = append.sync().await.unwrap();
5735
5736            let (_, snapshot) = append.snapshot().await.unwrap();
5737
5738            // Batch reads cover page starts, page ends, page interiors, and the frozen tail.
5739            let offsets = [
5740                0,
5741                (page_size - item_size) as u64,
5742                (page_size + 5) as u64,
5743                (page_size * 3 + 2) as u64,
5744            ];
5745            let mut batch = vec![0u8; offsets.len() * item_size];
5746            snapshot
5747                .read_many_into(&mut batch, &offsets, NZUsize!(item_size))
5748                .await
5749                .unwrap();
5750
5751            for (item, offset) in batch.chunks_exact(item_size).zip(offsets) {
5752                let single = snapshot
5753                    .read_at(offset, item_size)
5754                    .await
5755                    .unwrap()
5756                    .coalesce();
5757                assert_eq!(item, single.as_ref());
5758                assert_eq!(item, &data[offset as usize..offset as usize + item_size]);
5759            }
5760        });
5761    }
5762
5763    #[test]
5764    fn test_snapshot_try_read_sync_prefers_snapshot_tail() {
5765        let executor = deterministic::Runner::default();
5766        executor.start(|context: deterministic::Context| async move {
5767            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5768            let (blob, blob_size) = context
5769                .open("test_partition", b"snapshot_try_read_tail")
5770                .await
5771                .unwrap();
5772            let mut append = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
5773                .await
5774                .unwrap();
5775
5776            let page_size = PAGE_SIZE.get() as usize;
5777            (append, _) = append.append(&vec![0xAA; page_size]).await.unwrap();
5778            append = append.sync().await.unwrap();
5779
5780            let tail = b"oldtail";
5781            (append, _) = append.append(tail).await.unwrap();
5782            let (append, snapshot) = append.snapshot().await.unwrap();
5783
5784            // Stale cached bytes must not replace the snapshot's owned partial tail.
5785            let poison = vec![0xBB; page_size];
5786            assert_eq!(
5787                append.cache_ref.cache(append.id, &poison, page_size as u64),
5788                0
5789            );
5790
5791            let mut read = vec![0; tail.len()];
5792            assert!(snapshot.try_read_sync_into(&mut read, page_size as u64));
5793            assert_eq!(read.as_slice(), tail);
5794        });
5795    }
5796
5797    #[test]
5798    fn test_recovery_truncate_same_size_preserves_contents() {
5799        let executor = deterministic::Runner::default();
5800        executor.start(|context: deterministic::Context| async move {
5801            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5802            let (blob, blob_size) = context
5803                .open("test_partition", b"resize_same_size")
5804                .await
5805                .unwrap();
5806            let mut append = Recovery::open(blob, blob_size, BUFFER_SIZE, cache_ref)
5807                .await
5808                .unwrap();
5809
5810            (append, _) = append.append(b"hello world").await.unwrap();
5811            assert_eq!(append.size(), 11);
5812
5813            // Truncating at the existing end preserves the contents.
5814            append = append.truncate(11).await.unwrap();
5815            assert_eq!(append.size(), 11);
5816
5817            // Verify content is still readable and intact.
5818            let read = append.read_at(0, 11).await.unwrap().coalesce();
5819            assert_eq!(read.as_ref(), b"hello world");
5820        });
5821    }
5822
5823    #[test]
5824    fn test_recovery_truncate_same_page_shrink_reopens_at_shorter_size() {
5825        let executor = deterministic::Runner::default();
5826        executor.start(|context| async move {
5827            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5828            let data: Vec<u8> = (0..50).collect();
5829
5830            let (blob, size) = context
5831                .open("test_partition", b"same_page_shrink")
5832                .await
5833                .unwrap();
5834            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5835                .await
5836                .unwrap();
5837
5838            // Create a partial page whose authoritative checksum is in the first slot.
5839            (append, _) = append.append(&data).await.unwrap();
5840            append = append.sync().await.unwrap();
5841
5842            // Durably shorten within the page and release the writer before recovery.
5843            append = append.truncate(45).await.unwrap();
5844            drop(append);
5845
5846            // A fresh recovery must select the shorter checksum and return its exact prefix.
5847            let (blob, size) = context
5848                .open("test_partition", b"same_page_shrink")
5849                .await
5850                .unwrap();
5851            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
5852                .await
5853                .unwrap();
5854            assert_eq!(append.size(), 45);
5855            let read = append.read_at(0, 45).await.unwrap().coalesce();
5856            assert_eq!(read.as_ref(), &data[..45]);
5857        });
5858    }
5859
5860    /// A torn tail-page rewrite after a durable shrink must not resurrect the retired slot:
5861    /// the shrink zeroes the whole slot, so stale length bytes alone cannot reassemble a valid
5862    /// checksum over the pre-shrink bytes still on the page.
5863    #[test_traced("DEBUG")]
5864    fn test_shrink_then_torn_rewrite_does_not_resurrect() {
5865        let executor = deterministic::Runner::default();
5866        executor.start(|context: deterministic::Context| async move {
5867            let (blob, blob_size) = context
5868                .open("test_partition", b"shrink_torn")
5869                .await
5870                .unwrap();
5871            let blob = Arc::new(blob);
5872            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5873            let mut writer = Recovery::open(blob.clone(), blob_size, BUFFER_SIZE, cache_ref)
5874                .await
5875                .unwrap();
5876
5877            // Commit 80 bytes into the first slot, then durably shrink the tail page to 50.
5878            let data: Vec<u8> = (1u8..=80).collect();
5879            (writer, _) = writer.append(&data).await.unwrap();
5880            writer = writer.sync().await.unwrap();
5881            writer = writer.truncate(50).await.unwrap();
5882            drop(writer);
5883
5884            // Model a rewrite of the tail page back to 80 bytes torn down to only the retired
5885            // slot's length bytes: the pre-shrink data still on the page must not revalidate.
5886            let page_size = u64::from(PAGE_SIZE.get());
5887            blob.write_at(
5888                page_size,
5889                80u16.to_be_bytes().to_vec(),
5890                WriteOptions::default(),
5891            )
5892            .await
5893            .unwrap();
5894            blob.sync().await.unwrap();
5895
5896            drop(blob);
5897            let (blob, blob_size) = context
5898                .open("test_partition", b"shrink_torn")
5899                .await
5900                .unwrap();
5901            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5902            let recovered = Recovery::open(blob, blob_size, BUFFER_SIZE, cache_ref)
5903                .await
5904                .unwrap();
5905            assert_eq!(recovered.size(), 50);
5906            let read = recovered.read_at(0, 50).await.unwrap().coalesce();
5907            assert_eq!(read.as_ref(), &data[..50]);
5908        });
5909    }
5910
5911    /// Regression test for https://github.com/commonwarexyz/monorepo/issues/5667.
5912    ///
5913    /// A shrink torn while it retires the old checksum slot can leave that slot's CRC on the
5914    /// page. Recovery zeroes the slot, so a torn rewrite that lands only a length there cannot
5915    /// revalidate the bytes the shrink removed.
5916    #[test_traced("DEBUG")]
5917    fn issue_5667_regression_torn_shrink() {
5918        let executor = deterministic::Runner::default();
5919        executor.start(|context: deterministic::Context| async move {
5920            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
5921            let first_slot: usize = PAGE_SIZE.widen();
5922            let physical_page_size = first_slot + Checksum::SIZE;
5923            let first_slot_len = first_slot..first_slot + CHECKSUM_SLOT_LEN_SIZE;
5924            let data: Vec<u8> = (1u8..=80).collect();
5925
5926            // Commit 80 bytes, placing their checksum in the first slot.
5927            let (blob, size) = context
5928                .open("test_partition", b"torn_shrink")
5929                .await
5930                .unwrap();
5931            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5932                .await
5933                .unwrap();
5934            (writer, _) = writer.append(&data).await.unwrap();
5935            writer = writer.sync().await.unwrap();
5936            drop(writer);
5937
5938            // Shrink to 50 bytes, tearing the write that retires the first slot after its
5939            // length field.
5940            let (blob, size) = context
5941                .open("test_partition", b"torn_shrink")
5942                .await
5943                .unwrap();
5944            let blob = PartialWriteBlob::new(blob, 3, CHECKSUM_SLOT_LEN_SIZE);
5945            let failed_write_len = blob.failed_write_len();
5946            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5947                .await
5948                .unwrap();
5949            assert!(
5950                writer.truncate(50).await.is_err(),
5951                "the torn retirement must fail"
5952            );
5953            assert_eq!(failed_write_len.load(Ordering::SeqCst), CHECKSUM_SLOT_SIZE);
5954
5955            // Recovery selects the shorter checksum.
5956            let (blob, size) = context
5957                .open("test_partition", b"torn_shrink")
5958                .await
5959                .unwrap();
5960            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5961                .await
5962                .unwrap();
5963            assert_eq!(writer.size(), 50);
5964            drop(writer);
5965
5966            // Grow the page back to 80 bytes with different contents. The new checksum goes to the
5967            // first slot, and the rewrite is torn down to that slot's length field.
5968            let (blob, size) = context
5969                .open("test_partition", b"torn_shrink")
5970                .await
5971                .unwrap();
5972            let blob = PartialWriteBlob::keeping(blob, 1, first_slot_len);
5973            let failed_write_len = blob.failed_write_len();
5974            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
5975                .await
5976                .unwrap();
5977            (writer, _) = writer.append(&[0xAA; 30]).await.unwrap();
5978            assert!(writer.sync().await.is_err(), "the torn rewrite must fail");
5979            assert_eq!(failed_write_len.load(Ordering::SeqCst), physical_page_size);
5980
5981            // The bytes the shrink removed stay removed.
5982            let (blob, size) = context
5983                .open("test_partition", b"torn_shrink")
5984                .await
5985                .unwrap();
5986            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
5987                .await
5988                .unwrap();
5989            assert_eq!(writer.size(), 50);
5990            let read = writer.read_at(0, 50).await.unwrap().coalesce();
5991            assert_eq!(read.as_ref(), &data[..50]);
5992        });
5993    }
5994
5995    /// Regression test for https://github.com/commonwarexyz/monorepo/issues/5667.
5996    ///
5997    /// A torn append can leave its bytes and CRC on the page without their length. Recovery
5998    /// zeroes the slot, so a torn rewrite that lands only a length there cannot revalidate the
5999    /// bytes recovery discarded.
6000    #[test_traced("DEBUG")]
6001    fn issue_5667_regression_torn_append() {
6002        let executor = deterministic::Runner::default();
6003        executor.start(|context: deterministic::Context| async move {
6004            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6005            let first_slot: usize = PAGE_SIZE.widen();
6006            let physical_page_size = first_slot + Checksum::SIZE;
6007            let second_slot = first_slot + CHECKSUM_SLOT_SIZE;
6008            let second_slot_len = second_slot..second_slot + CHECKSUM_SLOT_LEN_SIZE;
6009            let data: Vec<u8> = (1u8..=50).collect();
6010
6011            // Commit 50 bytes, placing their checksum in the first slot.
6012            let (blob, size) = context
6013                .open("test_partition", b"torn_append")
6014                .await
6015                .unwrap();
6016            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6017                .await
6018                .unwrap();
6019            (writer, _) = writer.append(&data).await.unwrap();
6020            writer = writer.sync().await.unwrap();
6021            drop(writer);
6022
6023            // Append 60 bytes to fill the page and start the next one. The first page's new
6024            // checksum goes to the second slot. The write is torn so that the first page lands
6025            // without that slot's length field, followed by a fragment of the next page.
6026            let (blob, size) = context
6027                .open("test_partition", b"torn_append")
6028                .await
6029                .unwrap();
6030            let kept = [
6031                0..second_slot_len.start,
6032                second_slot_len.end..physical_page_size + 4,
6033            ];
6034            let blob = PartialWriteBlob::torn(blob, 1, kept);
6035            let failed_write_len = blob.failed_write_len();
6036            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6037                .await
6038                .unwrap();
6039            (writer, _) = writer.append(&[0x11; 60]).await.unwrap();
6040            assert!(writer.sync().await.is_err(), "the torn append must fail");
6041            assert_eq!(
6042                failed_write_len.load(Ordering::SeqCst),
6043                2 * physical_page_size
6044            );
6045
6046            // Recovery trims the fragment and discards the append.
6047            let (blob, size) = context
6048                .open("test_partition", b"torn_append")
6049                .await
6050                .unwrap();
6051            assert_eq!(size, Widen::<u64>::widen(physical_page_size + 4));
6052            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6053                .await
6054                .unwrap();
6055            assert_eq!(writer.size(), 50);
6056            drop(writer);
6057
6058            // Append 60 different bytes, tearing the write down to that length field.
6059            let (blob, size) = context
6060                .open("test_partition", b"torn_append")
6061                .await
6062                .unwrap();
6063            let blob = PartialWriteBlob::keeping(blob, 1, second_slot_len);
6064            let failed_write_len = blob.failed_write_len();
6065            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6066                .await
6067                .unwrap();
6068            (writer, _) = writer.append(&[0xAA; 60]).await.unwrap();
6069            assert!(writer.sync().await.is_err(), "the torn append must fail");
6070            assert_eq!(
6071                failed_write_len.load(Ordering::SeqCst),
6072                2 * physical_page_size
6073            );
6074
6075            // The discarded append stays discarded.
6076            let (blob, size) = context
6077                .open("test_partition", b"torn_append")
6078                .await
6079                .unwrap();
6080            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6081                .await
6082                .unwrap();
6083            assert_eq!(writer.size(), 50);
6084            let read = writer.read_at(0, 50).await.unwrap().coalesce();
6085            assert_eq!(read.as_ref(), data.as_slice());
6086        });
6087    }
6088
6089    /// Recovery writes nothing when the other slot holds the checksum of a shorter prefix of the
6090    /// page.
6091    #[test_traced("DEBUG")]
6092    fn test_recovery_open_keeps_prefix_checksum() {
6093        let executor = deterministic::Runner::default();
6094        executor.start(|context: deterministic::Context| async move {
6095            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6096            let data: Vec<u8> = (1u8..=80).collect();
6097
6098            // Commit 50 bytes, then 30 more, leaving the 50-byte checksum beside the 80-byte one.
6099            let (blob, size) = context
6100                .open("test_partition", b"prefix_checksum")
6101                .await
6102                .unwrap();
6103            let mut writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6104                .await
6105                .unwrap();
6106            (writer, _) = writer.append(&data[..50]).await.unwrap();
6107            writer = writer.sync().await.unwrap();
6108            (writer, _) = writer.append(&data[50..]).await.unwrap();
6109            writer = writer.sync().await.unwrap();
6110            drop(writer);
6111
6112            // Reopening leaves the page untouched.
6113            let (blob, size) = context
6114                .open("test_partition", b"prefix_checksum")
6115                .await
6116                .unwrap();
6117            let blob = PartialWriteBlob::new(blob, usize::MAX, 0);
6118            let writes = blob.write_count();
6119            let writer = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6120                .await
6121                .unwrap();
6122            assert_eq!(writer.size(), 80);
6123            assert_eq!(writes.load(Ordering::SeqCst), 0);
6124        });
6125    }
6126
6127    #[test]
6128    fn test_recovery_truncate_same_page_shrink_survives_interrupted_crc_stage() {
6129        let executor = deterministic::Runner::default();
6130        executor.start(|context| async move {
6131            // Put the durable 50-byte prefix in the second checksum slot.
6132            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6133            let data: Vec<u8> = (0..50).collect();
6134
6135            let (blob, size) = context
6136                .open("test_partition", b"same_page_shrink_interrupted")
6137                .await
6138                .unwrap();
6139            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6140                .await
6141                .unwrap();
6142            (append, _) = append.append(&data[..40]).await.unwrap();
6143            append = append.sync().await.unwrap();
6144            (append, _) = append.append(&data[40..]).await.unwrap();
6145            append = append.sync().await.unwrap();
6146            drop(append);
6147
6148            // Tear the staged shorter checksum before its length can be published.
6149            let (blob, size) = context
6150                .open("test_partition", b"same_page_shrink_interrupted")
6151                .await
6152                .unwrap();
6153            let faulty_blob = PartialWriteBlob::new(blob, 1, 3);
6154            let write_count = faulty_blob.write_count();
6155            let failed_write_len = faulty_blob.failed_write_len();
6156            let append = Recovery::open(faulty_blob, size, BUFFER_SIZE, cache_ref.clone())
6157                .await
6158                .unwrap();
6159
6160            assert!(
6161                append.truncate(45).await.is_err(),
6162                "phase-1 partial write should fail"
6163            );
6164            assert_eq!(write_count.load(Ordering::SeqCst), 1);
6165            assert_eq!(failed_write_len.load(Ordering::SeqCst), CHECKSUM_SLOT_SIZE);
6166
6167            // The untouched authoritative slot must recover all 50 durable bytes.
6168            let (blob, size) = context
6169                .open("test_partition", b"same_page_shrink_interrupted")
6170                .await
6171                .unwrap();
6172            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6173                .await
6174                .unwrap();
6175            assert_eq!(append.size(), 50);
6176            let read = append.read_at(0, 50).await.unwrap().coalesce();
6177            assert_eq!(read.as_ref(), &data);
6178        });
6179    }
6180
6181    #[test]
6182    fn test_recovery_truncate_same_page_shrink_survives_interrupted_len_stage() {
6183        let executor = deterministic::Runner::default();
6184        executor.start(|context| async move {
6185            // Use a length above 255 so a one-byte tear changes the decoded length.
6186            const LARGE_PAGE_SIZE: NonZeroU16 = NZU16!(600);
6187            const LARGE_BUFFER_SIZE: usize = 1_200;
6188
6189            let cache_ref = CacheRef::new(LARGE_PAGE_SIZE, NZUsize!(LARGE_BUFFER_SIZE));
6190            let data: Vec<u8> = (0..300).map(|i| (i % 251) as u8).collect();
6191
6192            let (blob, size) = context
6193                .open("test_partition", b"same_page_shrink_len_stage")
6194                .await
6195                .unwrap();
6196            let mut append = Recovery::open(blob, size, LARGE_BUFFER_SIZE, cache_ref.clone())
6197                .await
6198                .unwrap();
6199            (append, _) = append.append(&data[..255]).await.unwrap();
6200            append = append.sync().await.unwrap();
6201            (append, _) = append.append(&data[255..]).await.unwrap();
6202            append = append.sync().await.unwrap();
6203            drop(append);
6204
6205            // Tear the shorter slot's published length after its checksum is staged.
6206            let (blob, size) = context
6207                .open("test_partition", b"same_page_shrink_len_stage")
6208                .await
6209                .unwrap();
6210            let faulty_blob = PartialWriteBlob::new(blob, 2, 1);
6211            let write_count = faulty_blob.write_count();
6212            let failed_write_len = faulty_blob.failed_write_len();
6213            let append = Recovery::open(faulty_blob, size, LARGE_BUFFER_SIZE, cache_ref.clone())
6214                .await
6215                .unwrap();
6216
6217            assert!(
6218                append.truncate(257).await.is_err(),
6219                "length-stage partial write should fail"
6220            );
6221            assert_eq!(write_count.load(Ordering::SeqCst), 2);
6222            assert_eq!(failed_write_len.load(Ordering::SeqCst), 2);
6223
6224            // The torn new length must leave the original 300-byte slot authoritative.
6225            let (blob, size) = context
6226                .open("test_partition", b"same_page_shrink_len_stage")
6227                .await
6228                .unwrap();
6229            let append = Recovery::open(blob, size, LARGE_BUFFER_SIZE, cache_ref)
6230                .await
6231                .unwrap();
6232            assert_eq!(append.size(), 300);
6233            let read = append.read_at(0, 300).await.unwrap().coalesce();
6234            assert_eq!(read.as_ref(), &data);
6235        });
6236    }
6237
6238    #[test]
6239    fn test_recovery_truncate_same_page_shrink_preserves_validated_fallback_slot() {
6240        let executor = deterministic::Runner::default();
6241        executor.start(|context| async move {
6242            // Prepare two durable checksum slots and tear the next checksum write.
6243            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6244            let data: Vec<u8> = (0..52).collect();
6245
6246            let (blob, size) = context
6247                .open("test_partition", b"same_page_shrink_fallback_slot")
6248                .await
6249                .unwrap();
6250            let blob = Arc::new(blob);
6251            let faulty_blob = PartialWriteBlob::new(blob.clone(), 4, 3);
6252            let write_count = faulty_blob.write_count();
6253            let failed_write_len = faulty_blob.failed_write_len();
6254            let mut append = Recovery::open(faulty_blob, size, BUFFER_SIZE, cache_ref.clone())
6255                .await
6256                .unwrap();
6257            (append, _) = append.append(&data[..48]).await.unwrap();
6258            append = append.sync().await.unwrap();
6259            assert_eq!(write_count.load(Ordering::SeqCst), 1);
6260
6261            (append, _) = append.append(&data[48..50]).await.unwrap();
6262            append = append.sync().await.unwrap();
6263            assert_eq!(write_count.load(Ordering::SeqCst), 2);
6264
6265            (append, _) = append.append(&data[50..]).await.unwrap();
6266            append = append.sync().await.unwrap();
6267            assert_eq!(write_count.load(Ordering::SeqCst), 3);
6268
6269            // Corrupt the newer authoritative slot. The older slot still covers the shrink target.
6270            // The cached footer no longer matches storage. A torn phase-1 shrink write must
6271            // preserve the fallback slot validated from storage.
6272            let slot0_offset = PAGE_SIZE.get() as u64;
6273            blob.write_at(slot0_offset, DUMMY_MARKER.to_vec(), WriteOptions::default())
6274                .await
6275                .unwrap();
6276            blob.sync().await.unwrap();
6277
6278            assert!(
6279                append.truncate(45).await.is_err(),
6280                "phase-1 partial write should fail"
6281            );
6282            assert_eq!(write_count.load(Ordering::SeqCst), 4);
6283            assert_eq!(failed_write_len.load(Ordering::SeqCst), CHECKSUM_SLOT_SIZE);
6284
6285            // Recovery must use the older validated slot after the failed shrink.
6286            drop(blob);
6287            let (blob, size) = context
6288                .open("test_partition", b"same_page_shrink_fallback_slot")
6289                .await
6290                .unwrap();
6291            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6292                .await
6293                .unwrap();
6294            assert_eq!(append.size(), 50);
6295            let read = append.read_at(0, 50).await.unwrap().coalesce();
6296            assert_eq!(read.as_ref(), &data[..50]);
6297        });
6298    }
6299
6300    #[test]
6301    fn test_recovery_truncate_full_page_to_partial_reopens_at_shorter_size() {
6302        let executor = deterministic::Runner::default();
6303        executor.start(|context| async move {
6304            // Start with two full pages and choose a shorter tip inside the second page.
6305            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6306            let page_size = PAGE_SIZE.get() as u64;
6307            let target = page_size + 45;
6308            let data: Vec<u8> = (0..page_size * 2).map(|i| (i % 251) as u8).collect();
6309
6310            let (blob, size) = context
6311                .open("test_partition", b"full_page_to_partial")
6312                .await
6313                .unwrap();
6314            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6315                .await
6316                .unwrap();
6317            (append, _) = append.append(&data).await.unwrap();
6318            append = append.sync().await.unwrap();
6319
6320            // Persist the shorter checksum before releasing the recovery owner.
6321            append = append.truncate(target).await.unwrap();
6322            drop(append);
6323
6324            // A fresh recovery must expose exactly the selected prefix.
6325            let (blob, size) = context
6326                .open("test_partition", b"full_page_to_partial")
6327                .await
6328                .unwrap();
6329            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6330                .await
6331                .unwrap();
6332            assert_eq!(append.size(), target);
6333            let read = append.read_at(0, target as usize).await.unwrap().coalesce();
6334            assert_eq!(read.as_ref(), &data[..target as usize]);
6335        });
6336    }
6337
6338    #[test]
6339    fn test_recovery_truncate_full_page_to_partial_survives_interrupted_crc_stage() {
6340        let executor = deterministic::Runner::default();
6341        executor.start(|context| async move {
6342            // Persist three full pages so truncation first removes the physical suffix.
6343            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6344            let page_size = PAGE_SIZE.get() as u64;
6345            let target = page_size + 45;
6346            let data: Vec<u8> = (0..page_size * 3).map(|i| (i % 251) as u8).collect();
6347
6348            let (blob, size) = context
6349                .open("test_partition", b"full_page_to_partial_interrupted")
6350                .await
6351                .unwrap();
6352            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6353                .await
6354                .unwrap();
6355            (append, _) = append.append(&data).await.unwrap();
6356            append = append.sync().await.unwrap();
6357            drop(append);
6358
6359            // Tear the shorter checksum after the physical resize has completed.
6360            let (blob, size) = context
6361                .open("test_partition", b"full_page_to_partial_interrupted")
6362                .await
6363                .unwrap();
6364            let faulty_blob = PartialWriteBlob::new(blob, 1, 3);
6365            let write_count = faulty_blob.write_count();
6366            let failed_write_len = faulty_blob.failed_write_len();
6367            let append = Recovery::open(faulty_blob, size, BUFFER_SIZE, cache_ref.clone())
6368                .await
6369                .unwrap();
6370
6371            assert!(
6372                append.truncate(target).await.is_err(),
6373                "phase-1 partial write should fail"
6374            );
6375            assert_eq!(write_count.load(Ordering::SeqCst), 1);
6376            assert_eq!(failed_write_len.load(Ordering::SeqCst), CHECKSUM_SLOT_SIZE);
6377
6378            // Recovery must retain the two full pages left by the completed resize.
6379            let (blob, size) = context
6380                .open("test_partition", b"full_page_to_partial_interrupted")
6381                .await
6382                .unwrap();
6383            let append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref)
6384                .await
6385                .unwrap();
6386            assert_eq!(append.size(), page_size * 2);
6387            let read = append
6388                .read_at(0, (page_size * 2) as usize)
6389                .await
6390                .unwrap()
6391                .coalesce();
6392            assert_eq!(read.as_ref(), &data[..(page_size * 2) as usize]);
6393        });
6394    }
6395
6396    #[test]
6397    fn test_recovery_truncate_same_page_shrink_survives_interrupted_length_invalidation() {
6398        let executor = deterministic::Runner::default();
6399        executor.start(|context| async move {
6400            // Use lengths above 255 to expose a one-byte tear in old-slot invalidation.
6401            const LARGE_PAGE_SIZE: NonZeroU16 = NZU16!(600);
6402            const LARGE_BUFFER_SIZE: usize = 1_200;
6403
6404            let cache_ref = CacheRef::new(LARGE_PAGE_SIZE, NZUsize!(LARGE_BUFFER_SIZE));
6405            let data: Vec<u8> = (0..300).map(|i| (i % 251) as u8).collect();
6406
6407            let (blob, size) = context
6408                .open(
6409                    "test_partition",
6410                    b"same_page_shrink_interrupted_len_invalidation",
6411                )
6412                .await
6413                .unwrap();
6414            let mut append = Recovery::open(blob, size, LARGE_BUFFER_SIZE, cache_ref.clone())
6415                .await
6416                .unwrap();
6417
6418            // Put the old authoritative CRC in slot 1, so the shorter CRC will be staged in slot 0.
6419            (append, _) = append.append(&data[..255]).await.unwrap();
6420            append = append.sync().await.unwrap();
6421            (append, _) = append.append(&data[255..]).await.unwrap();
6422            append = append.sync().await.unwrap();
6423            drop(append);
6424
6425            // Tear invalidation of the old slot after the shorter slot is durable.
6426            let (blob, size) = context
6427                .open(
6428                    "test_partition",
6429                    b"same_page_shrink_interrupted_len_invalidation",
6430                )
6431                .await
6432                .unwrap();
6433            let faulty_blob = PartialWriteBlob::new(blob, 3, 1);
6434            let write_count = faulty_blob.write_count();
6435            let failed_write_len = faulty_blob.failed_write_len();
6436            let append = Recovery::open(faulty_blob, size, LARGE_BUFFER_SIZE, cache_ref.clone())
6437                .await
6438                .unwrap();
6439
6440            assert!(
6441                append.truncate(40).await.is_err(),
6442                "old-slot length invalidation should fail"
6443            );
6444            assert_eq!(write_count.load(Ordering::SeqCst), 3);
6445            assert_eq!(failed_write_len.load(Ordering::SeqCst), CHECKSUM_SLOT_SIZE);
6446
6447            // Recovery must select the durable shorter slot despite the torn invalidation.
6448            let (blob, size) = context
6449                .open(
6450                    "test_partition",
6451                    b"same_page_shrink_interrupted_len_invalidation",
6452                )
6453                .await
6454                .unwrap();
6455            let append = Recovery::open(blob, size, LARGE_BUFFER_SIZE, cache_ref)
6456                .await
6457                .unwrap();
6458            assert_eq!(append.size(), 40);
6459            let read = append.read_at(0, 40).await.unwrap().coalesce();
6460            assert_eq!(read.as_ref(), &data[..40]);
6461        });
6462    }
6463
6464    #[test_traced("DEBUG")]
6465    fn test_recovery_truncate_partial_shrink_without_physical_resize_uses_range_sync() {
6466        let executor = deterministic::Runner::default();
6467        executor.start(|_: deterministic::Context| async move {
6468            let blob = SyncTrackingBlob::new();
6469            let blob = Arc::new(blob);
6470            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6471            let mut append = Recovery::open(blob.clone(), 0, BUFFER_SIZE, cache_ref)
6472                .await
6473                .unwrap();
6474            append = append.sync().await.unwrap();
6475
6476            let data = vec![5u8; PAGE_SIZE.get() as usize];
6477            (append, _) = append.append(&data).await.unwrap();
6478            append = append.sync().await.unwrap();
6479
6480            // Shrinking within the same physical page only rewrites CRC metadata.
6481            append = append.truncate(50).await.unwrap();
6482            append.sync().await.unwrap();
6483
6484            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
6485            assert_eq!(writes, 4);
6486            assert_eq!(full_syncs, 1);
6487            assert_eq!(range_syncs, 4);
6488        });
6489    }
6490
6491    #[test_traced("DEBUG")]
6492    fn test_recovery_truncate_partial_shrink_with_physical_resize_clears_full_sync_requirement() {
6493        let executor = deterministic::Runner::default();
6494        executor.start(|_: deterministic::Context| async move {
6495            let blob = SyncTrackingBlob::new();
6496            let blob = Arc::new(blob);
6497            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6498            let mut append = Recovery::open(blob.clone(), 0, BUFFER_SIZE, cache_ref)
6499                .await
6500                .unwrap();
6501            append = append.sync().await.unwrap();
6502
6503            let data = vec![9u8; PAGE_SIZE.get() as usize * 2];
6504            (append, _) = append.append(&data).await.unwrap();
6505            append = append.sync().await.unwrap();
6506
6507            // Shrinking from two physical pages to one partial page must also make the resize
6508            // durable.
6509            append = append.truncate(50).await.unwrap();
6510            append = append.sync().await.unwrap();
6511
6512            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
6513            assert_eq!(writes, 4);
6514            assert_eq!(full_syncs, 2);
6515            assert_eq!(range_syncs, 3);
6516
6517            // Once the resize barrier is cleared, the next single flush can use range sync again.
6518            (append, _) = append.append(b"x").await.unwrap();
6519            append = append.sync().await.unwrap();
6520
6521            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
6522            assert_eq!(writes, 5);
6523            assert_eq!(full_syncs, 2);
6524            assert_eq!(range_syncs, 4);
6525
6526            let mut expected = data[..50].to_vec();
6527            expected.push(b'x');
6528            let read = append.read_at(0, expected.len()).await.unwrap().coalesce();
6529            assert_eq!(read.as_ref(), expected.as_slice());
6530        });
6531    }
6532
6533    #[test_traced("DEBUG")]
6534    fn test_recovery_truncate_page_boundary_shrink_uses_full_sync() {
6535        let executor = deterministic::Runner::default();
6536        executor.start(|_: deterministic::Context| async move {
6537            let blob = SyncTrackingBlob::new();
6538            let blob = Arc::new(blob);
6539            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6540            let mut append = Recovery::open(blob.clone(), 0, BUFFER_SIZE, cache_ref)
6541                .await
6542                .unwrap();
6543            append = append.sync().await.unwrap();
6544
6545            // Start with two durable full pages. After clearing the wrapper barrier, the data sync
6546            // can persist them with one range-sync write.
6547            let page_size = PAGE_SIZE.get() as usize;
6548            let data = vec![11u8; page_size * 2];
6549            (append, _) = append.append(&data).await.unwrap();
6550            append = append.sync().await.unwrap();
6551
6552            // Shrinking to a page boundary resizes the blob but does not rewrite CRC metadata.
6553            // Only the resize needs a full sync, which the truncation issues itself.
6554            append = append.truncate(PAGE_SIZE.get() as u64).await.unwrap();
6555            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
6556            assert_eq!(writes, 1);
6557            assert_eq!(full_syncs, 2);
6558            assert_eq!(range_syncs, 1);
6559
6560            // Nothing is left pending, so a later sync adds no barrier.
6561            append.sync().await.unwrap();
6562            let (_, writes, full_syncs, range_syncs) = blob.snapshot();
6563            assert_eq!(writes, 1);
6564            assert_eq!(full_syncs, 2);
6565            assert_eq!(range_syncs, 1);
6566
6567            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6568            let reopened = Recovery::open(blob.clone(), blob.size(), BUFFER_SIZE, cache_ref)
6569                .await
6570                .unwrap();
6571            assert_eq!(reopened.size(), PAGE_SIZE.get() as u64);
6572            let read = reopened.read_at(0, page_size).await.unwrap().coalesce();
6573            assert_eq!(read.as_ref(), &data[..page_size]);
6574        });
6575    }
6576
6577    #[test]
6578    fn test_recovery_partial_tail_append_and_truncate() {
6579        let executor = deterministic::Runner::default();
6580        executor.start(|context| async move {
6581            const PAGE_SIZE: NonZeroU16 = NZU16!(64);
6582            const BUFFER_SIZE: usize = 256;
6583
6584            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(4));
6585
6586            let (blob, size) = context
6587                .open("test_partition", b"partial_tail_test")
6588                .await
6589                .unwrap();
6590
6591            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6592                .await
6593                .unwrap();
6594
6595            // Write some initial data.
6596            (append, _) = append.append(&[1, 2, 3, 4, 5]).await.unwrap();
6597            append = append.sync().await.unwrap();
6598            assert_eq!(append.size(), 5);
6599            drop(append);
6600
6601            let (blob, size) = context
6602                .open("test_partition", b"partial_tail_test")
6603                .await
6604                .unwrap();
6605
6606            let mut append = Recovery::open(blob, size, BUFFER_SIZE, cache_ref.clone())
6607                .await
6608                .unwrap();
6609            assert_eq!(append.size(), 5);
6610
6611            (append, _) = append.append(&[6, 7, 8]).await.unwrap();
6612            append = append.truncate(6).await.unwrap();
6613            append = append.sync().await.unwrap();
6614
6615            let data: Vec<u8> = append.read_at(0, 6).await.unwrap().coalesce().into();
6616            assert_eq!(data, vec![1, 2, 3, 4, 5, 6]);
6617        });
6618    }
6619
6620    #[test]
6621    fn test_corrupted_crc_len_too_large() {
6622        let executor = deterministic::Runner::default();
6623        executor.start(|context| async move {
6624            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6625            let physical_page_size = PAGE_SIZE.get() as usize + CHECKSUM_SIZE as usize;
6626
6627            // Step 1: Create blob with valid data
6628            let (blob, size) = context
6629                .open("test_partition", b"crc_len_test")
6630                .await
6631                .unwrap();
6632
6633            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
6634                .await
6635                .unwrap();
6636
6637            (append, _) = append.append(&[0x42; 50]).await.unwrap();
6638            append = append.sync().await.unwrap();
6639            drop(append);
6640
6641            // Step 2: Corrupt the CRC record to have len > page_size
6642            let (blob, size) = context
6643                .open("test_partition", b"crc_len_test")
6644                .await
6645                .unwrap();
6646            assert_eq!(size as usize, physical_page_size);
6647
6648            // CRC record is at the end of the physical page
6649            let crc_offset = PAGE_SIZE.get() as u64;
6650
6651            // Create a CRC record with len1 = 0xFFFF (65535), which is >> page_size (103)
6652            // Format: [len1_hi, len1_lo, crc1 (4 bytes), len2_hi, len2_lo, crc2 (4 bytes)]
6653            let bad_crc_record: [u8; 12] = [
6654                0xFF, 0xFF, // len1 = 65535 (way too large)
6655                0xDE, 0xAD, 0xBE, 0xEF, // crc1 (garbage)
6656                0x00, 0x00, // len2 = 0
6657                0x00, 0x00, 0x00, 0x00, // crc2 = 0
6658            ];
6659            blob.write_at(crc_offset, bad_crc_record.to_vec(), WriteOptions::default())
6660                .await
6661                .unwrap();
6662            blob.sync().await.unwrap();
6663
6664            // Step 3: Opening the blob should NOT panic
6665            let result = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone()).await;
6666
6667            // Either returns InvalidChecksum error OR truncates the corrupted data
6668            // (both are acceptable behaviors, but panicking is NOT acceptable)
6669            match result {
6670                Ok(append) => {
6671                    // If it opens successfully, the corrupted page should have been truncated
6672                    let recovered_size = append.size();
6673                    assert_eq!(
6674                        recovered_size, 0,
6675                        "Corrupted page should be truncated, size should be 0"
6676                    );
6677                }
6678                Err(e) => {
6679                    // Error is also acceptable
6680                    assert!(
6681                        matches!(e, crate::Error::InvalidChecksum),
6682                        "Expected InvalidChecksum error, got: {:?}",
6683                        e
6684                    );
6685                }
6686            }
6687        });
6688    }
6689
6690    #[test]
6691    fn test_corrupted_crc_both_slots_len_too_large() {
6692        let executor = deterministic::Runner::default();
6693        executor.start(|context| async move {
6694            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6695
6696            // Step 1: Create blob with valid data
6697            let (blob, size) = context
6698                .open("test_partition", b"crc_both_bad")
6699                .await
6700                .unwrap();
6701
6702            let mut append = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone())
6703                .await
6704                .unwrap();
6705
6706            (append, _) = append.append(&[0x42; 50]).await.unwrap();
6707            append = append.sync().await.unwrap();
6708            drop(append);
6709
6710            // Step 2: Corrupt BOTH CRC slots to have len > page_size
6711            let (blob, size) = context
6712                .open("test_partition", b"crc_both_bad")
6713                .await
6714                .unwrap();
6715
6716            let crc_offset = PAGE_SIZE.get() as u64;
6717
6718            // Both slots have len > page_size
6719            let bad_crc_record: [u8; 12] = [
6720                0x01, 0x00, // len1 = 256 (> 103)
6721                0xDE, 0xAD, 0xBE, 0xEF, // crc1 (garbage)
6722                0x02, 0x00, // len2 = 512 (> 103)
6723                0xCA, 0xFE, 0xBA, 0xBE, // crc2 (garbage)
6724            ];
6725            blob.write_at(crc_offset, bad_crc_record.to_vec(), WriteOptions::default())
6726                .await
6727                .unwrap();
6728            blob.sync().await.unwrap();
6729
6730            // Step 3: Opening should NOT panic
6731            let result = Writer::new(blob, size, BUFFER_SIZE, cache_ref.clone()).await;
6732
6733            match result {
6734                Ok(append) => {
6735                    // Corrupted page truncated
6736                    assert_eq!(append.size(), 0);
6737                }
6738                Err(e) => {
6739                    assert!(
6740                        matches!(e, crate::Error::InvalidChecksum),
6741                        "Expected InvalidChecksum, got: {:?}",
6742                        e
6743                    );
6744                }
6745            }
6746        });
6747    }
6748
6749    /// Readers observe buffered (not yet flushed) bytes through both async and sync read paths.
6750    #[test_traced("DEBUG")]
6751    fn test_reader_sees_buffered_bytes() {
6752        let executor = deterministic::Runner::default();
6753        executor.start(|context: deterministic::Context| async move {
6754            let (blob, blob_size) = context.open("test_partition", b"rdr_buf").await.unwrap();
6755            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6756            let mut writer = Writer::new(blob, blob_size, BUFFER_SIZE, cache_ref)
6757                .await
6758                .unwrap();
6759
6760            let data: Vec<u8> = (0u8..50).collect();
6761            (writer, _) = writer.append(&data).await.unwrap();
6762
6763            // No flush or sync has happened; reads must still see the buffered bytes.
6764            assert_eq!(writer.size(), 50);
6765            let read = writer.read_at(0, 50).await.unwrap().coalesce();
6766            assert_eq!(read.as_ref(), data.as_slice());
6767
6768            let mut buf = vec![0u8; 10];
6769            assert!(writer.try_read_sync_into(&mut buf, 20));
6770            assert_eq!(buf, data[20..30]);
6771        });
6772    }
6773
6774    /// Recovery rejects reads past the selected end and preserves the retained bytes.
6775    #[test_traced("DEBUG")]
6776    fn test_recovery_read_past_truncated_end_errors_cleanly() {
6777        let executor = deterministic::Runner::default();
6778        executor.start(|context: deterministic::Context| async move {
6779            let (blob, blob_size) = context.open("test_partition", b"rdr_rsz").await.unwrap();
6780            let cache_ref = CacheRef::new(PAGE_SIZE, NZUsize!(BUFFER_SIZE));
6781            let mut writer = Recovery::open(blob, blob_size, BUFFER_SIZE, cache_ref)
6782                .await
6783                .unwrap();
6784
6785            let page_size = PAGE_SIZE.get() as usize;
6786            let data: Vec<u8> = (0u8..=255).cycle().take(page_size * 2).collect();
6787            (writer, _) = writer.append(&data).await.unwrap();
6788            writer = writer.sync().await.unwrap();
6789            assert_eq!(writer.size(), (page_size * 2) as u64);
6790
6791            // Shrink below the last observed size.
6792            let new_size = (page_size / 2) as u64;
6793            writer = writer.truncate(new_size).await.unwrap();
6794
6795            // Reads past the new size fail cleanly.
6796            let err = writer
6797                .read_at(new_size, page_size)
6798                .await
6799                .expect_err("read past truncated end must fail");
6800            assert!(matches!(err, Error::BlobInsufficientLength));
6801
6802            // Reads within the new size return the retained prefix, not stale cached bytes.
6803            let read = writer
6804                .read_at(0, new_size as usize)
6805                .await
6806                .unwrap()
6807                .coalesce();
6808            assert_eq!(read.as_ref(), &data[..new_size as usize]);
6809        });
6810    }
6811}