Skip to main content

sensor_db/
async_db.rs

1//! Async version of SensorDb for use with Embassy and `embedded-storage-async`.
2//!
3//! This module provides [`SensorDbAsync`], which mirrors the API of [`SensorDb`](crate::SensorDb)
4//! but uses `async fn` for all flash-touching operations. This enables DMA-based flash access
5//! on targets like RP2350 when used with Embassy.
6//!
7//! ## Differences from `SensorDb`
8//!
9//! - **No `RefCell`**: All methods take `&mut self`. Async code cannot safely borrow through
10//!   `RefCell` across `.await` points, so interior mutability is not used.
11//! - **All flash operations are `async`**: `mount`, `format`, `append`, `sync`, `latest`,
12//!   `query_range`, `oldest`, `count`, `compact` are all async.
13//!
14//! ## What is shared with the sync implementation
15//!
16//! [`SensorDbAsync`] holds the same `SensorDbState` value as [`SensorDb`](crate::SensorDb),
17//! so every field and every helper that does not touch flash — sector ordering, wear
18//! levelling (`find_next_sector`), page-buffer scanning, bloom filters — is defined
19//! exactly once in `db.rs` and used verbatim here.
20//!
21//! What remains duplicated is only the code that actually calls flash. The sync and async
22//! `NorFlash` traits are unrelated types, so `flush_page`, `seal_and_advance`, the sector
23//! scanners and the five `*_in_sector` readers exist in both flavours. That duplication is
24//! deliberate: it buys zero-overhead sync and async types with no generic sync/async
25//! machinery.
26//!
27//! ## Example
28//!
29//! ```ignore
30//! use sensor_db::SensorDbAsync;
31//!
32//! let mut db: SensorDbAsync<_, 256, 512> = SensorDbAsync::new(
33//!     flash, 0x0020_0000, 512, 2,
34//! )?;
35//!
36//! db.mount().await?;
37//! db.append(0x01, timestamp_us, &temperature_bytes).await?;
38//! ```
39
40use crate::db::{
41    AppendStep, CompactScope, DbConfig, DbStats, Edge, LogPosition, MountMode, MountStats,
42    ReadCursor, Replicated, Scan, ScannedEntry, ScannedSector, SectorScanner, SensorDbState,
43    SpoolStats, sort_by_seq,
44};
45use crate::entry::{ENTRY_HEADER_SIZE, ENTRY_OVERHEAD, EntryHeader, EntryKind};
46use crate::error::Error;
47use crate::partition::Partition;
48use crate::run::{RUN_FRAME_SIZE, Run, RunFrame, deliver_samples, samples_in};
49use crate::schema;
50use crate::sector::{
51    LogId, SECTOR_FOOTER_SIZE, SECTOR_HEADER_SIZE, SectorClass, SectorFooter, SectorHeader,
52    SectorState, SectorSummary,
53};
54use crate::typed::SensorData;
55use embedded_storage_async::nor_flash::{NorFlash, ReadNorFlash};
56use heapless::Vec as HeaplessVec;
57use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
58
59/// Async twin of [`Geometry`](crate::db::Geometry): compile-time check that the
60/// driver's write granularity divides `PAGE_SIZE`.
61///
62/// Duplicated rather than shared because `embedded-storage` and
63/// `embedded-storage-async` are unrelated trait families — `WRITE_SIZE` has to be
64/// read from whichever one the driver implements.
65struct GeometryAsync<F: ?Sized, const PAGE_SIZE: usize>(core::marker::PhantomData<F>);
66
67impl<F: NorFlash + ?Sized, const PAGE_SIZE: usize> GeometryAsync<F, PAGE_SIZE> {
68    /// Fails the build when `PAGE_SIZE` is not a whole number of writes.
69    const PAGE_IS_WRITABLE: () = assert!(
70        PAGE_SIZE.is_multiple_of(F::WRITE_SIZE),
71        "PAGE_SIZE must be a multiple of the flash driver's WRITE_SIZE",
72    );
73}
74
75/// The blocking [`SectorScanner`] driven with `.await`ing reads.
76///
77/// There is no async *scanner*: the cursor and every decision it makes live in
78/// [`crate::db`], I/O-free, and this is the loop that supplies the reads. The
79/// pair of them replaced a hand-written mirror of the whole scanner, whose only
80/// difference from the original was the `.await` — and which the byte-for-byte
81/// parity suite could never have caught drifting, because a scan performed
82/// wrongly by *both* drivers agrees with itself.
83async fn next_entry_async<F: ReadNorFlash>(
84    scanner: &mut SectorScanner,
85    flash: &mut F,
86    header_buf: &mut [u8; ENTRY_HEADER_SIZE],
87    page_size: usize,
88) -> Result<Option<ScannedEntry>, Error> {
89    let mut step = scanner.begin();
90    loop {
91        match step {
92            Scan::Done => return Ok(None),
93            Scan::Found(entry) => return Ok(Some(entry)),
94            Scan::Read(addr) => {
95                flash.read(addr, &mut header_buf[..]).await?;
96                step = scanner.feed(header_buf, page_size);
97            }
98        }
99    }
100}
101
102/// [`ScannedEntry::accept`] with an `.await`ing read in front of it.
103async fn accept_entry_async<F: ReadNorFlash>(
104    flash: &mut F,
105    sector_offset: u32,
106    entry: &ScannedEntry,
107    buf: &mut [u8],
108) -> Result<bool, Error> {
109    let (addr, read_len) = entry.payload_read(sector_offset);
110    // Defensive: never slice past the caller's buffer on a malformed entry.
111    if read_len > buf.len() {
112        return Ok(false);
113    }
114    flash.read(addr, &mut buf[..read_len]).await?;
115    Ok(entry.accept(buf))
116}
117
118/// Async append-only sensor database for NOR flash.
119///
120/// This is the async counterpart of [`SensorDb`](crate::SensorDb), using
121/// `embedded-storage-async` traits for all flash operations. It is designed
122/// for use with Embassy on targets that benefit from DMA-based flash access.
123///
124/// ## Key differences from `SensorDb`
125///
126/// - All flash-touching methods are `async fn`
127/// - All methods take `&mut self` (no `RefCell` / interior mutability)
128/// - Reuses the same wire format, sector layout, and `SensorDbState` value
129///
130/// Generic parameters:
131/// - `F`: Flash storage implementing async `NorFlash` and `ReadNorFlash`
132/// - `PAGE_SIZE`: the unit this database writes in. Must be a multiple of
133///   `F::WRITE_SIZE`, checked at compile time, and must not exceed the part's
134///   physical program page — which the trait does not express, so it cannot be
135///   checked. See [`SensorDb`](crate::SensorDb) for the full contract.
136/// - `MAX_SECTORS`: Maximum number of sectors this instance can manage
137pub struct SensorDbAsync<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
138    flash: F,
139    state: SensorDbState<PAGE_SIZE, MAX_SECTORS>,
140}
141
142impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> core::fmt::Debug
143    for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
144{
145    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
146        f.debug_struct("SensorDbAsync")
147            .field("base_offset", &self.state.base_offset)
148            .field("sector_count", &self.state.sector_count)
149            .field("sector_size", &self.state.sector_size)
150            .field("mounted", &self.state.mounted)
151            .field("active_sector", &self.state.active_sector)
152            .field("total_entries", &self.state.total_entries)
153            .finish_non_exhaustive()
154    }
155}
156
157impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
158where
159    F: NorFlash + ReadNorFlash,
160{
161    /// Create a new async SensorDb instance.
162    ///
163    /// # Arguments
164    /// - `flash`: Async flash storage
165    /// - `base_offset`: Starting offset in flash for the database region
166    /// - `sector_count`: Number of sectors to use
167    /// - `reserved_sectors`: Number of sectors to keep free for compaction headroom
168    ///
169    /// # Errors
170    /// - `TooManySectors` if `sector_count > MAX_SECTORS`
171    /// - `InvalidConfig` if `reserved_sectors >= sector_count`
172    pub fn new(
173        flash: F,
174        base_offset: u32,
175        sector_count: u16,
176        reserved_sectors: u16,
177    ) -> Result<Self, Error> {
178        Self::with_config(
179            flash,
180            DbConfig::new(base_offset, sector_count, reserved_sectors)?,
181        )
182    }
183
184    /// Create a `SensorDbAsync` from a validated [`DbConfig`].
185    ///
186    /// Use this instead of [`new`](Self::new) when the database needs a
187    /// [`LogId`] — for example when its storage is
188    /// removable and could be carried to, or confused with, another device.
189    ///
190    /// # Errors
191    /// - `TooManySectors` if `config.sector_count() > MAX_SECTORS`
192    /// - `Overflow` if the region does not fit in `u32` address space
193    ///
194    /// # Panics
195    ///
196    /// Fails to *compile*, not to run, if `PAGE_SIZE` is not a multiple of
197    /// `F::WRITE_SIZE`.
198    pub fn with_config(flash: F, config: DbConfig) -> Result<Self, Error> {
199        let () = GeometryAsync::<F, PAGE_SIZE>::PAGE_IS_WRITABLE;
200        Ok(Self {
201            flash,
202            state: SensorDbState::new(config, F::ERASE_SIZE as u32)?,
203        })
204    }
205
206    /// Format the database region, erasing all sectors and initializing the first as active.
207    ///
208    /// After format, the database is automatically mounted.
209    pub async fn format(&mut self) -> Result<(), Error> {
210        // Erase all sectors
211        for i in 0..self.state.sector_count {
212            self.erase_sector(i).await?;
213            self.state.sectors[i as usize] = SectorSummary::erased();
214            self.state.sectors[i as usize].erase_count = 1;
215        }
216
217        // Initialize first sector as active
218        self.init_sector(0, 1, 1).await?;
219        self.state.sectors[0].state = SectorState::Active;
220        self.state.sectors[0].sequence = 1;
221        self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
222        self.state.sectors[0].erase_count = 1;
223
224        self.state.active_sector = Some(0);
225        self.state.next_sequence = 2;
226        self.state.total_entries = 0;
227        self.state.total_samples = 0;
228        self.state.mounted = true;
229        self.state.mount_mode = MountMode::Full;
230        // `init_sector` above stamps epoch 1, so nothing is owed.
231        self.state.epoch_pending = false;
232        self.state.spool_watermark = LogPosition::BEGINNING;
233        self.state.spooled_entries = 0;
234        self.state.spooled_samples = 0;
235        self.state.dropped_unspooled = 0;
236
237        // Initialize page buffer for the active sector
238        self.state.page_flash_offset = self.state.base_offset;
239        self.state.page_buf_offset = SECTOR_HEADER_SIZE;
240        self.state.page_buf_durable = SECTOR_HEADER_SIZE;
241        self.state.page_buf.fill(0xFF);
242        let header = self.state.sector_header(1, 1);
243        self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
244
245        Ok(())
246    }
247
248    /// Mount an existing database by scanning all sectors and rebuilding the index.
249    ///
250    /// Equivalent to [`mount_with(MountMode::Full)`](Self::mount_with).
251    ///
252    /// # Errors
253    /// - `AlreadyMounted` if already mounted
254    /// - `ForeignVolume` if the medium belongs to a different log
255    /// - `UnsupportedVersion` if the medium uses a newer format
256    pub async fn mount(&mut self) -> Result<MountStats, Error> {
257        self.mount_with(MountMode::Full).await
258    }
259
260    /// Mount an existing database, choosing how much of the index to rebuild.
261    ///
262    /// See [`SensorDb::mount_with`](crate::SensorDb::mount_with) for the
263    /// foreign-media and epoch semantics; they are identical here.
264    ///
265    /// # Errors
266    /// - `AlreadyMounted` if already mounted
267    /// - `ForeignVolume` if the medium belongs to a different log
268    /// - `UnsupportedVersion` if the medium uses a newer format
269    pub async fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error> {
270        if self.state.mounted {
271            return Err(Error::AlreadyMounted);
272        }
273
274        let mut stats = MountStats::default();
275        let mut max_sequence: u32 = 0;
276        let mut max_epoch: u32 = 0;
277
278        // Pass 1: headers only. Classification happens before any write, so a
279        // foreign or unreadable volume is rejected intact.
280        let mut valid: HeaplessVec<u16, MAX_SECTORS> = HeaplessVec::new();
281        for i in 0..self.state.sector_count {
282            let sector_offset = self.state.sector_offset(i);
283            let mut header_buf = [0u8; SECTOR_HEADER_SIZE];
284            self.flash.read(sector_offset, &mut header_buf).await?;
285
286            let header =
287                SectorHeader::read_from_bytes(&header_buf).map_err(|_| Error::CorruptEntry)?;
288
289            match header.classify(self.state.log_id) {
290                SectorClass::Valid => {
291                    let seq = header.sequence.get();
292                    let epoch = header.epoch.get();
293                    self.state.sectors[i as usize].sequence = seq;
294                    self.state.sectors[i as usize].erase_count = header.erase_count.get();
295                    max_sequence = max_sequence.max(seq);
296                    max_epoch = max_epoch.max(epoch);
297                    let _ = valid.push(i);
298                }
299                SectorClass::Free => {
300                    self.state.sectors[i as usize] = SectorSummary::erased();
301                }
302                SectorClass::Foreign { found } => {
303                    return Err(Error::ForeignVolume {
304                        expected: self.state.log_id_raw(),
305                        found,
306                    });
307                }
308                SectorClass::Unsupported { found } => {
309                    return Err(Error::UnsupportedVersion { found });
310                }
311            }
312        }
313
314        // The newest sector is the only one an append can land in, so it must be
315        // scanned in every mode to find the resume offset.
316        let newest = valid
317            .iter()
318            .copied()
319            .max_by_key(|i| self.state.sectors[*i as usize].sequence);
320
321        // Pass 2: rebuild the entry index for the sectors this mode covers.
322        // See the blocking driver for why `newest_sealed` is tracked.
323        let mut newest_sealed = false;
324        for i in valid.iter().copied() {
325            let is_newest = Some(i) == newest;
326
327            // Read a footer when it can index the sector — and always for the
328            // newest one, where it is not an optimisation at all but the signal
329            // that the sector is already closed.
330            let footer = if self.state.wants_footer(mode, is_newest) {
331                self.read_sector_footer(i).await?
332            } else {
333                None
334            };
335            if is_newest {
336                newest_sealed = footer.is_some();
337            }
338
339            // `Verify` exists to re-read the medium, so it indexes from entries
340            // even where a footer would have answered.
341            if let Some(footer) = footer.filter(|_| mode != MountMode::Verify) {
342                self.state.adopt_footer(i, &footer, &mut stats);
343            } else if mode != MountMode::HeadersOnly || is_newest {
344                let (scanned, corrupt) = self.scan_sector_entries(i).await?;
345                self.state.adopt_scan(i, &scanned, corrupt, &mut stats);
346            } else {
347                self.state.adopt_unindexed(i);
348            }
349            self.state.sectors[i as usize].state = SectorState::Sealed;
350            stats.sealed_sectors += 1;
351        }
352
353        self.state
354            .finish_mount(mode, max_sequence, max_epoch, &stats);
355
356        if let Some(idx) = newest {
357            self.state.sectors[idx as usize].state = SectorState::Active;
358            self.state.active_sector = Some(idx);
359            stats.sealed_sectors = stats.sealed_sectors.saturating_sub(1);
360
361            // This sector was created by an earlier run, so it carries that run's
362            // epoch. Owe a sector roll, paid on the first append.
363            self.state.epoch_pending = true;
364
365            let sector_offset = self.state.sector_offset(idx);
366
367            // Where writing resumes inside this sector — the footer page when
368            // the sector was already sealed, so `append`'s boundary check seals
369            // and moves on rather than appending into a frozen summary. See the
370            // blocking driver.
371            let resume = if newest_sealed {
372                self.state.footer_offset()
373            } else {
374                self.state.sectors[idx as usize].write_offset
375            };
376
377            let page_start = (resume / PAGE_SIZE as u32) * PAGE_SIZE as u32;
378            self.state.page_flash_offset = sector_offset + page_start;
379            self.state.page_buf_offset = (resume % PAGE_SIZE as u32) as usize;
380            self.state.page_buf_durable = self.state.page_buf_offset;
381            self.state.page_buf.fill(0xFF);
382
383            // A power loss can leave written bytes *past* the last valid entry,
384            // and not only in this page: the scanner steps over uncommitted
385            // entries without adopting them, so whole pages of half-committed
386            // data can sit ahead of the resume point. Appending before them
387            // would eventually flush into a dirty page, and NOR cannot set bits
388            // back — the write fails and the log wedges.
389            //
390            // Find the last page in this sector that still holds data, and
391            // resume after it. Bounded by the footer offset: the final page is
392            // not data.
393            let mut last_dirty: Option<u32> = None;
394            let mut probe = page_start;
395            while probe < self.state.footer_offset() {
396                self.flash
397                    .read(sector_offset + probe, &mut self.state.page_buf)
398                    .await?;
399                let from = if probe == page_start {
400                    self.state.page_buf_offset
401                } else {
402                    0
403                };
404                if self.state.page_buf[from..].iter().any(|b| *b != 0xFF) {
405                    last_dirty = Some(probe);
406                }
407                probe += PAGE_SIZE as u32;
408            }
409
410            match last_dirty {
411                None if resume < self.state.footer_offset() => {
412                    self.flash
413                        .read(self.state.page_flash_offset, &mut self.state.page_buf)
414                        .await?;
415                }
416                None => {}
417                Some(dirty) => {
418                    self.state.page_flash_offset = sector_offset + dirty + PAGE_SIZE as u32;
419                    self.state.page_buf_offset = 0;
420                    self.state.page_buf_durable = 0;
421                    self.state.page_buf.fill(0xFF);
422                    self.state.sectors[idx as usize].write_offset = dirty + PAGE_SIZE as u32;
423                }
424            }
425        } else {
426            // No valid sectors found. The chosen sector may hold stale data from a
427            // previous format (NOR writes only clear bits, so writing a fresh
428            // header over it would corrupt the magic), so erase before init.
429            //
430            // Reaching here means every sector classified as Free, so nothing
431            // another log owns is being destroyed.
432            self.erase_sector(0).await?;
433            self.init_sector(0, self.state.next_sequence, 1).await?;
434            // That header carries this run's epoch, so nothing is owed.
435            self.state.epoch_pending = false;
436            self.state.sectors[0].state = SectorState::Active;
437            self.state.sectors[0].sequence = self.state.next_sequence;
438            self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
439            self.state.sectors[0].erase_count = 1;
440            self.state.active_sector = Some(0);
441            self.state.next_sequence += 1;
442
443            self.state.page_flash_offset = self.state.base_offset;
444            self.state.page_buf_offset = SECTOR_HEADER_SIZE;
445            self.state.page_buf_durable = SECTOR_HEADER_SIZE;
446            self.state.page_buf.fill(0xFF);
447            let header = self.state.sector_header(self.state.sectors[0].sequence, 1);
448            self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
449        }
450
451        self.state.mounted = true;
452        Ok(stats)
453    }
454
455    /// Append a sensor reading to the database.
456    ///
457    /// # Errors
458    /// - `NotMounted` if not mounted
459    /// - `PayloadTooLarge` if payload exceeds max size
460    /// - `NoSpace` if no sectors available
461    pub async fn append(
462        &mut self,
463        sensor_id: u16,
464        timestamp: u64,
465        payload: &[u8],
466    ) -> Result<(), Error> {
467        self.append_entry(
468            EntryKind::Single,
469            sensor_id,
470            timestamp,
471            timestamp,
472            1,
473            &[],
474            payload,
475        )
476        .await
477    }
478
479    /// Append a [run](crate::run): many evenly spaced samples under one header.
480    ///
481    /// Async mirror of [`SensorDb::append_run`](crate::SensorDb::append_run),
482    /// including its invisibility to every read.
483    pub async fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
484        let mut frame = [0u8; RUN_FRAME_SIZE];
485        run.write_frame(&mut frame);
486        self.append_entry(
487            EntryKind::Run,
488            run.sensor_id(),
489            run.base_timestamp(),
490            run.span_end(),
491            run.count(),
492            &frame,
493            run.samples(),
494        )
495        .await
496    }
497
498    /// Append an entry exactly as another log stored it.
499    ///
500    /// Async mirror of
501    /// [`SensorDb::append_framed`](crate::SensorDb::append_framed).
502    pub async fn append_framed(
503        &mut self,
504        header: &EntryHeader,
505        payload: &[u8],
506    ) -> Result<(), Error> {
507        match header.kind {
508            EntryKind::Single => {
509                self.append(header.sensor_id, header.timestamp, payload)
510                    .await
511            }
512            EntryKind::Run => {
513                let frame = RunFrame::parse(payload).ok_or(Error::CorruptEntry)?;
514                self.append_entry(
515                    EntryKind::Run,
516                    header.sensor_id,
517                    header.timestamp,
518                    frame.span_end(header.timestamp),
519                    frame.count(),
520                    &[],
521                    payload,
522                )
523                .await
524            }
525        }
526    }
527
528    /// The one write path; see
529    /// [`SensorDb::append_entry`](crate::SensorDb) for the reasoning.
530    #[allow(clippy::too_many_arguments)]
531    async fn append_entry(
532        &mut self,
533        kind: EntryKind,
534        sensor_id: u16,
535        timestamp: u64,
536        span_end: u64,
537        samples: u32,
538        head: &[u8],
539        tail: &[u8],
540    ) -> Result<(), Error> {
541        if !self.state.mounted {
542            return Err(Error::NotMounted);
543        }
544
545        let payload_len = head.len() + tail.len();
546        let entry_size = ENTRY_OVERHEAD + payload_len;
547        if payload_len > self.max_payload_size() {
548            return Err(Error::PayloadTooLarge);
549        }
550
551        // Roll to a fresh sector so this run's epoch reaches the medium; see the
552        // blocking driver. `NoSpace` is tolerated — provenance never costs a
553        // write.
554        if self.state.epoch_pending {
555            match self.seal_and_advance().await {
556                Ok(()) => {}
557                Err(Error::NoSpace) => self.state.epoch_pending = false,
558                Err(e) => return Err(e),
559            }
560        }
561
562        let mut sealed_once = false;
563        loop {
564            match self.state.plan_append(entry_size)? {
565                AppendStep::Stage => break,
566                AppendStep::FlushPage => self.flush_page().await?,
567                AppendStep::Seal => {
568                    if sealed_once {
569                        return Err(Error::PayloadTooLarge);
570                    }
571                    sealed_once = true;
572                    self.seal_and_advance().await?;
573                }
574            }
575        }
576
577        self.state
578            .stage_entry(kind, sensor_id, timestamp, span_end, samples, head, tail)
579    }
580
581    /// Flush the page buffer to flash, committing buffered entries.
582    pub async fn sync(&mut self) -> Result<(), Error> {
583        if !self.state.mounted {
584            return Err(Error::NotMounted);
585        }
586        self.flush_page().await?;
587        Ok(())
588    }
589
590    /// Find the most recent entry for a given sensor.
591    ///
592    /// # Arguments
593    /// - `sensor_id`: Sensor to query
594    /// - `buf`: Buffer to receive payload
595    ///
596    /// # Returns
597    /// `Some((header, payload_len))` if found, `None` if no entries for this sensor.
598    pub async fn latest(
599        &mut self,
600        sensor_id: u16,
601        buf: &mut [u8],
602    ) -> Result<Option<(EntryHeader, usize)>, Error> {
603        self.state.require_reads()?;
604
605        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
606        for i in 0..self.state.sector_count {
607            let summary = &self.state.sectors[i as usize];
608            if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
609                let _ = sector_order.push((i, summary.sequence));
610            }
611        }
612        sort_by_seq(&mut sector_order, |a, b| b.cmp(a));
613
614        let mut best: Option<(EntryHeader, usize)> = None;
615        for (sector_idx, _) in sector_order {
616            if let Some(result) = self
617                .find_latest_in_sector(sector_idx, sensor_id, buf)
618                .await?
619            {
620                best = Some(result);
621                break;
622            }
623        }
624
625        let min_ts = best.as_ref().map_or(0, |(h, _)| h.timestamp);
626        if let Some((hdr, len)) = self
627            .state
628            .scan_page_buf_for_latest(sensor_id, min_ts, buf)?
629        {
630            best = Some((hdr, len));
631        }
632
633        Ok(best)
634    }
635
636    /// Query entries within a time range.
637    ///
638    /// # Arguments
639    /// - `sensor_id`: Optional sensor filter (None for all sensors)
640    /// - `t_start`: Start timestamp (inclusive)
641    /// - `t_end`: End timestamp (inclusive)
642    /// - `callback`: Called for each matching entry. Return `false` to stop early.
643    ///
644    /// # Returns
645    /// Number of entries that matched.
646    pub async fn query_range<C>(
647        &mut self,
648        sensor_id: Option<u16>,
649        t_start: u64,
650        t_end: u64,
651        mut callback: C,
652    ) -> Result<u32, Error>
653    where
654        C: FnMut(&EntryHeader, &[u8]) -> bool,
655    {
656        self.state.require_reads()?;
657
658        let mut count = 0u32;
659
660        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
661        for i in 0..self.state.sector_count {
662            let summary = &self.state.sectors[i as usize];
663            if summary.state != SectorState::Erased
664                && summary.entry_count > 0
665                && summary.overlaps_time_range(t_start, t_end)
666                && sensor_id.is_none_or(|id| summary.might_contain_sensor(id))
667            {
668                let _ = sector_order.push((i, summary.sequence));
669            }
670        }
671        sort_by_seq(&mut sector_order, u32::cmp);
672
673        let mut entry_buf = [0u8; PAGE_SIZE];
674        let mut stopped = false;
675
676        for (sector_idx, _) in sector_order {
677            stopped = self
678                .scan_sector_for_query(
679                    sector_idx,
680                    sensor_id,
681                    t_start,
682                    t_end,
683                    &mut entry_buf,
684                    &mut count,
685                    &mut callback,
686                )
687                .await?;
688            if stopped {
689                break;
690            }
691        }
692
693        if !stopped {
694            self.state.scan_page_buf_for_query(
695                sensor_id,
696                t_start,
697                t_end,
698                &mut entry_buf,
699                &mut count,
700                &mut callback,
701            );
702        }
703
704        Ok(count)
705    }
706
707    /// Query all entries for a sensor (or all sensors) without time constraints.
708    pub async fn query_all<C>(&mut self, sensor_id: Option<u16>, callback: C) -> Result<u32, Error>
709    where
710        C: FnMut(&EntryHeader, &[u8]) -> bool,
711    {
712        self.query_range(sensor_id, 0, u64::MAX, callback).await
713    }
714
715    /// Find the oldest (earliest) entry for a given sensor.
716    pub async fn oldest(
717        &mut self,
718        sensor_id: u16,
719        buf: &mut [u8],
720    ) -> Result<Option<(EntryHeader, usize)>, Error> {
721        self.state.require_reads()?;
722
723        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
724        for i in 0..self.state.sector_count {
725            let summary = &self.state.sectors[i as usize];
726            if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
727                let _ = sector_order.push((i, summary.sequence));
728            }
729        }
730        sort_by_seq(&mut sector_order, u32::cmp);
731
732        for (sector_idx, _) in sector_order {
733            if let Some((header, payload_len)) = self
734                .find_oldest_in_sector(sector_idx, sensor_id, buf)
735                .await?
736            {
737                return Ok(Some((header, payload_len)));
738            }
739        }
740
741        if let Some(result) = self.state.scan_page_buf_for_oldest(sensor_id, buf) {
742            return Ok(Some(result));
743        }
744
745        Ok(None)
746    }
747
748    /// Count entries for a specific sensor (or all sensors).
749    ///
750    /// Exact, and priced, exactly as [`SensorDb::count`](crate::SensorDb::count)
751    /// — the count matches what [`query_range`](Self::query_range) would yield,
752    /// at the cost of a payload read per entry in each sector the bloom filter
753    /// does not reject.
754    pub async fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
755        self.state.require_reads()?;
756
757        let Some(target) = sensor_id else {
758            return Ok(self.state.total_samples);
759        };
760
761        let mut count = 0u32;
762
763        for i in 0..self.state.sector_count {
764            let summary = &self.state.sectors[i as usize];
765            if summary.state != SectorState::Erased && summary.might_contain_sensor(target) {
766                count += self.count_sensor_in_sector(i, target).await?;
767            }
768        }
769
770        count += self.state.count_sensor_in_page_buf(target);
771
772        Ok(count)
773    }
774
775    /// Compact the database by erasing the oldest sealed sectors.
776    ///
777    /// See [`SensorDb::compact`](crate::SensorDb::compact) for the meaning of
778    /// `scope`.
779    pub async fn compact(&mut self, count: u16, scope: CompactScope) -> Result<u16, Error> {
780        if !self.state.mounted {
781            return Err(Error::NotMounted);
782        }
783
784        let mut sealed: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
785        for i in 0..self.state.sector_count {
786            let summary = &self.state.sectors[i as usize];
787            if summary.state != SectorState::Sealed {
788                continue;
789            }
790            if scope == CompactScope::SpooledOnly && !self.state.is_fully_spooled(summary) {
791                continue;
792            }
793            let _ = sealed.push((i, summary.sequence));
794        }
795
796        sort_by_seq(&mut sealed, u32::cmp);
797
798        let mut erased = 0u16;
799        for (sector_idx, _) in sealed.iter().take(count as usize) {
800            let victim = self.state.sectors[*sector_idx as usize];
801            self.erase_sector(*sector_idx).await?;
802            // Only after the erase actually succeeded.
803            self.state.account_eviction(&victim);
804            self.state.sectors[*sector_idx as usize] = SectorSummary::erased();
805            self.state.sectors[*sector_idx as usize].erase_count = victim.erase_count;
806            erased += 1;
807        }
808
809        Ok(erased)
810    }
811
812    /// Sectors this instance has erased, since it was created.
813    ///
814    /// See [`SensorDb::sectors_erased`](crate::SensorDb::sectors_erased).
815    pub fn sectors_erased(&self) -> u32 {
816        self.state.sectors_erased
817    }
818
819    /// Get database statistics.
820    pub fn stats(&self) -> DbStats {
821        self.state.stats()
822    }
823
824    /// Check if the database is mounted.
825    pub fn is_mounted(&self) -> bool {
826        self.state.mounted
827    }
828
829    /// Maximum payload size that can fit in a single entry.
830    pub fn max_payload_size(&self) -> usize {
831        PAGE_SIZE - ENTRY_OVERHEAD
832    }
833
834    // -------------------------------------------------------------------------
835    // Typed API - Layer 1: Explicit sensor ID with zerocopy types
836    // -------------------------------------------------------------------------
837
838    /// Append a typed value with an explicit sensor ID, untagged.
839    ///
840    /// Entries written this way carry no schema version and are not readable
841    /// through the `*_sensor` methods.
842    pub async fn append_value<T: IntoBytes + Immutable>(
843        &mut self,
844        sensor_id: u16,
845        timestamp: u64,
846        data: &T,
847    ) -> Result<(), Error> {
848        self.append(sensor_id, timestamp, data.as_bytes()).await
849    }
850
851    /// Find the most recent entry for a sensor and interpret as a typed value.
852    pub async fn latest_value<T: FromBytes + KnownLayout>(
853        &mut self,
854        sensor_id: u16,
855    ) -> Result<Option<(EntryHeader, T)>, Error> {
856        let expected_size = core::mem::size_of::<T>();
857        let mut buf = [0u8; PAGE_SIZE];
858
859        match self.latest(sensor_id, &mut buf).await? {
860            Some((header, payload_len)) => {
861                if payload_len != expected_size {
862                    return Err(Error::SizeMismatch {
863                        expected: expected_size,
864                        actual: payload_len,
865                    });
866                }
867                let value =
868                    T::read_from_bytes(&buf[..payload_len]).map_err(|_| Error::InvalidData)?;
869                Ok(Some((header, value)))
870            }
871            None => Ok(None),
872        }
873    }
874
875    // -------------------------------------------------------------------------
876    // Typed API - Layer 2: Type-driven sensor ID via SensorData trait
877    // -------------------------------------------------------------------------
878
879    /// Append a sensor reading using the type-driven API.
880    ///
881    /// The payload is the type's `SCHEMA_VERSION` followed by the value's
882    /// bytes; see [`SensorData::SCHEMA_VERSION`].
883    pub async fn append_sensor<T: SensorData>(
884        &mut self,
885        timestamp: u64,
886        data: &T,
887    ) -> Result<(), Error> {
888        // Bound before the await: a temporary in the call would not outlive it.
889        let framed = schema::tag(data);
890        self.append(T::SENSOR_ID, timestamp, framed.bytes()).await
891    }
892
893    /// Find the most recent entry for a sensor type.
894    ///
895    /// # Errors
896    /// - `SizeMismatch` if the stored payload is not `size_of::<T>() + 1` bytes
897    /// - `SchemaMismatch` if it was written under another `SCHEMA_VERSION`
898    pub async fn latest_sensor<T: SensorData>(
899        &mut self,
900    ) -> Result<Option<(EntryHeader, T)>, Error> {
901        let mut framed = schema::Tagged::<T>::empty();
902        let found = self.latest(T::SENSOR_ID, framed.bytes_mut()).await?;
903        schema::untag(found, framed)
904    }
905
906    /// Query sensor entries within a time range using the type-driven API.
907    pub async fn query_sensor<T: SensorData, C>(
908        &mut self,
909        t_start: u64,
910        t_end: u64,
911        mut callback: C,
912    ) -> Result<u32, Error>
913    where
914        C: FnMut(&EntryHeader, &T) -> bool,
915    {
916        let mut count = 0u32;
917
918        self.query_range(Some(T::SENSOR_ID), t_start, t_end, |header, payload| {
919            // Skipped, not raised — see the blocking driver.
920            let Some(value) = schema::untag_payload::<T>(payload) else {
921                return true;
922            };
923            count += 1;
924            callback(header, &value)
925        })
926        .await?;
927
928        Ok(count)
929    }
930
931    /// Query all entries for a sensor type without time constraints.
932    pub async fn query_all_sensor<T: SensorData, C>(&mut self, callback: C) -> Result<u32, Error>
933    where
934        C: FnMut(&EntryHeader, &T) -> bool,
935    {
936        self.query_sensor(0, u64::MAX, callback).await
937    }
938
939    /// Find the oldest (earliest) entry for a sensor type.
940    pub async fn oldest_sensor<T: SensorData>(
941        &mut self,
942    ) -> Result<Option<(EntryHeader, T)>, Error> {
943        let mut framed = schema::Tagged::<T>::empty();
944        let found = self.oldest(T::SENSOR_ID, framed.bytes_mut()).await?;
945        schema::untag(found, framed)
946    }
947
948    /// Count entries for a sensor type.
949    pub async fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error> {
950        self.count(Some(T::SENSOR_ID)).await
951    }
952
953    // -------------------------------------------------------------------------
954    // Replication primitives
955    // -------------------------------------------------------------------------
956
957    /// Deliver committed entries in log order, starting at `from` (inclusive).
958    ///
959    /// Async mirror of [`SensorDb::read_from`](crate::SensorDb::read_from); see
960    /// there for the durability boundary, ordering, and gap semantics.
961    ///
962    /// # Errors
963    /// - `NotMounted` if the database is not mounted
964    /// - whatever the callback returns
965    pub async fn read_from<C>(
966        &mut self,
967        from: LogPosition,
968        max_entries: u32,
969        mut callback: C,
970    ) -> Result<ReadCursor, Error>
971    where
972        C: FnMut(LogPosition, &EntryHeader, &[u8]) -> Result<bool, Error>,
973    {
974        if !self.state.mounted {
975            return Err(Error::NotMounted);
976        }
977
978        let mut order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
979        let mut oldest_seq = u32::MAX;
980        for i in 0..self.state.sector_count {
981            let summary = &self.state.sectors[i as usize];
982            if summary.state == SectorState::Erased {
983                continue;
984            }
985            if summary.sequence < oldest_seq {
986                oldest_seq = summary.sequence;
987            }
988            if summary.sequence >= from.sequence {
989                let _ = order.push((i, summary.sequence));
990            }
991        }
992        sort_by_seq(&mut order, u32::cmp);
993
994        let gap =
995            from != LogPosition::BEGINNING && oldest_seq != u32::MAX && from.sequence < oldest_seq;
996
997        let mut cursor = ReadCursor {
998            next: from,
999            entries: 0,
1000            exhausted: false,
1001            gap,
1002        };
1003
1004        if max_entries == 0 {
1005            return Ok(cursor);
1006        }
1007
1008        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1009        let mut buf = [0u8; PAGE_SIZE];
1010        let mut stopped = false;
1011
1012        for (sector_idx, seq) in order {
1013            let sector_offset = self.state.sector_offset(sector_idx);
1014            // `write_offset` is the right limit even for the active sector: the
1015            // bytes past the last flush read back as 0xFF, so the scanner runs
1016            // out of page before it runs out of limit and stops on its own.
1017            let limit = self.state.sectors[sector_idx as usize].write_offset;
1018            let start = if seq == from.sequence {
1019                from.offset.max(SECTOR_HEADER_SIZE as u32)
1020            } else {
1021                SECTOR_HEADER_SIZE as u32
1022            };
1023            if start >= limit {
1024                continue;
1025            }
1026
1027            let mut scanner = SectorScanner::new(sector_offset, start, limit);
1028            while let Some(entry) =
1029                next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1030            {
1031                if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut buf).await? {
1032                    scanner.skip(1);
1033                    continue;
1034                }
1035
1036                let position = LogPosition {
1037                    sequence: seq,
1038                    offset: entry.offset_in_sector,
1039                };
1040                let header = entry.header.to_header();
1041                // A rejected entry must not advance the cursor past it, or the
1042                // caller would resume after something it never accepted.
1043                if !callback(position, &header, &buf[..entry.payload_len])? {
1044                    stopped = true;
1045                    break;
1046                }
1047
1048                scanner.skip(entry.entry_size);
1049                cursor.entries += 1;
1050                cursor.next = LogPosition {
1051                    sequence: seq,
1052                    offset: scanner.offset(),
1053                };
1054
1055                if cursor.entries >= max_entries {
1056                    stopped = true;
1057                    break;
1058                }
1059            }
1060
1061            if stopped {
1062                break;
1063            }
1064        }
1065
1066        cursor.exhausted = !stopped;
1067        Ok(cursor)
1068    }
1069
1070    /// Hand out entries buffered in RAM but not yet durable, then discard them.
1071    ///
1072    /// Async mirror of
1073    /// [`SensorDb::drain_unflushed`](crate::SensorDb::drain_unflushed). Touches
1074    /// no flash, so it works when the device has physically gone away.
1075    pub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
1076    where
1077        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
1078    {
1079        self.state.drain_unflushed(callback)
1080    }
1081
1082    /// Show the RAM-buffered entries without removing them.
1083    ///
1084    /// Async mirror of
1085    /// [`SensorDb::peek_unflushed`](crate::SensorDb::peek_unflushed). Not
1086    /// `async`: it touches no flash.
1087    pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
1088    where
1089        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
1090    {
1091        self.state.peek_unflushed(callback)
1092    }
1093
1094    /// The epoch of the sector containing `position`.
1095    ///
1096    /// Async mirror of
1097    /// [`SensorDb::sector_epoch_at`](crate::SensorDb::sector_epoch_at).
1098    pub async fn sector_epoch_at(&mut self, position: LogPosition) -> Result<Option<u32>, Error> {
1099        if !self.state.mounted {
1100            return Err(Error::NotMounted);
1101        }
1102        let Some(idx) = self.state.sector_at_sequence(position.sequence) else {
1103            return Ok(None);
1104        };
1105
1106        let offset = self.state.sector_offset(idx);
1107        let mut buf = [0u8; SECTOR_HEADER_SIZE];
1108        self.flash.read(offset, &mut buf).await?;
1109        let header = SectorHeader::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
1110        Ok(header.is_valid().then(|| header.epoch.get()))
1111    }
1112
1113    /// Declare this log a replica of another, suppressing the per-run epoch roll.
1114    ///
1115    /// See [`SensorDb::mark_as_replica`](crate::SensorDb::mark_as_replica).
1116    pub fn mark_as_replica(&mut self) {
1117        self.state.epoch_pending = false;
1118    }
1119
1120    /// Position immediately after the newest entry, buffered entries included.
1121    pub fn head_position(&self) -> LogPosition {
1122        self.state.head_position()
1123    }
1124
1125    /// Position of the oldest entry the log still retains.
1126    pub fn tail_position(&self) -> LogPosition {
1127        self.state.tail_position()
1128    }
1129
1130    /// Advance the replication watermark. See
1131    /// [`SensorDb::note_spooled`](crate::SensorDb::note_spooled).
1132    pub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated) {
1133        self.state.note_spooled(upto, moved);
1134    }
1135
1136    /// Restore the replication watermark from an external source of truth. See
1137    /// [`SensorDb::restore_spool_watermark`](crate::SensorDb::restore_spool_watermark),
1138    /// including why an `Err` leaves the log fully usable.
1139    ///
1140    /// `async` because exact accounting costs one scan of the sector the
1141    /// watermark falls inside.
1142    pub async fn restore_spool_watermark(&mut self, upto: LogPosition) -> Result<(), Error> {
1143        let Some(boundary) = self.state.restore_spool_watermark(upto) else {
1144            return Ok(());
1145        };
1146        let counted = self.count_entries_before(boundary, upto.offset).await?;
1147        self.state.add_spooled(counted);
1148        Ok(())
1149    }
1150
1151    /// Replication accounting for this log.
1152    pub fn spool_stats(&self) -> SpoolStats {
1153        self.state.spool_stats()
1154    }
1155
1156    /// This log's declared identity, if any.
1157    pub fn log_id(&self) -> Option<LogId> {
1158        self.state.log_id
1159    }
1160
1161    /// The current epoch — one higher than any epoch seen on the medium at mount.
1162    pub fn epoch(&self) -> u32 {
1163        self.state.epoch
1164    }
1165
1166    /// How much of the index the current mount rebuilt.
1167    pub fn mount_mode(&self) -> MountMode {
1168        self.state.mount_mode
1169    }
1170
1171    /// Flash access bounded to `[base, base + len)`.
1172    ///
1173    /// The async counterpart of
1174    /// [`SensorDb::with_region`](crate::SensorDb::with_region), and it returns
1175    /// the [`Partition`] rather than taking a closure: a closure cannot express
1176    /// an awaited operation, because the future it returned would borrow from
1177    /// its own argument and the signature has nowhere to tie that lifetime to.
1178    ///
1179    /// The same check applies — a region intersecting the database's sectors is
1180    /// rejected with [`Error::RegionOverlap`] — and it applies at the point the
1181    /// partition is handed out, which is the only place it can be applied.
1182    ///
1183    /// # Errors
1184    /// - `RegionOverlap` if the region intersects the database's sectors
1185    /// - `InvalidConfig` if `base` or `len` is misaligned, `len` is zero, or the
1186    ///   region runs past the device's capacity
1187    /// - `Overflow` if `base + len` does not fit in `u32`
1188    pub fn region(&mut self, base: u32, len: u32) -> Result<Partition<&mut F>, Error> {
1189        self.state.check_disjoint(base, len)?;
1190        Partition::new_async(&mut self.flash, base, len)
1191    }
1192
1193    /// Borrow the underlying flash driver.
1194    ///
1195    /// See [`SensorDb::driver_mut`](crate::SensorDb::driver_mut): driver
1196    /// capabilities only — presence detection, wear counters, chip
1197    /// identification, power modes. To address flash, use
1198    /// [`region`](Self::region), which is checked.
1199    pub fn driver_mut(&mut self) -> &mut F {
1200        &mut self.flash
1201    }
1202
1203    /// Consume the database and return the underlying flash storage.
1204    pub fn into_inner(self) -> F {
1205        self.flash
1206    }
1207
1208    // =========================================================================
1209    // Async flash-accessing helpers
1210    // =========================================================================
1211
1212    async fn erase_sector(&mut self, sector_idx: u16) -> Result<(), Error> {
1213        let offset = self.state.sector_offset(sector_idx);
1214        self.flash
1215            .erase(offset, offset + self.state.sector_size)
1216            .await?;
1217        // After the erase, so the count is of sectors actually erased. A failure
1218        // reaches the caller as an error, which is a louder signal than this.
1219        self.state.sectors_erased = self.state.sectors_erased.saturating_add(1);
1220        Ok(())
1221    }
1222
1223    async fn init_sector(
1224        &mut self,
1225        sector_idx: u16,
1226        sequence: u32,
1227        erase_count: u32,
1228    ) -> Result<(), Error> {
1229        let header = self.state.sector_header(sequence, erase_count);
1230        let offset = self.state.sector_offset(sector_idx);
1231
1232        let mut page = [0xFFu8; PAGE_SIZE];
1233        page[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
1234        self.flash.write(offset, &page).await?;
1235
1236        Ok(())
1237    }
1238
1239    /// Read and validate the footer of `sector_idx`; `None` for anything that
1240    /// does not describe this sector's current incarnation. See the blocking
1241    /// driver's `read_sector_footer`.
1242    async fn read_sector_footer(&mut self, sector_idx: u16) -> Result<Option<SectorFooter>, Error> {
1243        let offset = self.state.sector_offset(sector_idx) + self.state.footer_offset();
1244        let mut buf = [0u8; SECTOR_FOOTER_SIZE];
1245        self.flash.read(offset, &mut buf).await?;
1246
1247        let footer = SectorFooter::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
1248        let sequence = self.state.sectors[sector_idx as usize].sequence;
1249        Ok(footer.describes(sequence).then_some(footer))
1250    }
1251
1252    /// Write `sector_idx`'s summary into its reserved final page. See the
1253    /// blocking driver's `write_sector_footer`.
1254    async fn write_sector_footer(&mut self, sector_idx: u16) -> Result<(), Error> {
1255        debug_assert_eq!(
1256            self.state.page_buf_offset, self.state.page_buf_durable,
1257            "a sector is sealed only with a page buffer that flash already has"
1258        );
1259
1260        let footer = SectorFooter::new(&self.state.sectors[sector_idx as usize]);
1261        let mut page = [0xFFu8; PAGE_SIZE];
1262        page[..SECTOR_FOOTER_SIZE].copy_from_slice(footer.as_bytes());
1263        let offset = self.state.sector_offset(sector_idx) + self.state.footer_offset();
1264        self.flash.write(offset, &page).await?;
1265        Ok(())
1266    }
1267
1268    async fn flush_page(&mut self) -> Result<(), Error> {
1269        let Some(addr) = self.state.commit_target() else {
1270            return Ok(());
1271        };
1272        // Phase 1: the entries still carry flags=0xFF (uncommitted).
1273        self.flash.write(addr, &self.state.page_buf).await?;
1274        // Phase 2: mark, then re-write the same page.
1275        self.state.mark_page_committed();
1276        self.flash.write(addr, &self.state.page_buf).await?;
1277        self.state.advance_page();
1278        Ok(())
1279    }
1280
1281    async fn seal_and_advance(&mut self) -> Result<(), Error> {
1282        let old_active = self.state.sealing()?;
1283
1284        // Deliberately not propagated: the footer is an optimisation and must
1285        // never make the log less usable than it would be without one. See the
1286        // blocking driver for the full argument.
1287        let _ = self.write_sector_footer(old_active).await;
1288
1289        let plan = self.state.begin_seal(old_active)?;
1290        self.erase_sector(plan.new_active).await?;
1291        self.state.account_seal(&plan);
1292        self.init_sector(plan.new_active, self.state.next_sequence, plan.erase_count)
1293            .await?;
1294        self.state.finish_seal(&plan);
1295
1296        Ok(())
1297    }
1298
1299    async fn scan_sector_entries(
1300        &mut self,
1301        sector_idx: u16,
1302    ) -> Result<(ScannedSector, u32), Error> {
1303        let sector_offset = self.state.sector_offset(sector_idx);
1304        let entry_start = SECTOR_HEADER_SIZE as u32;
1305        // Bounded by the footer offset, not the sector size: the final page
1306        // holds a summary, not entries.
1307        let mut scanner =
1308            SectorScanner::new(sector_offset, entry_start, self.state.footer_offset());
1309        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1310        let mut buf = [0u8; PAGE_SIZE];
1311
1312        let mut found = ScannedSector {
1313            write_offset: entry_start,
1314            ..ScannedSector::EMPTY
1315        };
1316
1317        while let Some(entry) =
1318            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1319        {
1320            if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut buf).await? {
1321                scanner.corrupt_count += 1;
1322                scanner.skip(1);
1323                continue;
1324            }
1325
1326            found.record(&entry, &buf[..entry.payload_len]);
1327
1328            scanner.skip(entry.entry_size);
1329            found.write_offset = scanner.offset();
1330        }
1331
1332        Ok((found, scanner.corrupt_count()))
1333    }
1334
1335    async fn find_latest_in_sector(
1336        &mut self,
1337        sector_idx: u16,
1338        target_sensor: u16,
1339        buf: &mut [u8],
1340    ) -> Result<Option<(EntryHeader, usize)>, Error> {
1341        let sector_offset = self.state.sector_offset(sector_idx);
1342        let write_offset = self.state.sectors[sector_idx as usize].write_offset;
1343        let entry_start = SECTOR_HEADER_SIZE as u32;
1344        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
1345        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1346        let mut payload_buf = [0u8; PAGE_SIZE];
1347
1348        let mut latest: Option<(EntryHeader, usize)> = None;
1349        let mut latest_ts = 0u64;
1350
1351        while let Some(entry) =
1352            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1353        {
1354            if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut payload_buf).await?
1355            {
1356                scanner.skip(1);
1357                continue;
1358            }
1359
1360            if entry.sensor_id() == target_sensor {
1361                let (header, payload) =
1362                    entry.edge(&mut payload_buf[..entry.payload_len], Edge::Last);
1363
1364                if header.timestamp >= latest_ts {
1365                    let len = payload.len();
1366                    if len > buf.len() {
1367                        return Err(Error::BufferTooSmall);
1368                    }
1369                    buf[..len].copy_from_slice(payload);
1370                    latest_ts = header.timestamp;
1371                    latest = Some((header, len));
1372                }
1373            }
1374
1375            scanner.skip(entry.entry_size);
1376        }
1377
1378        Ok(latest)
1379    }
1380
1381    #[allow(clippy::too_many_arguments)]
1382    async fn scan_sector_for_query<C>(
1383        &mut self,
1384        sector_idx: u16,
1385        sensor_filter: Option<u16>,
1386        t_start: u64,
1387        t_end: u64,
1388        buf: &mut [u8],
1389        count: &mut u32,
1390        callback: &mut C,
1391    ) -> Result<bool, Error>
1392    where
1393        C: FnMut(&EntryHeader, &[u8]) -> bool,
1394    {
1395        let sector_offset = self.state.sector_offset(sector_idx);
1396        let write_offset = self.state.sectors[sector_idx as usize].write_offset;
1397        let entry_start = SECTOR_HEADER_SIZE as u32;
1398        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
1399        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1400
1401        while let Some(entry) =
1402            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1403        {
1404            if !accept_entry_async(&mut self.flash, sector_offset, &entry, buf).await? {
1405                scanner.skip(1);
1406                continue;
1407            }
1408
1409            let sensor = entry.sensor_id();
1410
1411            if sensor_filter.is_none_or(|f| f == sensor)
1412                && deliver_samples(
1413                    entry.is_run(),
1414                    sensor,
1415                    entry.timestamp(),
1416                    &mut buf[..entry.payload_len],
1417                    t_start,
1418                    t_end,
1419                    count,
1420                    callback,
1421                )
1422            {
1423                return Ok(true);
1424            }
1425
1426            scanner.skip(entry.entry_size);
1427        }
1428
1429        Ok(false)
1430    }
1431
1432    async fn find_oldest_in_sector(
1433        &mut self,
1434        sector_idx: u16,
1435        target_sensor: u16,
1436        buf: &mut [u8],
1437    ) -> Result<Option<(EntryHeader, usize)>, Error> {
1438        let sector_offset = self.state.sector_offset(sector_idx);
1439        let write_offset = self.state.sectors[sector_idx as usize].write_offset;
1440        let entry_start = SECTOR_HEADER_SIZE as u32;
1441        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
1442        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1443        let mut payload_buf = [0u8; PAGE_SIZE];
1444
1445        while let Some(entry) =
1446            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1447        {
1448            if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut payload_buf).await?
1449            {
1450                scanner.skip(1);
1451                continue;
1452            }
1453
1454            if entry.sensor_id() == target_sensor {
1455                let (header, payload) =
1456                    entry.edge(&mut payload_buf[..entry.payload_len], Edge::First);
1457
1458                if payload.len() > buf.len() {
1459                    return Err(Error::BufferTooSmall);
1460                }
1461                buf[..payload.len()].copy_from_slice(payload);
1462                return Ok(Some((header, payload.len())));
1463            }
1464
1465            scanner.skip(entry.entry_size);
1466        }
1467
1468        Ok(None)
1469    }
1470
1471    /// Count the entries in `sector_idx` that start below `offset_limit`.
1472    ///
1473    /// Async mirror of `SensorDbState::count_entries_before`.
1474    async fn count_entries_before(
1475        &mut self,
1476        sector_idx: u16,
1477        offset_limit: u32,
1478    ) -> Result<Replicated, Error> {
1479        let sector_offset = self.state.sector_offset(sector_idx);
1480        let entry_count = self.state.sectors[sector_idx as usize].entry_count;
1481        let sample_count = self.state.sectors[sector_idx as usize].sample_count;
1482        let write_offset = self.state.sectors[sector_idx as usize].write_offset;
1483        let entry_start = SECTOR_HEADER_SIZE as u32;
1484        let limit = offset_limit.min(write_offset);
1485        if limit <= entry_start {
1486            return Ok(Replicated::NONE);
1487        }
1488
1489        let mut scanner = SectorScanner::new(sector_offset, entry_start, limit);
1490        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1491        let mut buf = [0u8; PAGE_SIZE];
1492        let mut found = Replicated::NONE;
1493
1494        while let Some(entry) =
1495            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1496        {
1497            if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut buf).await? {
1498                scanner.skip(1);
1499                continue;
1500            }
1501            found.push(samples_in(entry.is_run(), &buf[..entry.payload_len]));
1502            scanner.skip(entry.entry_size);
1503        }
1504
1505        Ok(Replicated {
1506            entries: found.entries.min(entry_count),
1507            samples: found.samples.min(sample_count),
1508        })
1509    }
1510
1511    /// Count the entries in `sector_idx` belonging to `target_sensor`.
1512    ///
1513    /// CRC-validated, matching the blocking driver's
1514    /// [`count_sensor_in_sector`](crate::SensorDb) and this driver's own query
1515    /// path: `count` and `query_range` must not disagree about how many entries
1516    /// exist.
1517    async fn count_sensor_in_sector(
1518        &mut self,
1519        sector_idx: u16,
1520        target_sensor: u16,
1521    ) -> Result<u32, Error> {
1522        let sector_offset = self.state.sector_offset(sector_idx);
1523        let write_offset = self.state.sectors[sector_idx as usize].write_offset;
1524        let entry_start = SECTOR_HEADER_SIZE as u32;
1525        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
1526        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
1527        let mut payload_buf = [0u8; PAGE_SIZE];
1528        let mut count = 0u32;
1529
1530        while let Some(entry) =
1531            next_entry_async(&mut scanner, &mut self.flash, &mut header_buf, PAGE_SIZE).await?
1532        {
1533            // Every entry is verified, not only the matching ones — see the
1534            // blocking driver for why a selective check walks the sector
1535            // differently from the read path.
1536            if !accept_entry_async(&mut self.flash, sector_offset, &entry, &mut payload_buf).await?
1537            {
1538                scanner.skip(1);
1539                continue;
1540            }
1541            if entry.sensor_id() == target_sensor {
1542                // Samples, not entries: a run answers for all of its own, which
1543                // is what `query_range` would yield for it.
1544                count += samples_in(entry.is_run(), &payload_buf[..entry.payload_len]);
1545            }
1546            scanner.skip(entry.entry_size);
1547        }
1548
1549        Ok(count)
1550    }
1551}
1552
1553// =============================================================================
1554// Capability ports
1555// =============================================================================
1556//
1557// Delegation only, spelled with UFCS — see the note on the blocking driver's
1558// impls for why the inherent method is never reached through `self.`.
1559
1560impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSinkAsync
1561    for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
1562where
1563    F: NorFlash + ReadNorFlash,
1564{
1565    fn append(
1566        &mut self,
1567        sensor_id: u16,
1568        timestamp: u64,
1569        payload: &[u8],
1570    ) -> impl core::future::Future<Output = Result<(), Error>> {
1571        SensorDbAsync::append(self, sensor_id, timestamp, payload)
1572    }
1573
1574    fn append_run(
1575        &mut self,
1576        run: &Run<'_>,
1577    ) -> impl core::future::Future<Output = Result<(), Error>> {
1578        SensorDbAsync::append_run(self, run)
1579    }
1580
1581    fn sync(&mut self) -> impl core::future::Future<Output = Result<(), Error>> {
1582        SensorDbAsync::sync(self)
1583    }
1584}
1585
1586impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSourceAsync
1587    for SensorDbAsync<F, PAGE_SIZE, MAX_SECTORS>
1588where
1589    F: NorFlash + ReadNorFlash,
1590{
1591    fn latest(
1592        &mut self,
1593        sensor_id: u16,
1594        buf: &mut [u8],
1595    ) -> impl core::future::Future<Output = Result<Option<(EntryHeader, usize)>, Error>> {
1596        SensorDbAsync::latest(self, sensor_id, buf)
1597    }
1598
1599    fn oldest(
1600        &mut self,
1601        sensor_id: u16,
1602        buf: &mut [u8],
1603    ) -> impl core::future::Future<Output = Result<Option<(EntryHeader, usize)>, Error>> {
1604        SensorDbAsync::oldest(self, sensor_id, buf)
1605    }
1606
1607    fn count(
1608        &mut self,
1609        sensor_id: Option<u16>,
1610    ) -> impl core::future::Future<Output = Result<u32, Error>> {
1611        SensorDbAsync::count(self, sensor_id)
1612    }
1613
1614    fn query_range(
1615        &mut self,
1616        sensor_id: Option<u16>,
1617        t_start: u64,
1618        t_end: u64,
1619        callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool,
1620    ) -> impl core::future::Future<Output = Result<u32, Error>> {
1621        SensorDbAsync::query_range(self, sensor_id, t_start, t_end, callback)
1622    }
1623}
1624
1625// =============================================================================
1626// Tests
1627// =============================================================================
1628
1629#[cfg(all(test, feature = "std", feature = "async"))]
1630mod tests {
1631    extern crate alloc;
1632    use alloc::vec;
1633    use alloc::vec::Vec;
1634
1635    use super::*;
1636    use crate::entry::{ENTRY_CRC_SIZE, EntryHeaderWire, FLAGS_COMMITTED, compute_entry_crc};
1637    use crate::mock::{MockFlash, MockFlashAsync, block_on};
1638
1639    const PAGE: usize = 256;
1640    const SECTOR: usize = 4096;
1641    const SECTORS: usize = 8;
1642
1643    // -------------------------------------------------------------------------
1644    // Helper
1645    // -------------------------------------------------------------------------
1646
1647    fn make_db() -> SensorDbAsync<MockFlashAsync<PAGE, SECTOR>, PAGE, SECTORS> {
1648        let flash = MockFlashAsync::<PAGE, SECTOR>::new(SECTORS * SECTOR);
1649        let mut db = SensorDbAsync::new(flash, 0, SECTORS as u16, 1).unwrap();
1650        block_on(db.format()).unwrap();
1651        db
1652    }
1653
1654    // -------------------------------------------------------------------------
1655    // Tests
1656    // -------------------------------------------------------------------------
1657
1658    #[test]
1659    fn async_format_and_mount() {
1660        let flash = MockFlashAsync::<PAGE, SECTOR>::new(SECTORS * SECTOR);
1661        let mut db: SensorDbAsync<_, PAGE, SECTORS> =
1662            SensorDbAsync::new(flash, 0, SECTORS as u16, 1).unwrap();
1663        block_on(db.format()).unwrap();
1664        assert!(db.is_mounted());
1665        assert_eq!(db.stats().total_entries, 0);
1666    }
1667
1668    #[test]
1669    fn async_append_and_latest() {
1670        let mut db = make_db();
1671        let payload = [0xDE, 0xAD, 0xBE, 0xEF];
1672        block_on(db.append(1, 1000, &payload)).unwrap();
1673        block_on(db.append(2, 1001, &[0x42])).unwrap();
1674        block_on(db.append(1, 1002, &[0x01, 0x02])).unwrap();
1675
1676        let mut buf = [0u8; 16];
1677        let (hdr, n) = block_on(db.latest(1, &mut buf)).unwrap().unwrap();
1678        assert_eq!(hdr.sensor_id, 1);
1679        assert_eq!(hdr.timestamp, 1002);
1680        assert_eq!(&buf[..n], &[0x01, 0x02]);
1681
1682        let (hdr2, n2) = block_on(db.latest(2, &mut buf)).unwrap().unwrap();
1683        assert_eq!(hdr2.sensor_id, 2);
1684        assert_eq!(&buf[..n2], &[0x42]);
1685    }
1686
1687    #[test]
1688    fn async_query_range_filters() {
1689        let mut db = make_db();
1690        block_on(db.append(1, 100, &[0x01])).unwrap();
1691        block_on(db.append(1, 200, &[0x02])).unwrap();
1692        block_on(db.append(2, 150, &[0x0A])).unwrap();
1693        block_on(db.append(1, 300, &[0x03])).unwrap();
1694        block_on(db.sync()).unwrap();
1695
1696        let mut results = Vec::new();
1697        let count = block_on(db.query_range(Some(1), 100, 250, |hdr, payload| {
1698            results.push((hdr.timestamp, payload[0]));
1699            true
1700        }))
1701        .unwrap();
1702
1703        assert_eq!(count, 2);
1704        assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
1705    }
1706
1707    #[test]
1708    fn async_survives_remount() {
1709        let flash = MockFlashAsync::<PAGE, SECTOR>::new(SECTORS * SECTOR);
1710        let mut db: SensorDbAsync<_, PAGE, SECTORS> =
1711            SensorDbAsync::new(flash, 0, SECTORS as u16, 1).unwrap();
1712        block_on(db.format()).unwrap();
1713
1714        block_on(db.append(5, 42, &[0xAA, 0xBB])).unwrap();
1715        block_on(db.append(5, 43, &[0xCC])).unwrap();
1716        block_on(db.sync()).unwrap();
1717
1718        let flash = db.into_inner();
1719        let mut db2: SensorDbAsync<_, PAGE, SECTORS> =
1720            SensorDbAsync::new(flash, 0, SECTORS as u16, 1).unwrap();
1721        let mount_stats = block_on(db2.mount()).unwrap();
1722
1723        assert_eq!(mount_stats.total_entries, 2);
1724
1725        let mut buf = [0u8; 16];
1726        let (hdr, n) = block_on(db2.latest(5, &mut buf)).unwrap().unwrap();
1727        assert_eq!(hdr.timestamp, 43);
1728        assert_eq!(&buf[..n], &[0xCC]);
1729    }
1730
1731    #[test]
1732    fn async_circular_wrap() {
1733        const SMALL: usize = 4;
1734        let flash = MockFlashAsync::<PAGE, SECTOR>::new(SMALL * SECTOR);
1735        let mut db: SensorDbAsync<_, PAGE, SMALL> =
1736            SensorDbAsync::new(flash, 0, SMALL as u16, 1).unwrap();
1737        block_on(db.format()).unwrap();
1738
1739        for i in 0..800u64 {
1740            let payload = (i as u32).to_le_bytes();
1741            block_on(db.append(1, i * 100, &payload)).unwrap();
1742        }
1743
1744        let stats = db.stats();
1745        assert!(stats.total_entries > 0);
1746        assert!(stats.used_sectors <= SMALL as u16);
1747
1748        let mut buf = [0u8; 4];
1749        let (hdr, _) = block_on(db.latest(1, &mut buf)).unwrap().unwrap();
1750        assert_eq!(hdr.timestamp, 799 * 100);
1751    }
1752
1753    #[test]
1754    fn async_compact() {
1755        let mut db = make_db();
1756        for i in 0..50u64 {
1757            block_on(db.append(1, i, &[i as u8])).unwrap();
1758        }
1759        block_on(db.sync()).unwrap();
1760
1761        let before = db.stats();
1762        let freed = block_on(db.compact(1, CompactScope::All)).unwrap();
1763        let after = db.stats();
1764
1765        if before.used_sectors > 1 {
1766            assert!(freed > 0);
1767            assert!(after.free_sectors > before.free_sectors);
1768        }
1769    }
1770
1771    #[test]
1772    fn async_oldest() {
1773        let mut db = make_db();
1774        block_on(db.append(1, 100, &[0x01])).unwrap();
1775        block_on(db.append(1, 200, &[0x02])).unwrap();
1776        block_on(db.append(1, 300, &[0x03])).unwrap();
1777        block_on(db.sync()).unwrap();
1778
1779        let mut buf = [0u8; 16];
1780        let (hdr, n) = block_on(db.oldest(1, &mut buf)).unwrap().unwrap();
1781        assert_eq!(hdr.timestamp, 100);
1782        assert_eq!(&buf[..n], &[0x01]);
1783    }
1784
1785    #[test]
1786    fn async_count() {
1787        let mut db = make_db();
1788        block_on(db.append(1, 100, &[0x01])).unwrap();
1789        block_on(db.append(2, 200, &[0x02])).unwrap();
1790        block_on(db.append(1, 300, &[0x03])).unwrap();
1791        block_on(db.sync()).unwrap();
1792
1793        assert_eq!(block_on(db.count(None)).unwrap(), 3);
1794        assert_eq!(block_on(db.count(Some(1))).unwrap(), 2);
1795        assert_eq!(block_on(db.count(Some(2))).unwrap(), 1);
1796        assert_eq!(block_on(db.count(Some(99))).unwrap(), 0);
1797    }
1798
1799    #[test]
1800    fn async_typed_api() {
1801        use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
1802
1803        #[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
1804        #[repr(C)]
1805        struct Temp {
1806            celsius: f32,
1807        }
1808
1809        impl SensorData for Temp {
1810            const SENSOR_ID: u16 = 0x01;
1811        }
1812
1813        let mut db = make_db();
1814        block_on(db.append_sensor(1000, &Temp { celsius: 25.5 })).unwrap();
1815        block_on(db.append_sensor(2000, &Temp { celsius: 26.0 })).unwrap();
1816        block_on(db.sync()).unwrap();
1817
1818        let (hdr, val) = block_on(db.latest_sensor::<Temp>()).unwrap().unwrap();
1819        assert_eq!(hdr.timestamp, 2000);
1820        assert_eq!(val.celsius, 26.0);
1821
1822        let (hdr, val) = block_on(db.oldest_sensor::<Temp>()).unwrap().unwrap();
1823        assert_eq!(hdr.timestamp, 1000);
1824        assert_eq!(val.celsius, 25.5);
1825
1826        assert_eq!(block_on(db.count_sensor::<Temp>()).unwrap(), 2);
1827    }
1828
1829    #[test]
1830    fn async_max_payload() {
1831        let mut db = make_db();
1832        let max = db.max_payload_size();
1833        let payload = vec![0x42u8; max];
1834        block_on(db.append(1, 999, &payload)).unwrap();
1835        block_on(db.sync()).unwrap();
1836
1837        let mut buf = vec![0u8; max];
1838        let (hdr, n) = block_on(db.latest(1, &mut buf)).unwrap().unwrap();
1839        assert_eq!(n, max);
1840        assert_eq!(hdr.payload_len as usize, max);
1841    }
1842
1843    #[test]
1844    fn async_rejects_oversized() {
1845        let mut db = make_db();
1846        let too_big = vec![0u8; db.max_payload_size() + 1];
1847        let result = block_on(db.append(1, 100, &too_big));
1848        assert!(result.is_err());
1849    }
1850
1851    /// Async mirror of `scanner_resyncs_past_oversized_false_marker`
1852    /// (`tests/comprehensive.rs`): the field crash that motivated this fix was in
1853    /// `verify_entry_crc_async`. A forged false marker encodes an oversized
1854    /// `payload_len` (3840) that fits the sector (4096) but dwarfs the 256-byte
1855    /// verify buffer. The async scanner must reject it on the `payload_len` bound,
1856    /// resync, and still find the valid entry that follows — no panic.
1857    #[test]
1858    fn async_scanner_resyncs_past_oversized_false_marker() {
1859        use embedded_storage::nor_flash::NorFlash as SyncNorFlash;
1860        use zerocopy::IntoBytes;
1861
1862        let mut raw = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
1863        let mut page = [0xFFu8; PAGE];
1864
1865        let sh = SectorHeader::new(None, 1, 1, 1);
1866        page[..SECTOR_HEADER_SIZE].copy_from_slice(sh.as_bytes());
1867
1868        // E1: real committed entry just after the sector header.
1869        let e1_off = SECTOR_HEADER_SIZE;
1870        let e1_payload = [0x01u8, 0x02, 0x03, 0x04];
1871        let mut e1 = EntryHeaderWire::new(1, 100, e1_payload.len() as u16);
1872        let e1_crc = compute_entry_crc(&e1, &e1_payload, e1_off as u32);
1873        e1.flags = FLAGS_COMMITTED;
1874        page[e1_off..e1_off + ENTRY_HEADER_SIZE].copy_from_slice(e1.as_bytes());
1875        page[e1_off + ENTRY_HEADER_SIZE..e1_off + ENTRY_HEADER_SIZE + e1_payload.len()]
1876            .copy_from_slice(&e1_payload);
1877        let e1_crc_off = e1_off + ENTRY_HEADER_SIZE + e1_payload.len();
1878        page[e1_crc_off..e1_crc_off + ENTRY_CRC_SIZE].copy_from_slice(&e1_crc.to_le_bytes());
1879
1880        // Forged false marker: "committed" header with payload_len = 3840.
1881        let forged_off = e1_crc_off + ENTRY_CRC_SIZE;
1882        let mut forged = EntryHeaderWire::new(1, 0, 3840);
1883        forged.flags = FLAGS_COMMITTED;
1884        page[forged_off..forged_off + ENTRY_HEADER_SIZE].copy_from_slice(forged.as_bytes());
1885
1886        // E2: real committed entry after the forged header.
1887        let e2_off = forged_off + ENTRY_HEADER_SIZE;
1888        let e2_payload = [0x11u8, 0x22, 0x33, 0x44];
1889        let mut e2 = EntryHeaderWire::new(1, 200, e2_payload.len() as u16);
1890        let e2_crc = compute_entry_crc(&e2, &e2_payload, e2_off as u32);
1891        e2.flags = FLAGS_COMMITTED;
1892        page[e2_off..e2_off + ENTRY_HEADER_SIZE].copy_from_slice(e2.as_bytes());
1893        page[e2_off + ENTRY_HEADER_SIZE..e2_off + ENTRY_HEADER_SIZE + e2_payload.len()]
1894            .copy_from_slice(&e2_payload);
1895        let e2_crc_off = e2_off + ENTRY_HEADER_SIZE + e2_payload.len();
1896        page[e2_crc_off..e2_crc_off + ENTRY_CRC_SIZE].copy_from_slice(&e2_crc.to_le_bytes());
1897
1898        raw.write(0, &page).unwrap();
1899
1900        let flash = MockFlashAsync::<PAGE, SECTOR>::wrap(raw);
1901        let mut db: SensorDbAsync<_, PAGE, SECTORS> =
1902            SensorDbAsync::new(flash, 0, SECTORS as u16, 1).unwrap();
1903        let stats = block_on(db.mount()).unwrap();
1904        assert_eq!(
1905            stats.total_entries, 2,
1906            "both real entries found, forged skipped"
1907        );
1908        assert!(
1909            stats.corrupt_entries > 0,
1910            "forged marker counted as corrupt"
1911        );
1912
1913        let mut buf = [0u8; 16];
1914        let (hdr, n) = block_on(db.latest(1, &mut buf)).unwrap().unwrap();
1915        assert_eq!(hdr.timestamp, 200);
1916        assert_eq!(&buf[..n], &e2_payload);
1917    }
1918
1919    /// Restoring a mid-sector watermark must give the same answer as the
1920    /// blocking driver — the two boundary scanners are hand-written mirrors, and
1921    /// a difference in either the scan limit or the entry-acceptance test would
1922    /// show up as a different count.
1923    #[test]
1924    fn async_restore_spool_watermark_matches_the_blocking_driver() {
1925        use crate::SensorDb;
1926
1927        let mut a = make_db();
1928        let mut b: SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS> =
1929            SensorDb::new(MockFlash::new(SECTORS * SECTOR), 0, SECTORS as u16, 1).unwrap();
1930        b.format().unwrap();
1931        for i in 0..500u64 {
1932            block_on(a.append(1, i, &[i as u8])).unwrap();
1933            b.append(1, i, &[i as u8]).unwrap();
1934        }
1935        block_on(a.sync()).unwrap();
1936        b.sync().unwrap();
1937
1938        // A run of 137 ends part-way into a sector, which is the case the
1939        // in-RAM index alone cannot answer.
1940        let tail = a.tail_position();
1941        let cut = block_on(a.read_from(tail, 137, |_, _, _| Ok(true)))
1942            .unwrap()
1943            .next;
1944        assert!(
1945            cut.offset > SECTOR_HEADER_SIZE as u32,
1946            "the watermark must fall inside a sector for this test to mean anything"
1947        );
1948
1949        block_on(a.restore_spool_watermark(cut)).unwrap();
1950        b.restore_spool_watermark(cut).unwrap();
1951
1952        assert_eq!(a.spool_stats(), b.spool_stats());
1953        let total = block_on(a.count(None)).unwrap();
1954        assert_eq!(total - a.spool_stats().unspooled_entries, 137);
1955    }
1956}