Skip to main content

sensor_db/
db.rs

1//! SensorDb implementation.
2//!
3//! Append-only sensor database for NOR flash with circular sector management.
4//!
5//! ## Usage
6//!
7//! ```ignore
8//! use sensor_db::{MockFlash, SensorDb};
9//!
10//! const PAGE: usize = 256;
11//! const SECTOR: usize = 4096;
12//! const SECTORS: usize = 32;
13//!
14//! let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
15//! let mut db: SensorDb<_, PAGE, SECTORS> = SensorDb::new(flash, 0, 32, 2).unwrap();
16//! db.format().unwrap();
17//!
18//! db.append(1, 1000, &[0xAB, 0xCD]).unwrap();
19//! let mut buf = [0u8; 16];
20//! let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
21//! assert_eq!(&buf[..n], &[0xAB, 0xCD]);
22//! ```
23
24use crate::entry::{
25    ENTRY_CRC_SIZE, ENTRY_HEADER_SIZE, ENTRY_OVERHEAD, EntryHeader, EntryHeaderWire, EntryKind,
26    FLAGS_COMMITTED, FLAGS_UNCOMMITTED, compute_entry_crc, is_entry_marker,
27};
28use crate::error::Error;
29use crate::partition::Partition;
30use crate::run::{RUN_FRAME_SIZE, Run, RunFrame, deliver_samples, samples_in};
31use crate::schema;
32use crate::sector::{
33    LogId, SECTOR_FOOTER_SIZE, SECTOR_HEADER_SIZE, SectorClass, SectorFooter, SectorHeader,
34    SectorState, SectorSummary, sensor_id_to_bit,
35};
36use crate::typed::SensorData;
37use embedded_storage::nor_flash::{NorFlash, ReadNorFlash};
38use heapless::Vec as HeaplessVec;
39use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
40
41/// Simple insertion sort for small heapless vectors (no alloc required).
42/// Sorts by the second element of the tuple using the given comparator.
43pub(crate) fn sort_by_seq<const N: usize>(
44    vec: &mut HeaplessVec<(u16, u32), N>,
45    cmp: fn(&u32, &u32) -> core::cmp::Ordering,
46) {
47    for i in 1..vec.len() {
48        let mut j = i;
49        while j > 0 && cmp(&vec[j - 1].1, &vec[j].1) == core::cmp::Ordering::Greater {
50            vec.swap(j - 1, j);
51            j -= 1;
52        }
53    }
54}
55
56/// Statistics about the database state.
57#[derive(Debug, Clone, Copy, Default)]
58#[cfg_attr(feature = "defmt", derive(defmt::Format))]
59pub struct DbStats {
60    /// Total number of valid entries across all sectors.
61    ///
62    /// *Entries*, so a [run](crate::run) counts once however many samples it
63    /// holds. This is what the log wrote and what replication moves;
64    /// [`total_samples`](Self::total_samples) is what a reader sees, and their
65    /// ratio is what run encoding bought.
66    pub total_entries: u32,
67    /// Total number of readable samples across all sectors.
68    ///
69    /// What [`count(None)`](crate::SensorDb::count) reports, and what a query
70    /// over the whole time range yields.
71    pub total_samples: u32,
72    /// Number of sectors currently in use (active or sealed).
73    pub used_sectors: u16,
74    /// Number of erased sectors available.
75    pub free_sectors: u16,
76    /// Number of reserved sectors for headroom.
77    pub reserved_sectors: u16,
78    /// Minimum erase count across all sectors.
79    pub min_erase_count: u32,
80    /// Maximum erase count across all sectors.
81    pub max_erase_count: u32,
82    /// Total erase count summed across all sectors.
83    pub total_erase_count: u64,
84}
85
86/// Geometry and identity of a database region.
87///
88/// Validated once, here, so everything downstream receives a configuration that
89/// is already known-good.
90///
91/// ```
92/// use sensor_db::db::DbConfig;
93/// use sensor_db::sector::LogId;
94///
95/// let config = DbConfig::new(0, 8, 1)?
96///     .with_log_id(LogId::new(0xC0FFEE).unwrap());
97/// # Ok::<(), sensor_db::Error>(())
98/// ```
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100#[cfg_attr(feature = "defmt", derive(defmt::Format))]
101pub struct DbConfig {
102    base_offset: u32,
103    sector_count: u16,
104    reserved_sectors: u16,
105    log_id: Option<LogId>,
106}
107
108impl DbConfig {
109    /// Describe a database region.
110    ///
111    /// # Arguments
112    /// - `base_offset`: starting byte offset of the region in flash
113    /// - `sector_count`: number of erase sectors the region spans
114    /// - `reserved_sectors`: sectors kept free as compaction headroom
115    ///
116    /// # Errors
117    /// - `InvalidConfig` if `reserved_sectors >= sector_count`
118    pub fn new(base_offset: u32, sector_count: u16, reserved_sectors: u16) -> Result<Self, Error> {
119        if reserved_sectors >= sector_count {
120            return Err(Error::InvalidConfig);
121        }
122        Ok(Self {
123            base_offset,
124            sector_count,
125            reserved_sectors,
126            log_id: None,
127        })
128    }
129
130    /// Declare this database's logical identity.
131    ///
132    /// The id is written into every sector header, and mounting a medium whose
133    /// sectors carry a *different* id fails with
134    /// [`Error::ForeignVolume`] instead of treating them as free space. Set this
135    /// on any database whose storage can be swapped between devices.
136    pub fn with_log_id(mut self, log_id: LogId) -> Self {
137        self.log_id = Some(log_id);
138        self
139    }
140
141    /// Starting byte offset of the region.
142    pub fn base_offset(&self) -> u32 {
143        self.base_offset
144    }
145
146    /// Number of erase sectors in the region.
147    pub fn sector_count(&self) -> u16 {
148        self.sector_count
149    }
150
151    /// Sectors kept free as compaction headroom.
152    pub fn reserved_sectors(&self) -> u16 {
153        self.reserved_sectors
154    }
155
156    /// Declared logical identity, if any.
157    pub fn log_id(&self) -> Option<LogId> {
158        self.log_id
159    }
160}
161
162/// Which sealed sectors [`SensorDb::compact`] may erase.
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
164#[cfg_attr(feature = "defmt", derive(defmt::Format))]
165pub enum CompactScope {
166    /// Every sealed sector is eligible, oldest first, replicated or not.
167    #[default]
168    All,
169    /// Only sealed sectors whose contents are fully replicated elsewhere.
170    ///
171    /// Reclaims space without ever destroying data that has not been copied off
172    /// the device. Erases nothing until a replica has acknowledged something —
173    /// on a log with no replica this is always a no-op.
174    SpooledOnly,
175}
176
177/// How much of the log to index when mounting.
178#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
179#[cfg_attr(feature = "defmt", derive(defmt::Format))]
180pub enum MountMode {
181    /// Rebuild the full index — entry counts, timestamp ranges and bloom
182    /// filters — reading each sealed sector's
183    /// [`SectorFooter`] where one is present and
184    /// valid, and scanning the sector body only where it is not.
185    ///
186    /// Required for reads, and the default. Cost is one page read per sealed
187    /// sector, so it is proportional to the *sector count* on a log this build
188    /// wrote. It falls back to a body scan — proportional to the data stored —
189    /// for the sector a crashed run left active, and for any sector whose footer
190    /// is missing or fails to validate.
191    ///
192    /// Because a footer records what was written rather than what is still
193    /// readable, this mode does not re-verify sealed entries and therefore
194    /// reports no [`corrupt_entries`](MountStats::corrupt_entries) for the
195    /// sectors it took from a footer. Reads are unaffected: every entry a query
196    /// returns is CRC-checked when it is read. Use [`Verify`](Self::Verify) to
197    /// check the whole medium at mount instead.
198    #[default]
199    Full,
200    /// Scan every entry of every valid sector, ignoring footers.
201    ///
202    /// Identical to [`Full`](Self::Full) in what it produces, and the only mode
203    /// that re-verifies stored data at mount: the index is built from entries
204    /// whose CRCs pass *now*, and
205    /// [`corrupt_entries`](MountStats::corrupt_entries) counts the rest. Cost is
206    /// proportional to the data stored, so a large nearly-full medium can take
207    /// seconds on a slow bus.
208    ///
209    /// This is what `Full` did before sectors carried footers.
210    Verify,
211    /// Read sector headers only, plus a full scan of the single highest-sequence
212    /// sector so appends can resume at the right offset.
213    ///
214    /// Bloom filters, per-sector entry counts and timestamp ranges are not
215    /// rebuilt, so [`latest`](SensorDb::latest), [`oldest`](SensorDb::oldest),
216    /// [`count`](SensorDb::count) and [`query_range`](SensorDb::query_range)
217    /// return [`Error::ReadsUnavailable`]. Streaming via
218    /// [`read_from`](SensorDb::read_from) still works.
219    ///
220    /// Now that sealed sectors carry footers, [`Full`](Self::Full) costs one
221    /// page read per sector where this costs one header read, so the gap is
222    /// small on a log this build wrote. What `HeadersOnly` still guarantees is
223    /// that the cost is `O(sector_count)` *unconditionally* — it never falls
224    /// back to a body scan, whatever state the medium is in. That is the reason
225    /// to keep reaching for it on a write-only replica read elsewhere.
226    HeadersOnly,
227}
228
229/// Replication accounting for a log.
230///
231/// Returned by [`SensorDb::spool_stats`]. Kept separate from [`DbStats`], which
232/// describes the sector index and means the same thing whether or not anything
233/// is replicating this log.
234#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
235#[cfg_attr(feature = "defmt", derive(defmt::Format))]
236pub struct SpoolStats {
237    /// Durable entries not yet known to be replicated elsewhere.
238    ///
239    /// Entries, which is the unit a spool pass moves and its
240    /// [budget](crate::SpoolBudget) is denominated in. For "how many readings
241    /// are still only here", see
242    /// [`unspooled_samples`](Self::unspooled_samples).
243    pub unspooled_entries: u32,
244    /// Durable *samples* not yet known to be replicated elsewhere.
245    ///
246    /// Larger than [`unspooled_entries`](Self::unspooled_entries) when the
247    /// un-replicated tail holds [runs](crate::run).
248    pub unspooled_samples: u32,
249    /// Everything strictly before this position is durably replicated.
250    pub watermark: LogPosition,
251    /// Position after the newest entry.
252    pub head: LogPosition,
253    /// Entries the ring overwrote before they could be replicated.
254    ///
255    /// Counted against the watermark *as it stood at the time of the eviction*.
256    /// Because [`mount`](SensorDb::mount) starts every run with the watermark at
257    /// [`LogPosition::BEGINNING`], data overwritten before a replica reappears
258    /// and calls [`restore_spool_watermark`](SensorDb::restore_spool_watermark)
259    /// is counted here even if a replica already had it. Attach early in boot,
260    /// or seed the watermark from wherever the application stashed it.
261    pub dropped_unspooled: u32,
262    /// Sticky: set once any un-replicated data has been overwritten, never
263    /// cleared. Surface this to the operator — it means data may have been lost.
264    ///
265    /// On a log that never replicates, *everything* is un-replicated, so this
266    /// becomes true the first time the ring wraps. That is accurate but rarely
267    /// interesting: `SpoolStats` is only meaningful for a log with a replica.
268    pub data_lost: bool,
269}
270
271/// How much one replication step carried, in both units the accounting needs.
272///
273/// A pair rather than two arguments because they are trivially transposable and
274/// a swap would be silent: entries drive the eviction and budget arithmetic,
275/// samples drive `count`.
276#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
277#[cfg_attr(feature = "defmt", derive(defmt::Format))]
278pub struct Replicated {
279    /// Entries copied.
280    pub entries: u32,
281    /// Samples those entries hold; equal to `entries` unless runs were copied.
282    pub samples: u32,
283}
284
285impl Replicated {
286    /// Nothing carried.
287    pub const NONE: Self = Self {
288        entries: 0,
289        samples: 0,
290    };
291
292    /// `n` entries holding one sample each — what a log with no runs in it
293    /// carries, and the shape a caller driving replication by hand usually has.
294    pub const fn singles(n: u32) -> Self {
295        Self {
296            entries: n,
297            samples: n,
298        }
299    }
300
301    /// Record one more entry holding `samples` samples.
302    pub fn push(&mut self, samples: u32) {
303        self.entries = self.entries.saturating_add(1);
304        self.samples = self.samples.saturating_add(samples);
305    }
306}
307
308/// A position in the log: sector sequence plus byte offset within that sector.
309///
310/// Sequence numbers are monotonic for the lifetime of a database, so ordering
311/// `LogPosition` lexicographically — which is what the derived `Ord` does — is
312/// exactly log order. This is the coordinate system used to resume a replication
313/// stream across reboots and across removals of the destination medium.
314///
315/// A position is *not* portable between databases: sequence numbers are
316/// allocated per database, so a position from one log means nothing in another.
317#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default, Hash)]
318#[cfg_attr(feature = "defmt", derive(defmt::Format))]
319pub struct LogPosition {
320    /// Sequence number of the sector this position falls in.
321    pub sequence: u32,
322    /// Byte offset within that sector.
323    pub offset: u32,
324}
325
326impl LogPosition {
327    /// A position before every entry the log has ever held.
328    ///
329    /// Real sector sequences start at 1, so sequence 0 is an unambiguous
330    /// sentinel. Reading from `BEGINNING` yields whatever the log still
331    /// retains, and never reports a gap.
332    pub const BEGINNING: Self = Self {
333        sequence: 0,
334        offset: 0,
335    };
336}
337
338/// Outcome of a [`SensorDb::read_from`] pass.
339#[derive(Debug, Clone, Copy, PartialEq, Eq)]
340#[cfg_attr(feature = "defmt", derive(defmt::Format))]
341pub struct ReadCursor {
342    /// Position immediately after the last entry delivered — pass this back as
343    /// `from` to continue where this pass stopped.
344    pub next: LogPosition,
345    /// Number of entries delivered to the callback in this pass.
346    pub entries: u32,
347    /// No further durable entries exist after [`next`](Self::next).
348    ///
349    /// False when the pass stopped because it hit `max_entries` or because the
350    /// callback asked to stop.
351    pub exhausted: bool,
352    /// The requested `from` had already fallen off the tail of the ring, so
353    /// entries between it and the oldest retained sector were skipped.
354    ///
355    /// This is not an error: it is the expected consequence of the log wrapping
356    /// while a replication target was unavailable.
357    pub gap: bool,
358}
359
360/// Statistics returned after mounting.
361#[derive(Debug, Clone, Copy, Default)]
362#[cfg_attr(feature = "defmt", derive(defmt::Format))]
363pub struct MountStats {
364    /// Total entries found during scan.
365    pub total_entries: u32,
366    /// Total readable samples found during scan, which exceeds
367    /// [`total_entries`](Self::total_entries) by what the log's
368    /// [runs](crate::run) hold.
369    pub total_samples: u32,
370    /// Number of sealed sectors found.
371    pub sealed_sectors: u16,
372    /// Number of corrupt entries skipped.
373    ///
374    /// Only sectors this mount actually read end to end can contribute: a
375    /// sector indexed from its [`SectorFooter`] is
376    /// not re-verified. See [`MountMode::Full`] and [`MountMode::Verify`].
377    pub corrupt_entries: u32,
378    /// Sector bodies this mount read end to end, rather than indexing from a
379    /// footer or skipping.
380    ///
381    /// This is the number that says what the footers bought: it is the mount
382    /// cost that scales with *data stored* instead of with sector count. On a
383    /// medium written entirely by this build it is 1 — the sector the last run
384    /// left active.
385    pub scanned_sectors: u16,
386}
387
388/// A parsed entry returned by [`SectorScanner`] (and its async twin).
389pub(crate) struct ScannedEntry {
390    /// The wire-format header.
391    pub(crate) header: EntryHeaderWire,
392    /// Byte offset of this entry within the sector.
393    pub(crate) offset_in_sector: u32,
394    /// Payload length in bytes.
395    pub(crate) payload_len: usize,
396    /// Total entry size (header + payload + CRC).
397    pub(crate) entry_size: u32,
398}
399
400impl ScannedEntry {
401    /// Whether this entry holds a [run](crate::run).
402    pub(crate) fn is_run(&self) -> bool {
403        self.header.is_run()
404    }
405
406    /// The sensor id, which every sample of a run shares.
407    pub(crate) fn sensor_id(&self) -> u16 {
408        self.header.sensor_id.get()
409    }
410
411    /// The header timestamp, which for a run is its *first* sample's.
412    pub(crate) fn timestamp(&self) -> u64 {
413        self.header.timestamp.get()
414    }
415}
416
417/// One whole entry found in the RAM page buffer.
418struct BufferedEntry {
419    header: EntryHeaderWire,
420    payload_start: usize,
421    payload_len: usize,
422}
423
424/// Which end of an entry a single-entry read wants: for a run, its first or its
425/// last sample, which are its oldest and newest.
426#[derive(Clone, Copy)]
427pub(crate) enum Edge {
428    First,
429    Last,
430}
431
432/// One chosen sample, located in the page buffer and not yet framed.
433///
434/// `latest` picks a winner across the whole buffer and copies once, so the
435/// choice and the copy have to be separable.
436#[derive(Clone, Copy)]
437struct BufferedSample {
438    payload_start: usize,
439    payload_len: usize,
440    /// The run this sample came from, and which sample it is. `None` for a
441    /// single-sample entry, whose payload is already exactly what to hand back.
442    run: Option<(RunFrame, u32)>,
443}
444
445impl BufferedEntry {
446    fn is_committed(&self) -> bool {
447        self.header.flags == FLAGS_COMMITTED
448    }
449
450    fn is_run(&self) -> bool {
451        self.header.is_run()
452    }
453
454    fn sensor_id(&self) -> u16 {
455        self.header.sensor_id.get()
456    }
457
458    fn timestamp(&self) -> u64 {
459        self.header.timestamp.get()
460    }
461}
462
463/// What a body scan learned about one sector.
464///
465/// Exactly the fields a [`SectorFooter`] carries, which is the point: mount
466/// takes whichever is available and nothing downstream can tell which.
467#[derive(Debug, Clone, Copy)]
468pub(crate) struct ScannedSector {
469    pub(crate) entries: u32,
470    pub(crate) samples: u32,
471    pub(crate) write_offset: u32,
472    pub(crate) min_timestamp: u64,
473    pub(crate) max_timestamp: u64,
474    pub(crate) sensor_bloom: u64,
475}
476
477impl ScannedSector {
478    /// A sector with nothing in it, with the bounds inverted so the first entry
479    /// scanned sets both.
480    pub(crate) const EMPTY: Self = Self {
481        entries: 0,
482        samples: 0,
483        write_offset: 0,
484        min_timestamp: u64::MAX,
485        max_timestamp: 0,
486        sensor_bloom: 0,
487    };
488
489    /// Fold one accepted entry into the running scan.
490    ///
491    /// Pure, and shared by both drivers: a run reaches past its header
492    /// timestamp, and the index has to know it — otherwise a query for the run's
493    /// tail prunes away the very sector the run lives in.
494    pub(crate) fn record(&mut self, entry: &ScannedEntry, payload: &[u8]) {
495        let base = entry.timestamp();
496        let span_end = match RunFrame::parse(payload).filter(|_| entry.is_run()) {
497            Some(frame) => {
498                self.samples += frame.count();
499                frame.span_end(base)
500            }
501            None => {
502                self.samples += 1;
503                base
504            }
505        };
506
507        self.entries += 1;
508        self.min_timestamp = self.min_timestamp.min(base);
509        self.max_timestamp = self.max_timestamp.max(span_end);
510        self.sensor_bloom |= sensor_id_to_bit(entry.sensor_id());
511    }
512
513    /// Copy the scan's findings into `summary`, leaving `state`, `sequence` and
514    /// `erase_count` — which come from the sector *header* — alone.
515    pub(crate) fn apply_to(&self, summary: &mut SectorSummary) {
516        summary.entry_count = self.entries;
517        summary.sample_count = self.samples;
518        summary.write_offset = self.write_offset;
519        summary.min_timestamp = self.min_timestamp;
520        summary.max_timestamp = self.max_timestamp;
521        summary.sensor_bloom = self.sensor_bloom;
522    }
523}
524
525/// What a [`SectorScanner`] needs next, or what it found.
526///
527/// This is the whole reason the scanner is I/O-free: the decisions it makes —
528/// where to resume after a bad byte, when an erased region ends the scan, which
529/// headers to reject before their `payload_len` is trusted — are identical for
530/// the blocking and async drivers, and a sector walked differently by two of
531/// them is exactly how `count` and `query_range` came to disagree once before.
532/// Stating the decisions once and letting each driver supply only the read is
533/// what makes that class of drift impossible rather than merely tested for.
534pub(crate) enum Scan {
535    /// Read [`ENTRY_HEADER_SIZE`] bytes at this **absolute** flash address, then
536    /// hand them to [`SectorScanner::feed`].
537    Read(u32),
538    /// A committed entry, at the scanner's current offset.
539    Found(ScannedEntry),
540    /// The sector is exhausted.
541    Done,
542}
543
544/// Stateful, I/O-free cursor that walks committed entry headers within a single
545/// sector.
546///
547/// Drive it with [`begin`](Self::begin) and [`feed`](Self::feed); each driver
548/// wraps those in a small loop that performs the reads
549/// ([`SectorScanner::next_entry`] here, its `.await`ing twin in
550/// [`async_db`](crate::async_db)).
551pub(crate) struct SectorScanner {
552    /// Absolute flash address of the sector start.
553    sector_offset: u32,
554    /// Current read position (relative to sector start).
555    offset: u32,
556    /// Upper bound for scanning (typically `write_offset` or `sector_size`).
557    limit: u32,
558    /// Number of corrupt/invalid bytes skipped.
559    pub(crate) corrupt_count: u32,
560}
561
562impl SectorScanner {
563    pub(crate) fn new(sector_offset: u32, entry_start: u32, limit: u32) -> Self {
564        Self {
565            sector_offset,
566            offset: entry_start,
567            limit,
568            corrupt_count: 0,
569        }
570    }
571
572    /// Current byte offset within the sector.
573    pub(crate) fn offset(&self) -> u32 {
574        self.offset
575    }
576
577    /// Number of corrupt/invalid bytes encountered so far.
578    pub(crate) fn corrupt_count(&self) -> u32 {
579        self.corrupt_count
580    }
581
582    /// Advance past an entry of the given size.
583    pub(crate) fn skip(&mut self, entry_size: u32) {
584        self.offset += entry_size;
585    }
586
587    /// What to read next from the current position, or `Done` if no entry can
588    /// still fit before the limit.
589    pub(crate) fn begin(&self) -> Scan {
590        if self.offset + ENTRY_OVERHEAD as u32 > self.limit {
591            return Scan::Done;
592        }
593        Scan::Read(self.sector_offset + self.offset)
594    }
595
596    /// Interpret the header bytes just read, and say what comes next.
597    ///
598    /// Skips erased regions (jumping to the next page boundary) and uncommitted
599    /// entries, and resyncs one byte forward past anything that does not parse.
600    pub(crate) fn feed(&mut self, header_buf: &[u8; ENTRY_HEADER_SIZE], page_size: usize) -> Scan {
601        // Erased area — skip to next page boundary
602        if header_buf[0] == 0xFF {
603            let next_page = ((self.offset as usize / page_size) + 1) * page_size;
604            if next_page as u32 + ENTRY_OVERHEAD as u32 > self.limit {
605                return Scan::Done;
606            }
607            self.offset = next_page as u32;
608            return self.begin();
609        }
610
611        // Not a valid marker — skip one byte
612        if !is_entry_marker(header_buf[0]) {
613            return self.resync();
614        }
615
616        let Ok(header) = EntryHeaderWire::read_from_bytes(&header_buf[..]) else {
617            return self.resync();
618        };
619
620        let payload_len = header.payload_len.get() as usize;
621
622        // Validate the header before trusting its length. The marker byte
623        // (0xAA) occurs naturally inside payload data, so matching it alone is
624        // not enough: without validation a false marker yields a garbage
625        // `payload_len` that desyncs the scan and — via `accept_entry` —
626        // slices a fixed buffer out of bounds. We reject on three grounds, in
627        // increasing cost: `flags` must be exactly COMMITTED or UNCOMMITTED
628        // (the header CRC masks flags, so it cannot vouch for them); the
629        // payload must fit within a page (defends against a CRC collision that
630        // still yields an impossible length); and the header CRC must match,
631        // which rejects false markers structurally rather than heuristically.
632        // On any failure, treat it as a stray byte and resync one byte forward.
633        let max_payload = page_size.saturating_sub(ENTRY_OVERHEAD);
634        if (header.flags != FLAGS_COMMITTED && header.flags != FLAGS_UNCOMMITTED)
635            || payload_len > max_payload
636            || !header.header_crc_valid()
637        {
638            return self.resync();
639        }
640
641        let entry_size = (ENTRY_OVERHEAD + payload_len) as u32;
642
643        if self.offset + entry_size > self.limit {
644            return Scan::Done;
645        }
646
647        // Skip uncommitted entries (power loss before commit)
648        if header.flags != FLAGS_COMMITTED {
649            self.offset += entry_size;
650            return self.begin();
651        }
652
653        Scan::Found(ScannedEntry {
654            header,
655            offset_in_sector: self.offset,
656            payload_len,
657            entry_size,
658        })
659    }
660
661    /// Count a bad byte and step over it.
662    fn resync(&mut self) -> Scan {
663        self.corrupt_count += 1;
664        self.offset += 1;
665        self.begin()
666    }
667
668    /// Read the next committed entry header from flash.
669    ///
670    /// The blocking driver's loop over [`begin`](Self::begin) and
671    /// [`feed`](Self::feed) — everything it decides lives there, so this is only
672    /// the read.
673    fn next_entry<F: ReadNorFlash>(
674        &mut self,
675        flash: &mut F,
676        header_buf: &mut [u8; ENTRY_HEADER_SIZE],
677        page_size: usize,
678    ) -> Result<Option<ScannedEntry>, Error> {
679        let mut step = self.begin();
680        loop {
681            match step {
682                Scan::Done => return Ok(None),
683                Scan::Found(entry) => return Ok(Some(entry)),
684                Scan::Read(addr) => {
685                    flash.read(addr, &mut header_buf[..])?;
686                    step = self.feed(header_buf, page_size);
687                }
688            }
689        }
690    }
691}
692
693/// Whether an entry's stored bytes are the ones that were written.
694///
695/// Two tests, and every scan applies both so that they all walk a sector
696/// identically — `count` and `query_range` disagreeing about how many entries
697/// exist is a defect, not an optimisation:
698///
699/// - the entry CRC must match, which is what says these bytes are the ones that
700///   were written;
701/// - a *run* must additionally carry a well-formed [`RunFrame`], because the
702///   scans downstream index by its sample count and span. Only a writer this
703///   crate does not have could produce a run that fails this, so it is a
704///   structural backstop rather than a case that arises — and rejecting it here
705///   means every caller handles it by the resync it already performs for a bad
706///   CRC.
707impl ScannedEntry {
708    /// The header and payload of this entry's first or last sample.
709    ///
710    /// For an ordinary entry both edges are the entry itself. For a run they are
711    /// its first and last samples — which are its oldest and newest, because the
712    /// interval is unsigned and a run's timestamps therefore never decrease.
713    ///
714    /// Shared by `latest` and `oldest` in both drivers, so the run/single
715    /// distinction is drawn once rather than in four places.
716    pub(crate) fn edge<'a>(&self, payload: &'a mut [u8], edge: Edge) -> (EntryHeader, &'a [u8]) {
717        // `RunFrame` borrows nothing, so the immutable parse ends before
718        // `tagged_sample` takes the buffer mutably.
719        match RunFrame::parse(payload).filter(|_| self.is_run()) {
720            Some(frame) => {
721                let index = match edge {
722                    Edge::First => 0,
723                    Edge::Last => frame.count() - 1,
724                };
725                (
726                    frame.header_at(self.sensor_id(), self.timestamp(), index),
727                    frame.tagged_sample(payload, index),
728                )
729            }
730            None => (self.header.to_header(), payload),
731        }
732    }
733
734    /// Where this entry's payload and CRC live, and how many bytes that is.
735    ///
736    /// Absolute address, so a driver can read it without knowing the layout.
737    pub(crate) fn payload_read(&self, sector_offset: u32) -> (u32, usize) {
738        (
739            sector_offset + self.offset_in_sector + ENTRY_HEADER_SIZE as u32,
740            self.payload_len + ENTRY_CRC_SIZE,
741        )
742    }
743
744    /// Verify the bytes [`payload_read`](Self::payload_read) asked for.
745    ///
746    /// `buf` holds `payload_len` payload bytes followed by the stored CRC.
747    pub(crate) fn accept(&self, buf: &[u8]) -> bool {
748        let stored_crc = u32::from_le_bytes([
749            buf[self.payload_len],
750            buf[self.payload_len + 1],
751            buf[self.payload_len + 2],
752            buf[self.payload_len + 3],
753        ]);
754        let computed_crc = compute_entry_crc(
755            &self.header,
756            &buf[..self.payload_len],
757            self.offset_in_sector,
758        );
759
760        if stored_crc != computed_crc {
761            return false;
762        }
763
764        !self.is_run() || RunFrame::parse(&buf[..self.payload_len]).is_some()
765    }
766}
767
768/// Read an entry's payload into `buf` and decide whether to accept it.
769///
770/// The blocking driver's read around [`ScannedEntry::accept`]; the async driver
771/// has the same four lines with an `.await`.
772///
773/// On success returns `true` and `buf[..entry.payload_len]` holds the payload.
774fn accept_entry<F: ReadNorFlash>(
775    flash: &mut F,
776    sector_offset: u32,
777    entry: &ScannedEntry,
778    buf: &mut [u8],
779) -> Result<bool, Error> {
780    let (addr, read_len) = entry.payload_read(sector_offset);
781    // Defensive: never slice past the caller's buffer on a malformed entry.
782    // The scanner already bounds `payload_len` to a page, but treat an
783    // oversized length as a CRC failure rather than panicking.
784    if read_len > buf.len() {
785        return Ok(false);
786    }
787    flash.read(addr, &mut buf[..read_len])?;
788    Ok(entry.accept(buf))
789}
790
791/// What a seal has decided, between the parts of it that touch flash.
792///
793/// [`begin_seal`](SensorDbState::begin_seal) produces it, the driver performs
794/// the erase and the header write, and
795/// [`finish_seal`](SensorDbState::finish_seal) consumes it — so the sequencing
796/// is the only thing each driver states for itself.
797pub(crate) struct SealPlan {
798    /// The sector being erased and made active.
799    pub(crate) new_active: u16,
800    /// Its erase count after this erase, carried over from the victim.
801    pub(crate) erase_count: u32,
802    /// The victim as it stood before the erase, for eviction accounting.
803    victim: SectorSummary,
804}
805
806/// What has to happen on flash before an entry can be staged.
807///
808/// [`plan_append`](SensorDbState::plan_append) decides; each driver's loop only
809/// performs. The decision is subtle enough to be worth stating once: an entry
810/// never spans a page, sealing does *not* hand back an empty page (page 0
811/// carries the 28-byte sector header), and a maximum-size entry therefore has to
812/// start on page 1 — which is why the driver loops rather than checking once.
813/// Checking once wrote such an entry at offset `SECTOR_HEADER_SIZE` of a
814/// `PAGE_SIZE` buffer and panicked on the slice index, reachable from a plain
815/// `append` of exactly the documented maximum payload.
816pub(crate) enum AppendStep {
817    /// There is room — call [`stage_entry`](SensorDbState::stage_entry).
818    Stage,
819    /// Close the current page, then ask again.
820    FlushPage,
821    /// Seal the active sector and advance, then ask again.
822    Seal,
823}
824
825/// Internal state of the sensor database (everything except the flash device).
826///
827/// Separated from [`SensorDb`] so a method can borrow `flash` and `state`
828/// disjointly — the flash-touching helpers take `&mut F` alongside `&mut self`,
829/// which the borrow checker only permits across two fields.
830///
831/// Shared verbatim with [`SensorDbAsync`](crate::SensorDbAsync), and it holds
832/// the **logic**, not merely the fields.
833///
834/// `embedded-storage` and `embedded-storage-async` are unrelated trait families,
835/// so the async driver cannot call a helper that takes a sync `&mut F`. It used
836/// to answer that by reimplementing the algorithm — 80% of `async_db.rs` was a
837/// line-for-line copy — which is worse than it sounds: the async test suite is
838/// largely byte-for-byte *parity* assertions against the blocking driver, so a
839/// defect present in both is invisible to it by construction.
840///
841/// So each flash-touching operation is split: the decisions live here, pure, and
842/// each driver contributes only the reads and writes between them. `flush_page`
843/// is [`commit_target`](Self::commit_target) →
844/// [`mark_page_committed`](Self::mark_page_committed) →
845/// [`advance_page`](Self::advance_page) with two writes interleaved;
846/// `seal_and_advance` is [`sealing`](Self::sealing) →
847/// [`begin_seal`](Self::begin_seal) → [`account_seal`](Self::account_seal) →
848/// [`finish_seal`](Self::finish_seal); `append_entry` is a loop over
849/// [`plan_append`](Self::plan_append) ending in
850/// [`stage_entry`](Self::stage_entry); and the scan itself is
851/// [`SectorScanner::feed`].
852///
853/// **A driver method that is more than I/O choreography belongs here instead.**
854pub(crate) struct SensorDbState<const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
855    pub(crate) base_offset: u32,
856    pub(crate) sector_count: u16,
857    pub(crate) reserved_sectors: u16,
858    pub(crate) sector_size: u32,
859    pub(crate) sectors: [SectorSummary; MAX_SECTORS],
860    pub(crate) active_sector: Option<u16>,
861    pub(crate) page_buf: [u8; PAGE_SIZE],
862    pub(crate) page_buf_offset: usize,
863    /// Bytes of `page_buf` below this offset are already durable on flash.
864    ///
865    /// Non-zero only after a `mount` that adopted a partially filled page: every
866    /// successful flush empties the buffer. This — not the flags byte — is what
867    /// says whether a buffered entry is safe on flash. `flush_page` flips flags
868    /// to committed *in RAM* before writing them, so a failed commit pass leaves
869    /// the buffer claiming a durability that flash does not have.
870    pub(crate) page_buf_durable: usize,
871    pub(crate) page_flash_offset: u32,
872    pub(crate) mounted: bool,
873    pub(crate) next_sequence: u32,
874    /// Valid entries the ring holds — the unit replication and eviction work in.
875    pub(crate) total_entries: u32,
876    /// Readable samples the ring holds, which exceeds `total_entries` by what
877    /// its [runs](crate::run) hold.
878    ///
879    /// Kept alongside rather than replacing it because the two answer different
880    /// questions: a spool pass moves *entries* and its budget is in entries,
881    /// while `count` and `query_range` speak in samples. Collapsing them would
882    /// make one of the two silently wrong the moment a run is written.
883    pub(crate) total_samples: u32,
884    /// Declared identity of this log, written into every sector header.
885    pub(crate) log_id: Option<LogId>,
886    /// Incremented once per mount; disambiguates boot-relative timestamps.
887    pub(crate) epoch: u32,
888    /// This run adopted a sector an earlier run created, so its epoch is not yet
889    /// recorded anywhere on the medium.
890    ///
891    /// Cleared by rolling to a fresh sector, which stamps it. Deferred to the
892    /// first append so that a run which only reads costs nothing.
893    pub(crate) epoch_pending: bool,
894    /// How much of the index this mount rebuilt.
895    pub(crate) mount_mode: MountMode,
896    /// Everything strictly before this position is durably replicated elsewhere.
897    ///
898    /// Not persisted here: the replica is the source of truth, and it restores
899    /// this via [`SensorDb::restore_spool_watermark`] when it reappears. That is
900    /// what lets two media be rotated against one log with no local state.
901    pub(crate) spool_watermark: LogPosition,
902    /// Entries counted as replicated, mirroring `total_entries` accounting.
903    pub(crate) spooled_entries: u32,
904    /// Samples counted as replicated, mirroring `total_samples` accounting.
905    ///
906    /// The pair moves together everywhere `spooled_entries` does, because a
907    /// tiered `count` needs "how many samples are *not* yet on the card" and
908    /// the entry figure cannot answer it once runs exist.
909    pub(crate) spooled_samples: u32,
910    /// Entries the ring overwrote before they could be replicated.
911    pub(crate) dropped_unspooled: u32,
912    /// Sector erases this instance has performed, saturating.
913    ///
914    /// An erase costs 100 ms or more on many NOR parts, against microseconds for
915    /// a page write, so it is the one operation whose latency a caller may need
916    /// to see. Counted here rather than derived from the per-sector erase counts
917    /// in [`DbStats`] because those are a *wear* history that survives remounts
918    /// and says nothing about when the erases happened.
919    pub(crate) sectors_erased: u32,
920}
921
922/// Compile-time check that a driver's write granularity divides `PAGE_SIZE`.
923///
924/// The database writes a page at a time, so a `PAGE_SIZE` the driver cannot
925/// express as a whole number of writes fails at the first flush with
926/// `NotAligned` — a geometry mistake reported as a runtime I/O error, on a
927/// device, long after the type that caused it was chosen.
928///
929/// The check is a *multiple*, not equality, because `embedded-storage`'s
930/// `WRITE_SIZE` is the minimum write **granularity** and not the program-page
931/// size: several HALs report 1, which divides every `PAGE_SIZE`. The other half
932/// of the contract — that `PAGE_SIZE` not exceed the part's physical program
933/// page — cannot be checked here, because the trait does not carry it.
934///
935/// An associated const rather than a bare `const` block, which cannot name the
936/// generic parameters it would need. Instantiating it in a constructor is what
937/// forces evaluation.
938pub(crate) struct Geometry<F: ?Sized, const PAGE_SIZE: usize>(core::marker::PhantomData<F>);
939
940impl<F: NorFlash + ?Sized, const PAGE_SIZE: usize> Geometry<F, PAGE_SIZE> {
941    /// Fails the build when `PAGE_SIZE` is not a whole number of writes.
942    pub(crate) const PAGE_IS_WRITABLE: () = assert!(
943        PAGE_SIZE.is_multiple_of(F::WRITE_SIZE),
944        "PAGE_SIZE must be a multiple of the flash driver's WRITE_SIZE",
945    );
946}
947
948impl<const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbState<PAGE_SIZE, MAX_SECTORS> {
949    /// Validate the geometry and build the initial (unmounted) state.
950    ///
951    /// Shared by both `SensorDb::new` and `SensorDbAsync::new` so the geometry
952    /// rules are stated exactly once.
953    ///
954    /// # Errors
955    /// - `TooManySectors` if `sector_count > MAX_SECTORS`
956    /// - `InvalidConfig` if a sector is smaller than three pages
957    /// - `Overflow` if the region does not fit in a `u32` address space
958    pub(crate) fn new(config: DbConfig, sector_size: u32) -> Result<Self, Error> {
959        if config.sector_count as usize > MAX_SECTORS {
960            return Err(Error::TooManySectors);
961        }
962
963        // Page 0 carries the sector header, the last page carries the footer,
964        // and an entry of the documented maximum payload needs a whole page to
965        // itself. Below three pages a sector could be initialised and then have
966        // nowhere to put a legal entry, which `append` could only report as
967        // `PayloadTooLarge` — a geometry mistake dressed up as a call mistake.
968        if sector_size < 3 * PAGE_SIZE as u32 {
969            return Err(Error::InvalidConfig);
970        }
971
972        let total_size = (config.sector_count as u32)
973            .checked_mul(sector_size)
974            .ok_or(Error::Overflow)?;
975        config
976            .base_offset
977            .checked_add(total_size)
978            .ok_or(Error::Overflow)?;
979
980        Ok(Self {
981            base_offset: config.base_offset,
982            sector_count: config.sector_count,
983            reserved_sectors: config.reserved_sectors,
984            sector_size,
985            sectors: [SectorSummary::default(); MAX_SECTORS],
986            active_sector: None,
987            page_buf: [0xFF; PAGE_SIZE],
988            page_buf_offset: 0,
989            page_buf_durable: 0,
990            page_flash_offset: 0,
991            mounted: false,
992            next_sequence: 1,
993            total_entries: 0,
994            total_samples: 0,
995            log_id: config.log_id,
996            epoch: 1,
997            epoch_pending: false,
998            mount_mode: MountMode::Full,
999            spool_watermark: LogPosition::BEGINNING,
1000            spooled_entries: 0,
1001            spooled_samples: 0,
1002            dropped_unspooled: 0,
1003            sectors_erased: 0,
1004        })
1005    }
1006
1007    /// The raw `log_id` this database expects, 0 when anonymous.
1008    pub(crate) fn log_id_raw(&self) -> u32 {
1009        self.log_id.map_or(0, LogId::get)
1010    }
1011
1012    /// Gate for query methods: mounted, and with an index good enough to answer.
1013    ///
1014    /// A [`MountMode::HeadersOnly`] mount deliberately skips the per-sector
1015    /// entry counts, timestamp ranges and bloom filters that every query relies
1016    /// on, so those queries must refuse rather than quietly return a subset.
1017    /// Streaming via `read_from` still works, because it reads flash directly.
1018    pub(crate) fn require_reads(&self) -> Result<(), Error> {
1019        if !self.mounted {
1020            return Err(Error::NotMounted);
1021        }
1022        if self.mount_mode == MountMode::HeadersOnly {
1023            return Err(Error::ReadsUnavailable);
1024        }
1025        Ok(())
1026    }
1027
1028    /// Build a sector header carrying this database's identity and epoch.
1029    pub(crate) fn sector_header(&self, sequence: u32, erase_count: u32) -> SectorHeader {
1030        SectorHeader::new(self.log_id, self.epoch, sequence, erase_count)
1031    }
1032
1033    /// Whether a sealed sector's contents are entirely replicated.
1034    ///
1035    /// Derived rather than stored, so there is no second copy of the truth to
1036    /// keep in sync. The comparison is strict: if the watermark falls *inside*
1037    /// sector `S`, every sector below `S` is fully replicated and `S` is not.
1038    pub(crate) fn is_fully_spooled(&self, summary: &SectorSummary) -> bool {
1039        summary.sequence < self.spool_watermark.sequence
1040    }
1041
1042    /// Apply the accounting for a sector whose contents have just been erased.
1043    ///
1044    /// Called *after* the erase succeeds, never before: an erase that fails must
1045    /// not leave the index claiming data is gone, and must not report a loss
1046    /// that did not happen.
1047    pub(crate) fn account_eviction(&mut self, victim: &SectorSummary) {
1048        let entries = victim.entry_count;
1049        let samples = victim.sample_count;
1050        self.total_entries = self.total_entries.saturating_sub(entries);
1051        self.total_samples = self.total_samples.saturating_sub(samples);
1052        if self.is_fully_spooled(victim) {
1053            self.spooled_entries = self.spooled_entries.saturating_sub(entries);
1054            self.spooled_samples = self.spooled_samples.saturating_sub(samples);
1055            return;
1056        }
1057
1058        // The victim is the sector the watermark falls inside, or one above it.
1059        // In the first case part of it *was* replicated and is counted in
1060        // `spooled_entries`; only the rest is a loss. The split is recoverable
1061        // without a scan: whatever stays replicated is exactly what the other
1062        // fully-spooled sectors hold, so the remainder is the victim's share.
1063        // Charging the whole sector to `dropped_unspooled` would report a loss
1064        // of data a replica demonstrably has.
1065        let spooled_elsewhere = self.spooled_in_whole_sectors();
1066        let victim_share = self.spooled_entries.saturating_sub(spooled_elsewhere);
1067        self.spooled_entries = spooled_elsewhere;
1068        self.dropped_unspooled = self
1069            .dropped_unspooled
1070            .saturating_add(entries.saturating_sub(victim_share));
1071
1072        // The same split, in samples. `dropped_unspooled` stays in entries: it
1073        // reports loss against the replication budget, which is entry-shaped.
1074        let samples_elsewhere = self.spooled_samples_in_whole_sectors();
1075        self.spooled_samples = samples_elsewhere;
1076    }
1077
1078    /// Entries held by retained sectors that lie entirely below the watermark.
1079    ///
1080    /// Excludes the sector the watermark falls inside, whose replicated prefix
1081    /// the in-RAM index cannot measure.
1082    fn spooled_in_whole_sectors(&self) -> u32 {
1083        self.fold_whole_spooled_sectors(|s| s.entry_count)
1084    }
1085
1086    /// The same, in samples.
1087    fn spooled_samples_in_whole_sectors(&self) -> u32 {
1088        self.fold_whole_spooled_sectors(|s| s.sample_count)
1089    }
1090
1091    fn fold_whole_spooled_sectors(&self, of: impl Fn(&SectorSummary) -> u32) -> u32 {
1092        (0..self.sector_count)
1093            .map(|i| &self.sectors[i as usize])
1094            .filter(|s| s.state != SectorState::Erased && self.is_fully_spooled(s))
1095            .fold(0u32, |acc, s| acc.saturating_add(of(s)))
1096    }
1097}
1098
1099/// Append-only sensor database for NOR flash.
1100///
1101/// Generic parameters:
1102/// - `F`: Flash storage implementing `NorFlash` and `ReadNorFlash`
1103/// - `PAGE_SIZE`: the unit this database writes in. Must be a multiple of
1104///   `F::WRITE_SIZE` — checked at compile time — and must not exceed the part's
1105///   physical program page, which `embedded-storage` does not express and so
1106///   cannot be checked. Note `WRITE_SIZE` is the minimum write *granularity*,
1107///   not the program-page size; a driver reporting 1 constrains nothing.
1108/// - `MAX_SECTORS`: Maximum number of sectors this instance can manage
1109///
1110/// # Memory Usage
1111///
1112/// The struct's RAM footprint is approximately:
1113/// - `MAX_SECTORS × 48` bytes for the in-RAM sector index ([`SectorSummary`] array)
1114/// - `PAGE_SIZE` bytes for the write page buffer
1115/// - ~30 bytes for bookkeeping fields
1116///
1117/// Example: with `PAGE_SIZE = 256` and `MAX_SECTORS = 32`, total ≈ 1,822 bytes.
1118///
1119/// # NOR Flash Constraints
1120///
1121/// Entries cannot span page boundaries because NOR flash requires page-aligned
1122/// writes. Each entry (header + payload + CRC) must fit within a single
1123/// `PAGE_SIZE` page. The maximum payload size is `PAGE_SIZE - 20` bytes.
1124///
1125/// The database does not perform active wear leveling beyond the implicit
1126/// distribution of the circular sector ring. Sectors are used round-robin
1127/// starting from the sector after the current active one. For applications
1128/// needing precise wear balancing, consider tracking erase counts externally.
1129///
1130/// # Read Model
1131///
1132/// Reads do **not** write to flash: `latest`, `oldest`, `count`, `query_range`
1133/// and their typed variants scan committed entries and transparently include
1134/// any buffered (unflushed) entries from the page buffer, so a read never
1135/// triggers a flash write and `sync()` is needed for **durability** alone, not
1136/// for read visibility.
1137///
1138/// They do take `&mut self`, because `ReadNorFlash::read` does. An earlier
1139/// revision wrapped the driver in a `RefCell` so they could take `&self`, and
1140/// it bought nothing: `RefCell<F>` is `!Sync`, so the only way to share a
1141/// `SensorDb` was a `Mutex`, which hands back `&mut` anyway. What it cost was
1142/// real — reads split into two shapes (`&self` here, `&mut self` on
1143/// [`LogSource`](crate::LogSource), which
1144/// [`TieredDb`](crate::TieredDb) forces), a re-entrancy panic to fence off
1145/// (a callback capturing `&db` and calling `latest()` double-borrowed), and a
1146/// panic path in a `no_std` crate. Without it `SensorDb` is `Sync` whenever
1147/// `F` is, and the port and the inherent methods agree.
1148///
1149/// Methods that touch no flash — [`stats`](Self::stats),
1150/// [`is_mounted`](Self::is_mounted), [`head_position`](Self::head_position),
1151/// [`peek_unflushed`](Self::peek_unflushed) and the rest — still take `&self`.
1152///
1153/// # Stack Usage
1154///
1155/// Most public methods allocate a single `[u8; PAGE_SIZE]` temporary buffer
1156/// on the stack. The deepest call chains (e.g., `latest_value` → `latest` →
1157/// `find_latest_in_sector`) pass buffers through rather than allocating new
1158/// ones, so the worst-case stack overhead per call is approximately
1159/// `1 × PAGE_SIZE` bytes on top of the `SensorDb` struct itself.
1160///
1161/// With `PAGE_SIZE = 256`, this is negligible. With `PAGE_SIZE = 4096`, each
1162/// read/query call uses ~4 KB of stack — plan accordingly on Cortex-M targets
1163/// with limited stack space.
1164pub struct SensorDb<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
1165    flash: F,
1166    state: SensorDbState<PAGE_SIZE, MAX_SECTORS>,
1167}
1168
1169impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> core::fmt::Debug
1170    for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
1171{
1172    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1173        f.debug_struct("SensorDb")
1174            .field("base_offset", &self.state.base_offset)
1175            .field("sector_count", &self.state.sector_count)
1176            .field("sector_size", &self.state.sector_size)
1177            .field("mounted", &self.state.mounted)
1178            .field("active_sector", &self.state.active_sector)
1179            .field("total_entries", &self.state.total_entries)
1180            .finish_non_exhaustive()
1181    }
1182}
1183
1184impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDb<F, PAGE_SIZE, MAX_SECTORS>
1185where
1186    F: NorFlash + ReadNorFlash,
1187{
1188    /// Create a new SensorDb instance.
1189    ///
1190    /// # Arguments
1191    /// - `flash`: Flash storage
1192    /// - `base_offset`: Starting offset in flash for the database region
1193    /// - `sector_count`: Number of sectors to use
1194    /// - `reserved_sectors`: Number of sectors to keep free for compaction headroom
1195    ///
1196    /// # Limits
1197    ///
1198    /// - The entire database region (`sector_count × ERASE_SIZE + base_offset`)
1199    ///   must fit within `u32` address space (4 GB).
1200    /// - `SectorSummary.write_offset` is `u32`, supporting individual sectors
1201    ///   up to 4 GB.
1202    /// - `sector_count` must not exceed `MAX_SECTORS`.
1203    ///
1204    /// # Errors
1205    /// - `TooManySectors` if `sector_count > MAX_SECTORS`
1206    /// - `InvalidConfig` if `reserved_sectors >= sector_count`
1207    pub fn new(
1208        flash: F,
1209        base_offset: u32,
1210        sector_count: u16,
1211        reserved_sectors: u16,
1212    ) -> Result<Self, Error> {
1213        Self::with_config(
1214            flash,
1215            DbConfig::new(base_offset, sector_count, reserved_sectors)?,
1216        )
1217    }
1218
1219    /// Create a `SensorDb` from a validated [`DbConfig`].
1220    ///
1221    /// Use this instead of [`new`](Self::new) when the database needs a
1222    /// [`LogId`] — for example when its storage is removable and could be
1223    /// carried to, or confused with, another device.
1224    ///
1225    /// # Errors
1226    /// - `TooManySectors` if `config.sector_count() > MAX_SECTORS`
1227    /// - `Overflow` if the region does not fit in `u32` address space
1228    ///
1229    /// # Panics
1230    ///
1231    /// Fails to *compile*, not to run, if `PAGE_SIZE` is not a multiple of
1232    /// `F::WRITE_SIZE` — the compile-time `Geometry` assert.
1233    pub fn with_config(flash: F, config: DbConfig) -> Result<Self, Error> {
1234        let () = Geometry::<F, PAGE_SIZE>::PAGE_IS_WRITABLE;
1235        Ok(Self {
1236            flash,
1237            state: SensorDbState::new(config, F::ERASE_SIZE as u32)?,
1238        })
1239    }
1240
1241    /// Format the database region, erasing all sectors and initializing the first as active.
1242    ///
1243    /// After format, the database is automatically mounted. All sectors carry
1244    /// this database's [`LogId`] and `erase_count = 1`, and the epoch restarts
1245    /// at 1.
1246    ///
1247    /// This destroys everything in the region unconditionally — including a
1248    /// foreign volume. Use [`mount`](Self::mount), which refuses to touch
1249    /// another log's data, when the medium's provenance is not certain.
1250    pub fn format(&mut self) -> Result<(), Error> {
1251        let flash = &mut self.flash;
1252        // Erase all sectors
1253        for i in 0..self.state.sector_count {
1254            self.state.erase_sector(flash, i)?;
1255            self.state.sectors[i as usize] = SectorSummary::erased();
1256            self.state.sectors[i as usize].erase_count = 1;
1257        }
1258
1259        self.state.epoch = 1;
1260        // `init_sector` below stamps epoch 1, so nothing is owed.
1261        self.state.epoch_pending = false;
1262
1263        // Initialize first sector as active
1264        self.state.init_sector(flash, 0, 1, 1)?;
1265        self.state.sectors[0].state = SectorState::Active;
1266        self.state.sectors[0].sequence = 1;
1267        self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
1268        self.state.sectors[0].erase_count = 1;
1269
1270        self.state.active_sector = Some(0);
1271        self.state.next_sequence = 2;
1272        self.state.total_entries = 0;
1273        self.state.total_samples = 0;
1274        self.state.mounted = true;
1275        self.state.mount_mode = MountMode::Full;
1276        self.state.spool_watermark = LogPosition::BEGINNING;
1277        self.state.spooled_entries = 0;
1278        self.state.spooled_samples = 0;
1279        self.state.dropped_unspooled = 0;
1280
1281        // Initialize page buffer for the active sector
1282        self.state.page_flash_offset = self.state.base_offset;
1283        self.state.page_buf_offset = SECTOR_HEADER_SIZE;
1284        self.state.page_buf_durable = SECTOR_HEADER_SIZE;
1285        self.state.page_buf.fill(0xFF);
1286        // Read the sector header into the page buffer
1287        let header = self.state.sector_header(1, 1);
1288        self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
1289
1290        Ok(())
1291    }
1292
1293    /// Mount an existing database by scanning all sectors and rebuilding the index.
1294    ///
1295    /// Equivalent to [`mount_with(MountMode::Full)`](Self::mount_with).
1296    ///
1297    /// # Errors
1298    /// - `AlreadyMounted` if already mounted
1299    /// - `ForeignVolume` if the medium belongs to a different log
1300    /// - `UnsupportedVersion` if the medium uses a newer format
1301    pub fn mount(&mut self) -> Result<MountStats, Error> {
1302        self.mount_with(MountMode::Full)
1303    }
1304
1305    /// Mount an existing database, choosing how much of the index to rebuild.
1306    ///
1307    /// # Foreign media
1308    ///
1309    /// A sector whose header parses as this format but carries a different
1310    /// [`LogId`] aborts the mount with [`Error::ForeignVolume`], **before**
1311    /// anything is written. This matters for removable storage: the fallback
1312    /// path for "no valid sectors found" erases a sector to bootstrap the log,
1313    /// so without this check, inserting another device's card and mounting it
1314    /// would destroy its data.
1315    ///
1316    /// An anonymous database (no `log_id` in its [`DbConfig`]) accepts any
1317    /// medium, preserving the behaviour of databases that never declare an
1318    /// identity.
1319    ///
1320    /// # Epoch
1321    ///
1322    /// Each successful mount takes an epoch one higher than any found on the
1323    /// medium, and stamps it into every sector header written from then on.
1324    /// Timestamps from a device with no real-time clock restart at zero on every
1325    /// boot; the epoch is what lets a reader tell those runs apart.
1326    ///
1327    /// # Errors
1328    /// - `AlreadyMounted` if already mounted
1329    /// - `ForeignVolume` if the medium belongs to a different log
1330    /// - `UnsupportedVersion` if the medium uses a newer format
1331    pub fn mount_with(&mut self, mode: MountMode) -> Result<MountStats, Error> {
1332        if self.state.mounted {
1333            return Err(Error::AlreadyMounted);
1334        }
1335
1336        let flash = &mut self.flash;
1337        let mut stats = MountStats::default();
1338        let mut max_sequence: u32 = 0;
1339        let mut max_epoch: u32 = 0;
1340
1341        // Pass 1: read every sector header. Classification happens before any
1342        // write, so a foreign or unreadable volume is rejected intact.
1343        let mut valid: HeaplessVec<u16, MAX_SECTORS> = HeaplessVec::new();
1344        for i in 0..self.state.sector_count {
1345            let sector_offset = self.state.sector_offset(i);
1346            let mut header_buf = [0u8; SECTOR_HEADER_SIZE];
1347            flash.read(sector_offset, &mut header_buf)?;
1348
1349            let header =
1350                SectorHeader::read_from_bytes(&header_buf).map_err(|_| Error::CorruptEntry)?;
1351
1352            match header.classify(self.state.log_id) {
1353                SectorClass::Valid => {
1354                    let seq = header.sequence.get();
1355                    let epoch = header.epoch.get();
1356                    self.state.sectors[i as usize].sequence = seq;
1357                    self.state.sectors[i as usize].erase_count = header.erase_count.get();
1358                    max_sequence = max_sequence.max(seq);
1359                    max_epoch = max_epoch.max(epoch);
1360                    let _ = valid.push(i);
1361                }
1362                SectorClass::Free => {
1363                    // Erased, never written, or data this format cannot parse.
1364                    // The body is not a valid entry stream, so treat the sector
1365                    // as free rather than scanning it.
1366                    self.state.sectors[i as usize] = SectorSummary::erased();
1367                }
1368                SectorClass::Foreign { found } => {
1369                    return Err(Error::ForeignVolume {
1370                        expected: self.state.log_id_raw(),
1371                        found,
1372                    });
1373                }
1374                SectorClass::Unsupported { found } => {
1375                    return Err(Error::UnsupportedVersion { found });
1376                }
1377            }
1378        }
1379
1380        // The newest sector is the only one an append can land in, so it must be
1381        // scanned in every mode to find the resume offset.
1382        let newest = valid
1383            .iter()
1384            .copied()
1385            .max_by_key(|i| self.state.sectors[*i as usize].sequence);
1386
1387        // Pass 2: rebuild the entry index for the sectors this mode covers.
1388        //
1389        // The newest sector is where an append resumes, so it is always indexed
1390        // exactly — but even it can carry a footer: a run that sealed a sector
1391        // and then died before the successor's header reached flash leaves the
1392        // sealed sector holding the highest valid sequence. `newest_sealed`
1393        // records that, because the cursor must then be parked at the footer
1394        // page rather than inside data the footer already describes.
1395        let mut newest_sealed = false;
1396        for i in valid.iter().copied() {
1397            let is_newest = Some(i) == newest;
1398
1399            // Read a footer when it can index the sector — and always for the
1400            // newest one, where it is not an optimisation at all but the signal
1401            // that the sector is already closed. `HeadersOnly` keeps its
1402            // one-read-per-sector promise everywhere else.
1403            let footer = if self.state.wants_footer(mode, is_newest) {
1404                self.state.read_sector_footer(flash, i)?
1405            } else {
1406                None
1407            };
1408            if is_newest {
1409                newest_sealed = footer.is_some();
1410            }
1411
1412            // `Verify` exists to re-read the medium, so it indexes from entries
1413            // even where a footer would have answered.
1414            if let Some(footer) = footer.filter(|_| mode != MountMode::Verify) {
1415                self.state.adopt_footer(i, &footer, &mut stats);
1416            } else if mode != MountMode::HeadersOnly || is_newest {
1417                let (scanned, corrupt) = self.state.scan_sector_entries(flash, i)?;
1418                self.state.adopt_scan(i, &scanned, corrupt, &mut stats);
1419            } else {
1420                self.state.adopt_unindexed(i);
1421            }
1422            self.state.sectors[i as usize].state = SectorState::Sealed;
1423            stats.sealed_sectors += 1;
1424        }
1425
1426        self.state
1427            .finish_mount(mode, max_sequence, max_epoch, &stats);
1428
1429        if let Some(idx) = newest {
1430            self.state.sectors[idx as usize].state = SectorState::Active;
1431            self.state.active_sector = Some(idx);
1432            stats.sealed_sectors = stats.sealed_sectors.saturating_sub(1);
1433
1434            // This sector was created by an earlier run, so it carries that run's
1435            // epoch. Anything appended into it would be attributed to that run.
1436            // Owe a sector roll, paid on the first append.
1437            self.state.epoch_pending = true;
1438
1439            let sector_offset = self.state.sector_offset(idx);
1440
1441            // Where writing resumes inside this sector. Normally the end of its
1442            // data — but a sector that already carries a footer was *sealed*,
1443            // and its frozen summary would become a lie if anything were
1444            // appended into it. Resume such a sector at its footer page, which
1445            // is where `append`'s boundary check seals and moves on. That
1446            // happens when a run sealed a sector and then lost power before the
1447            // successor's header landed, leaving the sealed sector holding the
1448            // highest valid sequence.
1449            let resume = if newest_sealed {
1450                self.state.footer_offset()
1451            } else {
1452                self.state.sectors[idx as usize].write_offset
1453            };
1454
1455            // Load the partial page into the buffer
1456            let page_start = (resume / PAGE_SIZE as u32) * PAGE_SIZE as u32;
1457            self.state.page_flash_offset = sector_offset + page_start;
1458            self.state.page_buf_offset = (resume % PAGE_SIZE as u32) as usize;
1459            self.state.page_buf_durable = self.state.page_buf_offset;
1460            self.state.page_buf.fill(0xFF);
1461
1462            // A power loss can leave written bytes *past* the last valid entry,
1463            // and not only in this page: the scanner steps over uncommitted
1464            // entries without adopting them, so whole pages of half-committed
1465            // data can sit ahead of the resume point. Appending before them
1466            // would eventually flush into a dirty page, and NOR cannot set bits
1467            // back — the write fails and the log wedges.
1468            //
1469            // Find the last page in this sector that still holds data, and
1470            // resume after it. This costs one read per page of the active
1471            // sector, on a path that has already read every entry.
1472            //
1473            // Usually nothing depends on it: `epoch_pending` was just set, so
1474            // the first append rolls to a fresh sector and abandons this one
1475            // before any of it matters. But that roll is skipped when the ring
1476            // has no sector to give (`append` swallows `NoSpace` rather than
1477            // fail a write for the sake of provenance metadata), and *then* this
1478            // is the only thing standing between a torn page and a log that
1479            // cannot be written to again. A full ring is exactly when losing the
1480            // log would hurt most.
1481            //
1482            // Bounded by the footer offset: the final page is not data, and on a
1483            // sector parked there by `newest_sealed` the probe does not run at
1484            // all — there is nothing ahead of the cursor to be in the way of.
1485            let mut last_dirty: Option<u32> = None;
1486            let mut probe = page_start;
1487            while probe < self.state.footer_offset() {
1488                flash.read(sector_offset + probe, &mut self.state.page_buf)?;
1489                // In the resume page, only what lies *after* the write position
1490                // counts as in the way.
1491                let from = if probe == page_start {
1492                    self.state.page_buf_offset
1493                } else {
1494                    0
1495                };
1496                if self.state.page_buf[from..].iter().any(|b| *b != 0xFF) {
1497                    last_dirty = Some(probe);
1498                }
1499                probe += PAGE_SIZE as u32;
1500            }
1501
1502            match last_dirty {
1503                // Everything from the write position on is erased: resume there,
1504                // continuing to fill the partial page. Nothing to re-read when
1505                // the cursor is parked on the footer page.
1506                None if resume < self.state.footer_offset() => {
1507                    flash.read(self.state.page_flash_offset, &mut self.state.page_buf)?;
1508                }
1509                None => {}
1510                // Something is in the way. Start after it, giving up the rest of
1511                // the skipped pages — cheaper than an unusable log.
1512                Some(dirty) => {
1513                    self.state.page_flash_offset = sector_offset + dirty + PAGE_SIZE as u32;
1514                    self.state.page_buf_offset = 0;
1515                    self.state.page_buf_durable = 0;
1516                    self.state.page_buf.fill(0xFF);
1517                    self.state.sectors[idx as usize].write_offset = dirty + PAGE_SIZE as u32;
1518                }
1519            }
1520        } else {
1521            // No valid sectors found. The chosen sector may hold stale data from a
1522            // previous format (NOR writes only clear bits, so writing a fresh
1523            // header over it would corrupt the magic), so erase before init.
1524            //
1525            // Reaching here means every sector classified as Free, so nothing
1526            // another log owns is being destroyed.
1527            self.state.erase_sector(flash, 0)?;
1528            self.state
1529                .init_sector(flash, 0, self.state.next_sequence, 1)?;
1530            // That header carries this run's epoch, so nothing is owed.
1531            self.state.epoch_pending = false;
1532            self.state.sectors[0].state = SectorState::Active;
1533            self.state.sectors[0].sequence = self.state.next_sequence;
1534            self.state.sectors[0].write_offset = SECTOR_HEADER_SIZE as u32;
1535            self.state.sectors[0].erase_count = 1;
1536            self.state.active_sector = Some(0);
1537            self.state.next_sequence += 1;
1538
1539            self.state.page_flash_offset = self.state.base_offset;
1540            self.state.page_buf_offset = SECTOR_HEADER_SIZE;
1541            self.state.page_buf_durable = SECTOR_HEADER_SIZE;
1542            self.state.page_buf.fill(0xFF);
1543            let header = self.state.sector_header(self.state.sectors[0].sequence, 1);
1544            self.state.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
1545        }
1546
1547        self.state.mounted = true;
1548        Ok(stats)
1549    }
1550
1551    /// Append a sensor reading to the database.
1552    ///
1553    /// # Arguments
1554    /// - `sensor_id`: Sensor identifier
1555    /// - `timestamp`: Timestamp (typically microseconds since epoch)
1556    /// - `payload`: Raw sensor data
1557    ///
1558    /// # Errors
1559    /// - `NotMounted` if not mounted
1560    /// - `PayloadTooLarge` if payload exceeds max size
1561    /// - `NoSpace` if no sectors available
1562    pub fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
1563        self.append_entry(
1564            EntryKind::Single,
1565            sensor_id,
1566            timestamp,
1567            timestamp,
1568            1,
1569            &[],
1570            payload,
1571        )
1572    }
1573
1574    /// Append a [run](crate::run): many evenly spaced samples under one header.
1575    ///
1576    /// One entry header and one CRC for the whole burst, which is what makes it
1577    /// worth doing — thirty-two `f32` samples cost 148 bytes here against 800
1578    /// appended one at a time.
1579    ///
1580    /// The run is **invisible to every read**: [`query_range`](Self::query_range),
1581    /// [`latest`](Self::latest), [`oldest`](Self::oldest) and
1582    /// [`count`](Self::count) expand it back into the samples it holds, so they
1583    /// deliver byte for byte what [`append_sensor`](Self::append_sensor) of the
1584    /// same samples would have delivered. Only
1585    /// [`read_from`](Self::read_from) sees it as one entry, because replication
1586    /// copies entries and a replica should keep the amortisation.
1587    ///
1588    /// ```ignore
1589    /// use sensor_db::Run;
1590    ///
1591    /// let burst: [Temperature; 32] = collect_burst();
1592    /// db.append_run(&Run::of(t0, 10_000, &burst)?)?;
1593    /// ```
1594    ///
1595    /// # Errors
1596    /// - `NotMounted` if not mounted
1597    /// - `PayloadTooLarge` if the framed run exceeds
1598    ///   [`max_payload_size`](Self::max_payload_size); split the burst
1599    /// - `NoSpace` if no sectors available
1600    pub fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
1601        let mut frame = [0u8; RUN_FRAME_SIZE];
1602        run.write_frame(&mut frame);
1603        self.append_entry(
1604            EntryKind::Run,
1605            run.sensor_id(),
1606            run.base_timestamp(),
1607            run.span_end(),
1608            run.count(),
1609            &frame,
1610            run.samples(),
1611        )
1612    }
1613
1614    /// Append an entry exactly as another log stored it.
1615    ///
1616    /// The write side of replication, and the mirror of
1617    /// [`read_from`](Self::read_from): hand back the `(header, payload)` pair a
1618    /// stream delivered and the entry is reproduced here — a
1619    /// [run](crate::run) as a run, so the copy keeps the amortisation instead of
1620    /// storing the frame as one opaque sample no read could interpret.
1621    ///
1622    /// # Errors
1623    /// - `CorruptEntry` if the header claims a run and the payload is not one
1624    /// - otherwise as [`append`](Self::append)
1625    pub fn append_framed(&mut self, header: &EntryHeader, payload: &[u8]) -> Result<(), Error> {
1626        match header.kind {
1627            EntryKind::Single => self.append(header.sensor_id, header.timestamp, payload),
1628            EntryKind::Run => {
1629                let frame = RunFrame::parse(payload).ok_or(Error::CorruptEntry)?;
1630                self.append_entry(
1631                    EntryKind::Run,
1632                    header.sensor_id,
1633                    header.timestamp,
1634                    frame.span_end(header.timestamp),
1635                    frame.count(),
1636                    &[],
1637                    payload,
1638                )
1639            }
1640        }
1641    }
1642
1643    /// The one write path: buffer an entry of either kind, sealing as needed.
1644    ///
1645    /// The payload arrives in two pieces so a run costs no staging buffer — the
1646    /// frame header and the sample bytes go straight into the page buffer, which
1647    /// is also where the entry CRC is then computed from.
1648    ///
1649    /// `span_end` and `samples` describe what the entry contributes to the
1650    /// sector index: a single sample spans its own timestamp and counts once, a
1651    /// run spans to its last sample and counts all of them.
1652    #[allow(clippy::too_many_arguments)]
1653    fn append_entry(
1654        &mut self,
1655        kind: EntryKind,
1656        sensor_id: u16,
1657        timestamp: u64,
1658        span_end: u64,
1659        samples: u32,
1660        head: &[u8],
1661        tail: &[u8],
1662    ) -> Result<(), Error> {
1663        if !self.state.mounted {
1664            return Err(Error::NotMounted);
1665        }
1666
1667        let payload_len = head.len() + tail.len();
1668        let entry_size = ENTRY_OVERHEAD + payload_len;
1669        if payload_len > self.max_payload_size() {
1670            return Err(Error::PayloadTooLarge);
1671        }
1672
1673        let flash = &mut self.flash;
1674
1675        // This run inherited a sector an earlier run created, so appending into
1676        // it would stamp these entries with the earlier run's epoch. Roll to a
1677        // fresh sector, which records this run's epoch on the medium.
1678        //
1679        // Deferred to here rather than done at mount so a run that only reads
1680        // costs no erase at all.
1681        if self.state.epoch_pending {
1682            match self.state.seal_and_advance(flash) {
1683                Ok(()) => {}
1684                // Provenance metadata must never cost a write. If the ring has
1685                // no sector to give, append into the inherited one; the only
1686                // casualty is epoch precision.
1687                Err(Error::NoSpace) => self.state.epoch_pending = false,
1688                Err(e) => return Err(e),
1689            }
1690        }
1691
1692        // Make room. One seal always suffices: a fresh sector gives a whole page
1693        // after its header page. A second would mean the geometry cannot hold
1694        // this entry anywhere, so refuse rather than seal forever — burning the
1695        // entire ring one sector per iteration.
1696        let mut sealed_once = false;
1697        loop {
1698            match self.state.plan_append(entry_size)? {
1699                AppendStep::Stage => break,
1700                AppendStep::FlushPage => self.state.flush_page(flash)?,
1701                AppendStep::Seal => {
1702                    if sealed_once {
1703                        return Err(Error::PayloadTooLarge);
1704                    }
1705                    sealed_once = true;
1706                    self.state.seal_and_advance(flash)?;
1707                }
1708            }
1709        }
1710
1711        self.state
1712            .stage_entry(kind, sensor_id, timestamp, span_end, samples, head, tail)
1713    }
1714
1715    /// Flush the page buffer to flash, committing buffered entries.
1716    ///
1717    /// Call this after writing entries to ensure they survive a power loss.
1718    /// Read methods (`latest`, `query_range`, `oldest`, `count`) do **not**
1719    /// require a prior `sync()` — they transparently scan the page buffer for
1720    /// unflushed entries. `sync()` is only needed for **durability**, not for
1721    /// read visibility.
1722    ///
1723    /// # Sync Policy
1724    ///
1725    /// There is a trade-off between data safety and flash wear:
1726    /// - **Sync after every append**: Maximum durability — no data loss on power
1727    ///   failure, but each sync writes a full flash page (two writes for the
1728    ///   two-phase commit), increasing wear.
1729    /// - **Sync periodically** (e.g., every N entries or every T seconds):
1730    ///   Reduces wear but risks losing buffered entries on power failure.
1731    ///   Entries written since the last sync are not yet committed to flash.
1732    ///
1733    /// On embedded systems with limited flash endurance (~100K erase cycles),
1734    /// prefer batching writes and syncing periodically.
1735    pub fn sync(&mut self) -> Result<(), Error> {
1736        if !self.state.mounted {
1737            return Err(Error::NotMounted);
1738        }
1739        self.state.flush_page(&mut self.flash)?;
1740        Ok(())
1741    }
1742
1743    /// Find the most recent entry for a given sensor.
1744    ///
1745    /// This method does **not** write to flash. It scans committed entries on
1746    /// flash and any buffered (unflushed) entries in the page buffer, returning
1747    /// the one with the highest timestamp.
1748    ///
1749    /// # Arguments
1750    /// - `sensor_id`: Sensor to query
1751    /// - `buf`: Buffer to receive payload
1752    ///
1753    /// # Returns
1754    /// `Some((header, payload_len))` if found, `None` if no entries for this sensor.
1755    pub fn latest(
1756        &mut self,
1757        sensor_id: u16,
1758        buf: &mut [u8],
1759    ) -> Result<Option<(EntryHeader, usize)>, Error> {
1760        self.state.require_reads()?;
1761
1762        let flash = &mut self.flash;
1763
1764        // Sort sectors by sequence (newest first), skipping sectors that
1765        // definitely don't contain this sensor (bloom filter)
1766        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1767        for i in 0..self.state.sector_count {
1768            let summary = &self.state.sectors[i as usize];
1769            if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
1770                // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1771                let _ = sector_order.push((i, summary.sequence));
1772            }
1773        }
1774        // Sort descending by sequence
1775        sort_by_seq(&mut sector_order, |a, b| b.cmp(a));
1776
1777        // Scan committed sectors from flash (newest first, writes payload to buf)
1778        let mut best: Option<(EntryHeader, usize)> = None;
1779        for (sector_idx, _) in sector_order {
1780            if let Some(result) =
1781                self.state
1782                    .find_latest_in_sector(&mut *flash, sector_idx, sensor_id, buf)?
1783            {
1784                best = Some(result);
1785                break;
1786            }
1787        }
1788
1789        // Scan page buffer for unflushed entries. Only accepts entries with
1790        // timestamp >= the committed best, so buf is only overwritten if the
1791        // page buffer entry actually wins.
1792        let min_ts = best.as_ref().map_or(0, |(h, _)| h.timestamp);
1793        if let Some((hdr, len)) = self
1794            .state
1795            .scan_page_buf_for_latest(sensor_id, min_ts, buf)?
1796        {
1797            best = Some((hdr, len));
1798        }
1799
1800        Ok(best)
1801    }
1802
1803    /// Query entries within a time range.
1804    ///
1805    /// This method does **not** write to flash. It scans committed entries on
1806    /// flash and any buffered (unflushed) entries in the page buffer.
1807    ///
1808    /// # Arguments
1809    /// - `sensor_id`: Optional sensor filter (None for all sensors)
1810    /// - `t_start`: Start timestamp (inclusive)
1811    /// - `t_end`: End timestamp (inclusive)
1812    /// - `callback`: Called for each matching entry. Return `false` to stop early.
1813    ///
1814    /// # Returns
1815    /// Number of entries that matched.
1816    ///
1817    /// **Note:** Entries are returned in write order (sector sequence, then offset
1818    /// within sector), not sorted by timestamp. If timestamps are non-monotonic,
1819    /// the callback will see them out of chronological order.
1820    pub fn query_range<C>(
1821        &mut self,
1822        sensor_id: Option<u16>,
1823        t_start: u64,
1824        t_end: u64,
1825        mut callback: C,
1826    ) -> Result<u32, Error>
1827    where
1828        C: FnMut(&EntryHeader, &[u8]) -> bool,
1829    {
1830        self.state.require_reads()?;
1831
1832        let flash = &mut self.flash;
1833        let mut count = 0u32;
1834
1835        // Sort sectors by sequence (oldest first for chronological order)
1836        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1837        for i in 0..self.state.sector_count {
1838            let summary = &self.state.sectors[i as usize];
1839            if summary.state != SectorState::Erased
1840                && summary.entry_count > 0
1841                && summary.overlaps_time_range(t_start, t_end)
1842                && sensor_id.is_none_or(|id| summary.might_contain_sensor(id))
1843            {
1844                // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1845                let _ = sector_order.push((i, summary.sequence));
1846            }
1847        }
1848        // Sort ascending by sequence for chronological order
1849        sort_by_seq(&mut sector_order, u32::cmp);
1850
1851        let mut entry_buf = [0u8; PAGE_SIZE];
1852        let mut stopped = false;
1853
1854        for (sector_idx, _) in sector_order {
1855            stopped = self.state.scan_sector_for_query(
1856                flash,
1857                sector_idx,
1858                sensor_id,
1859                t_start,
1860                t_end,
1861                &mut entry_buf,
1862                &mut count,
1863                &mut callback,
1864            )?;
1865            if stopped {
1866                break;
1867            }
1868        }
1869
1870        // Scan page buffer for unflushed entries (newest, after all committed)
1871        if !stopped {
1872            self.state.scan_page_buf_for_query(
1873                sensor_id,
1874                t_start,
1875                t_end,
1876                &mut entry_buf,
1877                &mut count,
1878                &mut callback,
1879            );
1880        }
1881
1882        Ok(count)
1883    }
1884
1885    /// Query all entries for a sensor (or all sensors) without time constraints.
1886    ///
1887    /// This is a convenience wrapper around `query_range` that uses the full timestamp range.
1888    ///
1889    /// # Arguments
1890    /// - `sensor_id`: Optional sensor filter (None for all sensors)
1891    /// - `callback`: Called for each matching entry. Return `false` to stop early.
1892    ///
1893    /// # Returns
1894    /// Number of entries that matched.
1895    ///
1896    /// # Example
1897    ///
1898    /// ```ignore
1899    /// let count = db.query_all(Some(SENSOR_TEMP), |hdr, payload| {
1900    ///     println!("Entry at {}: {:?}", hdr.timestamp, payload);
1901    ///     true
1902    /// })?;
1903    /// ```
1904    pub fn query_all<C>(&mut self, sensor_id: Option<u16>, callback: C) -> Result<u32, Error>
1905    where
1906        C: FnMut(&EntryHeader, &[u8]) -> bool,
1907    {
1908        self.query_range(sensor_id, 0, u64::MAX, callback)
1909    }
1910
1911    /// Find the oldest (earliest) entry for a given sensor.
1912    ///
1913    /// This method does **not** write to flash. It scans committed entries on
1914    /// flash and falls back to the page buffer if no committed entries exist
1915    /// for this sensor.
1916    ///
1917    /// # Arguments
1918    /// - `sensor_id`: Sensor to query
1919    /// - `buf`: Buffer to receive payload
1920    ///
1921    /// # Returns
1922    /// `Some((header, payload_len))` if found, `None` if no entries for this sensor.
1923    ///
1924    /// # Example
1925    ///
1926    /// ```ignore
1927    /// let mut buf = [0u8; 64];
1928    /// if let Some((hdr, n)) = db.oldest(SENSOR_TEMP, &mut buf)? {
1929    ///     let first_reading = &buf[..n];
1930    ///     println!("First reading at {}", hdr.timestamp);
1931    /// }
1932    /// ```
1933    pub fn oldest(
1934        &mut self,
1935        sensor_id: u16,
1936        buf: &mut [u8],
1937    ) -> Result<Option<(EntryHeader, usize)>, Error> {
1938        self.state.require_reads()?;
1939
1940        let flash = &mut self.flash;
1941
1942        // Sort sectors by sequence (oldest first), skipping sectors that
1943        // definitely don't contain this sensor (bloom filter)
1944        let mut sector_order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
1945        for i in 0..self.state.sector_count {
1946            let summary = &self.state.sectors[i as usize];
1947            if summary.state != SectorState::Erased && summary.might_contain_sensor(sensor_id) {
1948                // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
1949                let _ = sector_order.push((i, summary.sequence));
1950            }
1951        }
1952        // Sort ascending by sequence (oldest first)
1953        sort_by_seq(&mut sector_order, u32::cmp);
1954
1955        for (sector_idx, _) in sector_order {
1956            if let Some((header, payload_len)) =
1957                self.state
1958                    .find_oldest_in_sector(&mut *flash, sector_idx, sensor_id, buf)?
1959            {
1960                return Ok(Some((header, payload_len)));
1961            }
1962        }
1963
1964        // Fallback: check page buffer. The active sector is the newest, so
1965        // buffered entries can only be "oldest" if no committed entries exist.
1966        if let Some(result) = self.state.scan_page_buf_for_oldest(sensor_id, buf) {
1967            return Ok(Some(result));
1968        }
1969
1970        Ok(None)
1971    }
1972
1973    /// Count entries for a specific sensor (or all sensors).
1974    ///
1975    /// Exact: the count is the number of entries
1976    /// [`query_range`](Self::query_range) would yield over the whole time range,
1977    /// because both apply the same acceptance test — a matching entry CRC — and
1978    /// resync the same way when one fails. Buffered entries not yet on flash are
1979    /// included, as they are for [`latest`](Self::latest).
1980    ///
1981    /// This method does **not** write to flash.
1982    ///
1983    /// # Cost
1984    ///
1985    /// `None` is free: it returns the total the mount scan established.
1986    ///
1987    /// A sensor filter scans every sector the per-sector bloom filter does not
1988    /// reject, reading each entry's payload to verify its CRC. That payload read
1989    /// is the price of agreeing with the read path; it was once skipped, which
1990    /// made `count` cheaper and wrong — it included entries `latest` and
1991    /// `query_range` refused to return. It is still cheaper than
1992    /// [`query_all`](Self::query_all), which has no bloom filter to skip
1993    /// sectors by.
1994    ///
1995    /// # Arguments
1996    /// - `sensor_id`: Optional sensor filter (None to count all entries)
1997    ///
1998    /// # Returns
1999    /// Number of entries matching the filter.
2000    ///
2001    /// # Example
2002    ///
2003    /// ```ignore
2004    /// let temp_count = db.count(Some(SENSOR_TEMP))?;
2005    /// let total = db.count(None)?;
2006    /// ```
2007    pub fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
2008        self.state.require_reads()?;
2009
2010        // For counting all entries, we can use the cached total
2011        let Some(target) = sensor_id else {
2012            return Ok(self.state.total_samples);
2013        };
2014
2015        let flash = &mut self.flash;
2016        let mut count = 0u32;
2017
2018        for i in 0..self.state.sector_count {
2019            let summary = &self.state.sectors[i as usize];
2020            if summary.state != SectorState::Erased && summary.might_contain_sensor(target) {
2021                count += self.state.count_sensor_in_sector(&mut *flash, i, target)?;
2022            }
2023        }
2024
2025        // Include unflushed entries in the page buffer
2026        count += self.state.count_sensor_in_page_buf(target);
2027
2028        Ok(count)
2029    }
2030
2031    /// Compact the database by erasing the oldest sealed sectors.
2032    ///
2033    /// # Arguments
2034    /// - `count`: Maximum number of sectors to erase
2035    /// - `scope`: Which sealed sectors are eligible. Use
2036    ///   [`CompactScope::SpooledOnly`] to reclaim space without destroying
2037    ///   anything that has not been replicated yet.
2038    ///
2039    /// # Returns
2040    /// Number of sectors actually erased.
2041    pub fn compact(&mut self, count: u16, scope: CompactScope) -> Result<u16, Error> {
2042        if !self.state.mounted {
2043            return Err(Error::NotMounted);
2044        }
2045
2046        // Find eligible sealed sectors
2047        let mut sealed: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
2048        for i in 0..self.state.sector_count {
2049            let summary = &self.state.sectors[i as usize];
2050            if summary.state != SectorState::Sealed {
2051                continue;
2052            }
2053            if scope == CompactScope::SpooledOnly && !self.state.is_fully_spooled(summary) {
2054                continue;
2055            }
2056            // Cannot fail: vec capacity is MAX_SECTORS >= sector_count
2057            let _ = sealed.push((i, summary.sequence));
2058        }
2059
2060        // Sort by sequence (oldest first)
2061        sort_by_seq(&mut sealed, u32::cmp);
2062
2063        let flash = &mut self.flash;
2064        let mut erased = 0u16;
2065        for (sector_idx, _) in sealed.iter().take(count as usize) {
2066            let victim = self.state.sectors[*sector_idx as usize];
2067            self.state.erase_sector(flash, *sector_idx)?;
2068            // Only after the erase actually succeeded.
2069            self.state.account_eviction(&victim);
2070            self.state.sectors[*sector_idx as usize] = SectorSummary::erased();
2071            // Preserve erase count — incremented when sector is later initialized
2072            self.state.sectors[*sector_idx as usize].erase_count = victim.erase_count;
2073            erased += 1;
2074        }
2075
2076        Ok(erased)
2077    }
2078
2079    /// Get database statistics.
2080    pub fn stats(&self) -> DbStats {
2081        self.state.stats()
2082    }
2083
2084    /// Sectors this instance has erased, since it was created.
2085    ///
2086    /// An erase takes 100 ms or more on many NOR parts, against microseconds for
2087    /// a page write, so it is the one operation that can make a single `append`
2088    /// or [`compact`](Self::compact) call visibly slow. Sampling this around a
2089    /// call says whether one happened — useful for a caller with a real-time
2090    /// deadline, and for
2091    /// [`WritePolicy::CardFirst`](crate::spool::WritePolicy::CardFirst), where
2092    /// appends go straight to a removable volume.
2093    ///
2094    /// Not the same as [`DbStats::total_erase_count`], which is a *wear* history
2095    /// read back from the sector headers and therefore counts erases from every
2096    /// previous run too. This counter starts at zero for each `SensorDb` value,
2097    /// including across a remount, and saturates rather than wrapping.
2098    pub fn sectors_erased(&self) -> u32 {
2099        self.state.sectors_erased
2100    }
2101
2102    /// Check if the database is mounted.
2103    pub fn is_mounted(&self) -> bool {
2104        self.state.mounted
2105    }
2106
2107    /// Maximum payload size that can fit in a single entry.
2108    ///
2109    /// Returns `PAGE_SIZE - 20` bytes (`PAGE_SIZE` minus the 16-byte entry
2110    /// header and 4-byte CRC-32C). Each entry must fit entirely within a
2111    /// single flash page.
2112    ///
2113    /// A *typed* payload carries a one-byte schema tag, so the largest storable
2114    /// `T` is one byte smaller again — see
2115    /// [`SCHEMA_TAG_SIZE`](crate::SCHEMA_TAG_SIZE).
2116    pub fn max_payload_size(&self) -> usize {
2117        PAGE_SIZE - ENTRY_OVERHEAD
2118    }
2119
2120    // -------------------------------------------------------------------------
2121    // Typed API - Layer 1: Explicit sensor ID with zerocopy types
2122    // -------------------------------------------------------------------------
2123
2124    /// Append a typed value to the database with an explicit sensor ID.
2125    ///
2126    /// This is the Layer 1 API where you provide the sensor ID explicitly.
2127    /// The value type must implement [`IntoBytes`] and [`Immutable`] from zerocopy.
2128    ///
2129    /// # Arguments
2130    /// - `sensor_id`: Sensor identifier
2131    /// - `timestamp`: Timestamp (typically microseconds since epoch)
2132    /// - `data`: Reference to the typed value to store
2133    ///
2134    /// # Example
2135    ///
2136    /// ```ignore
2137    /// #[derive(IntoBytes, Immutable)]
2138    /// #[repr(C)]
2139    /// struct Temperature { celsius: f32 }
2140    ///
2141    /// db.append_value(0x01, timestamp, &Temperature { celsius: 25.5 })?;
2142    /// ```
2143    pub fn append_value<T: IntoBytes + Immutable>(
2144        &mut self,
2145        sensor_id: u16,
2146        timestamp: u64,
2147        data: &T,
2148    ) -> Result<(), Error> {
2149        self.append(sensor_id, timestamp, data.as_bytes())
2150    }
2151
2152    /// Find the most recent entry for a given sensor and interpret as a typed value.
2153    ///
2154    /// This is the Layer 1 API where you provide the sensor ID explicitly.
2155    /// The value type must implement [`FromBytes`] and [`KnownLayout`] from zerocopy.
2156    ///
2157    /// # Arguments
2158    /// - `sensor_id`: Sensor to query
2159    ///
2160    /// # Returns
2161    /// `Some((header, value))` if found, `None` if no entries for this sensor.
2162    ///
2163    /// # Errors
2164    /// - `SizeMismatch` if the stored payload size doesn't match `size_of::<T>()`
2165    /// - `InvalidData` if the bytes cannot be interpreted as type `T`
2166    ///
2167    /// # Example
2168    ///
2169    /// ```ignore
2170    /// #[derive(FromBytes, KnownLayout)]
2171    /// #[repr(C)]
2172    /// struct Temperature { celsius: f32 }
2173    ///
2174    /// if let Some((hdr, temp)) = db.latest_value::<Temperature>(0x01)? {
2175    ///     println!("Temperature: {} °C", temp.celsius);
2176    /// }
2177    /// ```
2178    pub fn latest_value<T: FromBytes + KnownLayout>(
2179        &mut self,
2180        sensor_id: u16,
2181    ) -> Result<Option<(EntryHeader, T)>, Error> {
2182        let expected_size = core::mem::size_of::<T>();
2183        let mut buf = [0u8; PAGE_SIZE];
2184
2185        match self.latest(sensor_id, &mut buf)? {
2186            Some((header, payload_len)) => {
2187                if payload_len != expected_size {
2188                    return Err(Error::SizeMismatch {
2189                        expected: expected_size,
2190                        actual: payload_len,
2191                    });
2192                }
2193                let value =
2194                    T::read_from_bytes(&buf[..payload_len]).map_err(|_| Error::InvalidData)?;
2195                Ok(Some((header, value)))
2196            }
2197            None => Ok(None),
2198        }
2199    }
2200
2201    // -------------------------------------------------------------------------
2202    // Typed API - Layer 2: Type-driven sensor ID via SensorData trait
2203    // -------------------------------------------------------------------------
2204
2205    /// Append a sensor reading using the type-driven API.
2206    ///
2207    /// This is the Layer 2 API where the sensor ID is derived from the type.
2208    /// The data type must implement [`SensorData`].
2209    ///
2210    /// # Arguments
2211    /// - `timestamp`: Timestamp (typically microseconds since epoch)
2212    /// - `data`: Reference to the sensor data to store
2213    ///
2214    /// # Example
2215    ///
2216    /// ```ignore
2217    /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
2218    /// #[repr(C)]
2219    /// struct Temperature { celsius: f32 }
2220    ///
2221    /// impl SensorData for Temperature {
2222    ///     const SENSOR_ID: u16 = 0x01;
2223    /// }
2224    ///
2225    /// db.append_sensor(timestamp, &Temperature { celsius: 25.5 })?;
2226    /// ```
2227    ///
2228    /// # Schema tag
2229    ///
2230    /// The payload is the type's
2231    /// [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) followed by the value's
2232    /// bytes, so the entry's `payload_len` is `size_of::<T>() + 1`. Entries
2233    /// written with the untagged [`append_value`](Self::append_value) are not
2234    /// readable through the `*_sensor` methods, and vice versa.
2235    pub fn append_sensor<T: SensorData>(&mut self, timestamp: u64, data: &T) -> Result<(), Error> {
2236        let framed = schema::tag(data);
2237        self.append(T::SENSOR_ID, timestamp, framed.bytes())
2238    }
2239
2240    /// Find the most recent entry for a sensor type.
2241    ///
2242    /// This is the Layer 2 API where the sensor ID is derived from the type.
2243    /// The data type must implement [`SensorData`].
2244    ///
2245    /// # Returns
2246    /// `Some((header, value))` if found, `None` if no entries for this sensor.
2247    ///
2248    /// # Errors
2249    /// - `SizeMismatch` if the stored payload is not `size_of::<T>() + 1` bytes
2250    /// - `SchemaMismatch` if it was written under another
2251    ///   [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) of this type
2252    ///
2253    /// # Example
2254    ///
2255    /// ```ignore
2256    /// if let Some((hdr, temp)) = db.latest_sensor::<Temperature>()? {
2257    ///     println!("Temperature: {} °C at {}", temp.celsius, hdr.timestamp);
2258    /// }
2259    /// ```
2260    pub fn latest_sensor<T: SensorData>(&mut self) -> Result<Option<(EntryHeader, T)>, Error> {
2261        schema::read_tagged(|buf| self.latest(T::SENSOR_ID, buf))
2262    }
2263
2264    /// Query sensor entries within a time range using the type-driven API.
2265    ///
2266    /// This is the Layer 2 API where the sensor ID is derived from the type.
2267    /// The data type must implement [`SensorData`].
2268    ///
2269    /// # Arguments
2270    /// - `t_start`: Start timestamp (inclusive)
2271    /// - `t_end`: End timestamp (inclusive)
2272    /// - `callback`: Called for each matching entry with the header and typed value.
2273    ///   Return `false` to stop early.
2274    ///
2275    /// # Returns
2276    /// Number of entries that matched and were successfully deserialized.
2277    ///
2278    /// # Example
2279    ///
2280    /// ```ignore
2281    /// let count = db.query_sensor::<Temperature, _>(t_start, t_end, |hdr, temp| {
2282    ///     println!("{}: {} °C", hdr.timestamp, temp.celsius);
2283    ///     true // continue iterating
2284    /// })?;
2285    /// ```
2286    pub fn query_sensor<T: SensorData, C>(
2287        &mut self,
2288        t_start: u64,
2289        t_end: u64,
2290        mut callback: C,
2291    ) -> Result<u32, Error>
2292    where
2293        C: FnMut(&EntryHeader, &T) -> bool,
2294    {
2295        let mut count = 0u32;
2296
2297        self.query_range(Some(T::SENSOR_ID), t_start, t_end, |header, payload| {
2298            // Entries of another schema version, or of another shape entirely,
2299            // are skipped rather than raised: aborting on the first stale one
2300            // would hide every good entry behind it. Two types sharing a sensor
2301            // ID at different versions therefore each read their own era.
2302            let Some(value) = schema::untag_payload::<T>(payload) else {
2303                return true;
2304            };
2305            count += 1;
2306            callback(header, &value)
2307        })?;
2308
2309        Ok(count)
2310    }
2311
2312    /// Query all entries for a sensor type without time constraints.
2313    ///
2314    /// This is a convenience wrapper that queries all entries for the sensor type.
2315    ///
2316    /// # Arguments
2317    /// - `callback`: Called for each matching entry with the header and typed value.
2318    ///   Return `false` to stop early.
2319    ///
2320    /// # Returns
2321    /// Number of entries that matched and were successfully deserialized.
2322    ///
2323    /// # Example
2324    ///
2325    /// ```ignore
2326    /// let count = db.query_all_sensor::<Temperature, _>(|hdr, temp| {
2327    ///     println!("{}: {} °C", hdr.timestamp, temp.celsius);
2328    ///     true
2329    /// })?;
2330    /// ```
2331    pub fn query_all_sensor<T: SensorData, C>(&mut self, callback: C) -> Result<u32, Error>
2332    where
2333        C: FnMut(&EntryHeader, &T) -> bool,
2334    {
2335        self.query_sensor(0, u64::MAX, callback)
2336    }
2337
2338    /// Find the oldest (earliest) entry for a sensor type.
2339    ///
2340    /// # Returns
2341    /// `Some((header, value))` if found, `None` if no entries for this sensor.
2342    ///
2343    /// # Errors
2344    /// - `SizeMismatch` if the stored payload size doesn't match `size_of::<T>()`
2345    /// - `InvalidData` if the bytes cannot be interpreted as type `T`
2346    ///
2347    /// # Example
2348    ///
2349    /// ```ignore
2350    /// if let Some((hdr, temp)) = db.oldest_sensor::<Temperature>()? {
2351    ///     println!("First reading: {} °C at {}", temp.celsius, hdr.timestamp);
2352    /// }
2353    /// ```
2354    pub fn oldest_sensor<T: SensorData>(&mut self) -> Result<Option<(EntryHeader, T)>, Error> {
2355        schema::read_tagged(|buf| self.oldest(T::SENSOR_ID, buf))
2356    }
2357
2358    /// Count entries for a sensor type.
2359    ///
2360    /// # Returns
2361    /// Number of entries for this sensor type.
2362    ///
2363    /// # Example
2364    ///
2365    /// ```ignore
2366    /// let temp_count = db.count_sensor::<Temperature>()?;
2367    /// ```
2368    pub fn count_sensor<T: SensorData>(&mut self) -> Result<u32, Error> {
2369        self.count(Some(T::SENSOR_ID))
2370    }
2371
2372    // -------------------------------------------------------------------------
2373    // Replication primitives
2374    // -------------------------------------------------------------------------
2375
2376    /// Deliver committed entries in log order, starting at `from` (inclusive).
2377    ///
2378    /// This is the read side of replication: it walks the log as a *stream*
2379    /// rather than a query, so a copy can be resumed from a durable position
2380    /// after a reboot or after the destination went away.
2381    ///
2382    /// # Durability boundary
2383    ///
2384    /// Only entries that are **durable on flash** are delivered. Entries still
2385    /// sitting in the page buffer are excluded, so a caller replicating this log
2386    /// never copies something the source itself could still lose to a power cut.
2387    /// Call [`sync`](Self::sync) first to make the tail eligible.
2388    ///
2389    /// # Arguments
2390    /// - `from`: where to resume. Use [`LogPosition::BEGINNING`] to start at
2391    ///   whatever the log still retains.
2392    /// - `max_entries`: upper bound on entries delivered in this pass. Bounds
2393    ///   both the work done and, for a replicating caller, the amount that has
2394    ///   to be redone after a crash.
2395    /// - `callback`: receives each entry's position, header, and payload.
2396    ///   Return `Ok(false)` to stop, **rejecting** the entry just offered; return
2397    ///   `Err` to abort the pass.
2398    ///
2399    /// # Rejection semantics
2400    ///
2401    /// `Ok(false)` means *"I did not take this one, and I want to stop"*. The
2402    /// entry is not counted in [`ReadCursor::entries`] and
2403    /// [`ReadCursor::next`] stops **before** it, so resuming from `next`
2404    /// re-offers it. Likewise, an `Err` from the callback leaves `next` at the
2405    /// last entry the callback actually accepted.
2406    ///
2407    /// This is the opposite of [`query_range`](Self::query_range), where
2408    /// returning `false` stops *after* consuming the entry — and deliberately
2409    /// so. A caller forwarding this stream to somewhere else must be able to
2410    /// decline an entry (because the destination is full, or the batch has
2411    /// reached a boundary) without the log recording it as delivered.
2412    ///
2413    /// The callback returns `Result<bool, Error>` rather than a bare `bool`
2414    /// because its dominant use is writing each entry somewhere that can fail;
2415    /// a bare `bool` would force every such caller to smuggle the error out
2416    /// through captured state.
2417    ///
2418    /// # Ordering
2419    ///
2420    /// Entries are delivered in write order (ascending sector sequence, then
2421    /// ascending offset), which is not necessarily timestamp order — the same
2422    /// caveat as [`query_range`](Self::query_range).
2423    ///
2424    /// # Errors
2425    /// - `NotMounted` if the database is not mounted
2426    /// - whatever the callback returns
2427    pub fn read_from<C>(
2428        &mut self,
2429        from: LogPosition,
2430        max_entries: u32,
2431        mut callback: C,
2432    ) -> Result<ReadCursor, Error>
2433    where
2434        C: FnMut(LogPosition, &EntryHeader, &[u8]) -> Result<bool, Error>,
2435    {
2436        if !self.state.mounted {
2437            return Err(Error::NotMounted);
2438        }
2439
2440        // Collect retained sectors at or after `from`, and find the oldest
2441        // retained sequence so we can tell whether `from` fell off the tail.
2442        let mut order: HeaplessVec<(u16, u32), MAX_SECTORS> = HeaplessVec::new();
2443        let mut oldest_seq = u32::MAX;
2444        for i in 0..self.state.sector_count {
2445            let summary = &self.state.sectors[i as usize];
2446            if summary.state == SectorState::Erased {
2447                continue;
2448            }
2449            if summary.sequence < oldest_seq {
2450                oldest_seq = summary.sequence;
2451            }
2452            if summary.sequence >= from.sequence {
2453                let _ = order.push((i, summary.sequence));
2454            }
2455        }
2456        sort_by_seq(&mut order, u32::cmp);
2457
2458        let gap =
2459            from != LogPosition::BEGINNING && oldest_seq != u32::MAX && from.sequence < oldest_seq;
2460
2461        let mut cursor = ReadCursor {
2462            next: from,
2463            entries: 0,
2464            exhausted: false,
2465            gap,
2466        };
2467
2468        if max_entries == 0 {
2469            return Ok(cursor);
2470        }
2471
2472        let flash = &mut self.flash;
2473        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
2474        let mut buf = [0u8; PAGE_SIZE];
2475        let mut stopped = false;
2476
2477        for (sector_idx, seq) in order {
2478            let sector_offset = self.state.sector_offset(sector_idx);
2479            // `write_offset` is the right limit even for the active sector: the
2480            // bytes past the last flush read back as 0xFF, so the scanner runs
2481            // out of page before it runs out of limit and stops on its own.
2482            let limit = self.state.sectors[sector_idx as usize].write_offset;
2483            let start = if seq == from.sequence {
2484                from.offset.max(SECTOR_HEADER_SIZE as u32)
2485            } else {
2486                SECTOR_HEADER_SIZE as u32
2487            };
2488            if start >= limit {
2489                continue;
2490            }
2491
2492            let mut scanner = SectorScanner::new(sector_offset, start, limit);
2493            while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
2494                if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
2495                    scanner.skip(1);
2496                    continue;
2497                }
2498
2499                let position = LogPosition {
2500                    sequence: seq,
2501                    offset: entry.offset_in_sector,
2502                };
2503                let header = entry.header.to_header();
2504                // A rejected entry must not advance the cursor past it, or the
2505                // caller would resume after something it never accepted.
2506                if !callback(position, &header, &buf[..entry.payload_len])? {
2507                    stopped = true;
2508                    break;
2509                }
2510
2511                scanner.skip(entry.entry_size);
2512                cursor.entries += 1;
2513                cursor.next = LogPosition {
2514                    sequence: seq,
2515                    offset: scanner.offset(),
2516                };
2517
2518                if cursor.entries >= max_entries {
2519                    stopped = true;
2520                    break;
2521                }
2522            }
2523
2524            if stopped {
2525                break;
2526            }
2527        }
2528
2529        cursor.exhausted = !stopped;
2530        Ok(cursor)
2531    }
2532
2533    /// Hand out entries that are buffered in RAM but not yet durable, then
2534    /// discard them from this database.
2535    ///
2536    /// **Touches no flash.** This is what makes it usable when the underlying
2537    /// device has physically gone away: a removable medium can be pulled
2538    /// mid-page, and the entries still sitting in the page buffer are recovered
2539    /// into RAM and can be re-appended somewhere that still exists. A yank is
2540    /// not a power loss — the processor is still running, so nothing needs to be
2541    /// lost.
2542    ///
2543    /// Entries already durable on flash are left alone; only the RAM-only tail
2544    /// is drained. On return the page buffer is truncated to its durable prefix
2545    /// and the entry accounting is adjusted to match.
2546    ///
2547    /// "Durable" here means *written to flash*, which is not the same as the
2548    /// entry's committed flag: a commit pass that failed part-way leaves entries
2549    /// flagged committed in RAM that flash never received. Those are drained,
2550    /// because a later `mount` would not see them.
2551    ///
2552    /// The per-sector bloom filter and timestamp range are *not* rolled back —
2553    /// they may stay wider than the data warrants, which costs a redundant
2554    /// sector scan on some queries but never returns a wrong answer.
2555    ///
2556    /// # Returns
2557    /// The number of entries handed to the callback.
2558    ///
2559    /// # Errors
2560    /// - `NotMounted` if the database is not mounted
2561    /// - whatever the callback returns; the drain stops there and the buffer is
2562    ///   left untouched, so the operation can be retried
2563    pub fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
2564    where
2565        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
2566    {
2567        self.state.drain_unflushed(callback)
2568    }
2569
2570    /// Show the entries that are buffered in RAM but not yet durable, without
2571    /// removing them.
2572    ///
2573    /// The non-destructive twin of [`drain_unflushed`](Self::drain_unflushed),
2574    /// and the piece [`read_from`](Self::read_from) deliberately leaves out:
2575    /// `read_from` streams only what flash has, because a replica must never be
2576    /// told about data the source could still lose, whereas a *reader* of this
2577    /// log should see everything the log holds. Composing the two covers the
2578    /// whole log from a position.
2579    ///
2580    /// Touches no flash, so it costs nothing, works on a device that has gone
2581    /// away, and is one of the few reads that still takes `&self`.
2582    ///
2583    /// # Errors
2584    /// - `NotMounted` if the database is not mounted
2585    /// - whatever the callback returns, which stops the walk
2586    pub fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
2587    where
2588        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
2589    {
2590        self.state.peek_unflushed(callback)
2591    }
2592
2593    /// The epoch of the sector containing `position`.
2594    ///
2595    /// Reads the sector header from flash on demand rather than caching an
2596    /// epoch per sector in RAM — with `MAX_SECTORS = 512` that cache would cost
2597    /// 2 KB for a field consulted once per replication batch.
2598    ///
2599    /// Returns `None` when no retained sector holds that position, which is the
2600    /// normal answer for a position that has fallen off the tail of the ring.
2601    pub fn sector_epoch_at(&mut self, position: LogPosition) -> Result<Option<u32>, Error> {
2602        if !self.state.mounted {
2603            return Err(Error::NotMounted);
2604        }
2605        let Some(idx) = self.state.sector_at_sequence(position.sequence) else {
2606            return Ok(None);
2607        };
2608
2609        let offset = self.state.sector_offset(idx);
2610        let mut buf = [0u8; SECTOR_HEADER_SIZE];
2611        self.flash.read(offset, &mut buf)?;
2612        let header = SectorHeader::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
2613        Ok(header.is_valid().then(|| header.epoch.get()))
2614    }
2615
2616    /// Position immediately after the newest entry, buffered entries included.
2617    ///
2618    /// Note this can be ahead of what [`read_from`](Self::read_from) will
2619    /// deliver, which stops at the durable tail. Returns
2620    /// [`LogPosition::BEGINNING`] when there is no active sector.
2621    pub fn head_position(&self) -> LogPosition {
2622        self.state.head_position()
2623    }
2624
2625    /// Position of the oldest entry the log still retains.
2626    ///
2627    /// A [`read_from`](Self::read_from) starting before this reports a gap.
2628    /// Returns [`LogPosition::BEGINNING`] when the log is empty.
2629    pub fn tail_position(&self) -> LogPosition {
2630        self.state.tail_position()
2631    }
2632
2633    /// Run `f` with flash access bounded to `[base, base + len)`.
2634    ///
2635    /// This is how something else on the same chip — a config store, a
2636    /// replication cursor, a firmware slot — reaches the device the database
2637    /// owns by value. The closure gets a [`Partition`], so its offsets are
2638    /// relative to `base` and an access past `len` is
2639    /// [`PartitionError::OutOfBounds`](crate::PartitionError::OutOfBounds)
2640    /// rather than a write into a neighbour.
2641    ///
2642    /// A region intersecting `[base_offset, base_offset + sector_count *
2643    /// sector_size)` is rejected with [`Error::RegionOverlap`]. That check is
2644    /// the point of this method: writing inside the database region behind the
2645    /// database's back corrupts the log, the in-RAM index silently disagrees
2646    /// with flash, and nothing surfaces until a later mount.
2647    ///
2648    /// For a *driver* capability rather than a region — presence detection, a
2649    /// wear counter, a chip id, deep power-down — use
2650    /// [`driver_mut`](Self::driver_mut).
2651    ///
2652    /// # Errors
2653    /// - `RegionOverlap` if the region intersects the database's sectors
2654    /// - `InvalidConfig` if `base` or `len` is misaligned, `len` is zero, or the
2655    ///   region runs past the device's capacity
2656    /// - `Overflow` if `base + len` does not fit in `u32`
2657    ///
2658    /// ```ignore
2659    /// // Read the config block that lives just below the log.
2660    /// let mut buf = [0u8; 64];
2661    /// db.with_region(CONFIG_BASE, CONFIG_LEN, |p| p.read(0, &mut buf))??;
2662    /// ```
2663    pub fn with_region<R>(
2664        &mut self,
2665        base: u32,
2666        len: u32,
2667        f: impl FnOnce(&mut Partition<&mut F>) -> R,
2668    ) -> Result<R, Error> {
2669        self.state.check_disjoint(base, len)?;
2670        let mut partition = Partition::new(&mut self.flash, base, len)?;
2671        Ok(f(&mut partition))
2672    }
2673
2674    /// Borrow the underlying flash driver.
2675    ///
2676    /// For capabilities that belong to the *driver* rather than to any region of
2677    /// the chip: presence detection, wear counters, chip identification, power
2678    /// modes, and test introspection. The database owns `F` by value, so without
2679    /// this nothing else can reach those.
2680    ///
2681    /// # Correctness
2682    ///
2683    /// This is the unbounded escape hatch, and nothing here can enforce
2684    /// anything: `F` is a `NorFlash`, so a caller *can* write anywhere on the
2685    /// chip. **Do not address flash through it.** Use
2686    /// [`with_region`](Self::with_region), which is checked.
2687    pub fn driver_mut(&mut self) -> &mut F {
2688        &mut self.flash
2689    }
2690
2691    /// Advance the replication watermark.
2692    ///
2693    /// Call this only after `moved`, ending at `upto`, is **durably** stored
2694    /// somewhere else. Advancing it early is the one way to turn this design's
2695    /// at-least-once guarantee into data loss: the watermark is what tells the
2696    /// ring which sectors are safe to overwrite first.
2697    ///
2698    /// Monotonic — an `upto` at or behind the current watermark is ignored, so
2699    /// replaying an old acknowledgement cannot move it backwards.
2700    pub fn note_spooled(&mut self, upto: LogPosition, moved: Replicated) {
2701        self.state.note_spooled(upto, moved);
2702    }
2703
2704    /// Restore the replication watermark from an external source of truth.
2705    ///
2706    /// [`mount`](Self::mount) deliberately cannot recover this: the watermark
2707    /// lives on the replica, which is what lets two removable media be rotated
2708    /// against one log with no local state. Until a replica reappears and calls
2709    /// this, [`spool_stats`](Self::spool_stats) reports everything as
2710    /// un-replicated — the safe direction, because it can only cause redundant
2711    /// copying, never loss.
2712    ///
2713    /// Accounting is recomputed from the in-RAM index for whole sectors, plus one
2714    /// scan of the sector the watermark falls *inside* — the index knows how many
2715    /// entries a sector holds but not where each one starts, so the entries below
2716    /// the watermark within that sector have to be counted off flash. The result
2717    /// matches what [`note_spooled`](Self::note_spooled) would have accumulated
2718    /// had the replica never gone away.
2719    ///
2720    /// # Errors
2721    ///
2722    /// Only from that one scan, and only ever `Flash`. The watermark itself is
2723    /// restored *before* the scan and stays restored, because it is the part that
2724    /// matters: it is what tells the ring which sectors are safe to overwrite.
2725    /// An `Err` therefore means the log is fully usable and only
2726    /// [`spool_stats`](Self::spool_stats) is degraded — it over-reports
2727    /// `unspooled_entries` by at most one sector's worth, the same conservative
2728    /// answer this method used to give unconditionally.
2729    pub fn restore_spool_watermark(&mut self, upto: LogPosition) -> Result<(), Error> {
2730        let Some(boundary) = self.state.restore_spool_watermark(upto) else {
2731            return Ok(());
2732        };
2733        let counted = self
2734            .state
2735            .count_entries_before(&mut self.flash, boundary, upto.offset)?;
2736        self.state.add_spooled(counted);
2737        Ok(())
2738    }
2739
2740    /// Replication accounting for this log.
2741    ///
2742    /// `unspooled_entries` is O(1). See [`SpoolStats`] for the meaning of each
2743    /// field, and note that `data_lost` is sticky.
2744    pub fn spool_stats(&self) -> SpoolStats {
2745        self.state.spool_stats()
2746    }
2747
2748    /// This log's declared identity, if any.
2749    pub fn log_id(&self) -> Option<LogId> {
2750        self.state.log_id
2751    }
2752
2753    /// The current epoch — one higher than any epoch found on the medium at mount.
2754    ///
2755    /// Stamped into every sector header this run creates, which is what lets a
2756    /// reader attribute data to a particular run of a device whose clock
2757    /// restarts at zero on every boot.
2758    ///
2759    /// # How a run's epoch reaches the medium
2760    ///
2761    /// Epochs live in sector headers, so a run only records one by creating a
2762    /// sector. To keep the attribution exact, the **first append after a mount
2763    /// rolls to a fresh sector** rather than continuing in the one the previous
2764    /// run left open. Every entry a run writes therefore sits in a sector
2765    /// stamped with that run's epoch.
2766    ///
2767    /// The roll is deferred to the first append, so a run that only reads costs
2768    /// nothing. A run that writes costs one extra sector transition — one erase,
2769    /// plus whatever space was left unused in the inherited sector. That is
2770    /// cheap when reboots are rare, which is the case this is built for.
2771    ///
2772    /// If the ring is completely full and cannot yield a sector, the roll is
2773    /// skipped rather than failing the append: losing epoch precision is always
2774    /// preferable to losing a sample. Replication correctness never depends on
2775    /// the epoch — it rests on [`LogPosition`].
2776    pub fn epoch(&self) -> u32 {
2777        self.state.epoch
2778    }
2779
2780    /// How much of the index the current mount rebuilt.
2781    pub fn mount_mode(&self) -> MountMode {
2782        self.state.mount_mode
2783    }
2784
2785    /// Declare this log a replica of another, suppressing the per-run epoch roll.
2786    ///
2787    /// A primary log rolls to a fresh sector on its first append after a mount
2788    /// so that the run's [`epoch`](Self::epoch) is recorded on the medium. For a
2789    /// replica that is pure waste: its entries are copies, and their provenance
2790    /// lives in the replication cursor, not in this log's sector headers. Left
2791    /// enabled it would burn a sector — and on a full ring, evict the oldest one
2792    /// — every single time the medium is inserted.
2793    ///
2794    /// [`Spooler::attach`](crate::spool::Spooler::attach) calls this, so a
2795    /// volume managed by a spooler needs no action. Call it directly only when
2796    /// maintaining a replica by hand.
2797    ///
2798    /// Takes effect for the current mount; call it again after each `mount`.
2799    pub fn mark_as_replica(&mut self) {
2800        self.state.epoch_pending = false;
2801    }
2802
2803    /// Consume the database and return the underlying flash storage.
2804    pub fn into_inner(self) -> F {
2805        self.flash
2806    }
2807}
2808
2809// =============================================================================
2810// SensorDbState — all non-flash state and helpers
2811// =============================================================================
2812
2813impl<const PAGE_SIZE: usize, const MAX_SECTORS: usize> SensorDbState<PAGE_SIZE, MAX_SECTORS> {
2814    // -------------------------------------------------------------------------
2815    // Pure state helpers (no flash parameter)
2816    // -------------------------------------------------------------------------
2817
2818    pub(crate) fn sector_offset(&self, sector_idx: u16) -> u32 {
2819        // Safety: `new()` validates that base_offset + sector_count * sector_size
2820        // fits in u32, so this cannot overflow for any valid sector_idx.
2821        self.base_offset + sector_idx as u32 * self.sector_size
2822    }
2823
2824    /// Offset within a sector of the reserved footer page.
2825    ///
2826    /// Doubles as the limit for entry data: everything from here to the end of
2827    /// the sector belongs to the [`SectorFooter`]
2828    /// written when the sector is sealed, so `append` must stop before it and
2829    /// every scan must be bounded by it.
2830    ///
2831    /// Cannot underflow: `new` rejects a sector smaller than three pages.
2832    pub(crate) fn footer_offset(&self) -> u32 {
2833        self.sector_size - PAGE_SIZE as u32
2834    }
2835
2836    /// Byte after the last byte of the database region.
2837    pub(crate) fn region_end(&self) -> u32 {
2838        self.base_offset + self.sector_count as u32 * self.sector_size
2839    }
2840
2841    /// Reject a region that intersects the database's own sectors.
2842    ///
2843    /// This is the check that turns the old "only touch addresses outside the
2844    /// database region" doc comment into something enforced. Shared by both
2845    /// drivers so the rule is stated once.
2846    pub(crate) fn check_disjoint(&self, base: u32, len: u32) -> Result<(), Error> {
2847        let end = (base as u64)
2848            .checked_add(len as u64)
2849            .ok_or(Error::Overflow)?;
2850        let (db_base, db_end) = (self.base_offset, self.region_end());
2851        if (base as u64) < db_end as u64 && (db_base as u64) < end {
2852            return Err(Error::RegionOverlap { db_base, db_end });
2853        }
2854        Ok(())
2855    }
2856
2857    /// Choose the sector to write into next.
2858    ///
2859    /// Pure selection — this mutates no counters. The caller applies
2860    /// [`account_eviction`](Self::account_eviction) *after* the erase succeeds,
2861    /// so a failed erase cannot leave the index claiming data is gone.
2862    pub(crate) fn find_next_sector(&mut self) -> Result<u16, Error> {
2863        // Tier 1: an already-erased sector, lowest erase count (wear levelling).
2864        // Tie-break: round-robin starting from active_sector + 1.
2865        let start = self
2866            .active_sector
2867            .map_or(0, |a| (a + 1) % self.sector_count);
2868        let mut best_idx: Option<u16> = None;
2869        let mut best_erase = u32::MAX;
2870        for offset in 0..self.sector_count {
2871            let i = (start + offset) % self.sector_count;
2872            let summary = &self.sectors[i as usize];
2873            if summary.state == SectorState::Erased && summary.erase_count < best_erase {
2874                best_erase = summary.erase_count;
2875                best_idx = Some(i);
2876            }
2877        }
2878        if let Some(idx) = best_idx {
2879            return Ok(idx);
2880        }
2881
2882        // No erased sectors — reclaim a sealed one, respecting reserved_sectors.
2883        let sealed_count: u16 = self.sectors[..self.sector_count as usize]
2884            .iter()
2885            .filter(|s| s.state == SectorState::Sealed)
2886            .count() as u16;
2887
2888        if sealed_count <= self.reserved_sectors {
2889            return Err(Error::NoSpace);
2890        }
2891
2892        // Tier 2: the oldest sealed sector whose contents are fully replicated.
2893        // Tier 3: the oldest sealed sector at all — this destroys data that was
2894        // never replicated, which `account_eviction` records as a loss.
2895        //
2896        // These select the same sector in every state reachable today, because
2897        // replication proceeds oldest-first and so the replicated set is always a
2898        // prefix of the ring by sequence. The tiers are written out anyway: they
2899        // make the choice explicit rather than incidental, and they are where a
2900        // refuse-to-overwrite policy would hook in.
2901        self.oldest_sealed(true)
2902            .or_else(|| self.oldest_sealed(false))
2903            .ok_or(Error::NoSpace)
2904    }
2905
2906    // -------------------------------------------------------------------------
2907    // Replication bookkeeping (pure; shared by both flavours)
2908    // -------------------------------------------------------------------------
2909
2910    pub(crate) fn head_position(&self) -> LogPosition {
2911        match self.active_sector {
2912            Some(idx) => LogPosition {
2913                sequence: self.sectors[idx as usize].sequence,
2914                offset: self.sectors[idx as usize].write_offset,
2915            },
2916            None => LogPosition::BEGINNING,
2917        }
2918    }
2919
2920    pub(crate) fn tail_position(&self) -> LogPosition {
2921        let mut oldest: Option<u32> = None;
2922        for i in 0..self.sector_count {
2923            let summary = &self.sectors[i as usize];
2924            if summary.state != SectorState::Erased
2925                && oldest.is_none_or(|seq| summary.sequence < seq)
2926            {
2927                oldest = Some(summary.sequence);
2928            }
2929        }
2930        match oldest {
2931            Some(sequence) => LogPosition {
2932                sequence,
2933                offset: SECTOR_HEADER_SIZE as u32,
2934            },
2935            None => LogPosition::BEGINNING,
2936        }
2937    }
2938
2939    pub(crate) fn note_spooled(&mut self, upto: LogPosition, moved: Replicated) {
2940        if upto <= self.spool_watermark {
2941            return;
2942        }
2943        self.spool_watermark = upto;
2944        self.add_spooled(moved);
2945    }
2946
2947    /// Index of the retained sector carrying `sequence`, if the ring still holds it.
2948    pub(crate) fn sector_at_sequence(&self, sequence: u32) -> Option<u16> {
2949        (0..self.sector_count).find(|i| {
2950            let summary = &self.sectors[*i as usize];
2951            summary.state != SectorState::Erased && summary.sequence == sequence
2952        })
2953    }
2954
2955    /// Set the watermark and recompute accounting from whole sectors alone.
2956    ///
2957    /// Returns the sector the watermark falls *inside*, whose entries below it
2958    /// this cannot count from the in-RAM index — sector summaries record how many
2959    /// entries a sector holds, not where each one starts. Refining that is one
2960    /// bounded scan, which only the flash-holding caller can perform; until it
2961    /// does, the accounting under-reports what has been replicated, which is the
2962    /// safe direction.
2963    pub(crate) fn restore_spool_watermark(&mut self, upto: LogPosition) -> Option<u16> {
2964        if upto <= self.spool_watermark {
2965            return None;
2966        }
2967        self.spool_watermark = upto;
2968        self.spooled_entries = self.spooled_in_whole_sectors().min(self.total_entries);
2969        self.spooled_samples = self
2970            .spooled_samples_in_whole_sectors()
2971            .min(self.total_samples);
2972
2973        // The sector the watermark falls inside, if it holds anything below it.
2974        self.sector_at_sequence(upto.sequence).filter(|i| {
2975            upto.offset > SECTOR_HEADER_SIZE as u32 && self.sectors[*i as usize].entry_count > 0
2976        })
2977    }
2978
2979    /// Credit more as replicated, never past what the log still holds.
2980    pub(crate) fn add_spooled(&mut self, moved: Replicated) {
2981        self.spooled_entries = self
2982            .spooled_entries
2983            .saturating_add(moved.entries)
2984            .min(self.total_entries);
2985        self.spooled_samples = self
2986            .spooled_samples
2987            .saturating_add(moved.samples)
2988            .min(self.total_samples);
2989    }
2990
2991    pub(crate) fn spool_stats(&self) -> SpoolStats {
2992        SpoolStats {
2993            unspooled_entries: self.total_entries.saturating_sub(self.spooled_entries),
2994            unspooled_samples: self.total_samples.saturating_sub(self.spooled_samples),
2995            watermark: self.spool_watermark,
2996            head: self.head_position(),
2997            dropped_unspooled: self.dropped_unspooled,
2998            data_lost: self.dropped_unspooled > 0,
2999        }
3000    }
3001
3002    /// First byte of the page buffer that flash does not yet have.
3003    ///
3004    /// Everything below `page_buf_durable` is on flash; everything from here to
3005    /// `page_buf_offset` exists only in RAM.
3006    ///
3007    /// The flags byte deliberately plays no part. `flush_page` sets flags to
3008    /// committed in the buffer *before* writing it, so a commit pass that failed
3009    /// leaves entries marked committed in RAM while flash still has them
3010    /// uncommitted — invisible to a later `mount`. Trusting the flag would
3011    /// silently skip exactly the entries this boundary exists to identify.
3012    fn unflushed_start(&self) -> usize {
3013        self.page_buf_scan_start().max(self.page_buf_durable)
3014    }
3015
3016    /// Walk the RAM-only tail of the page buffer without changing it.
3017    ///
3018    /// Stops at the first byte that is not the start of a whole entry, which is
3019    /// how a partially written tail is bounded.
3020    /// Walks *entries*, not samples: this is the replication and rescue side,
3021    /// where a run must stay a run so the copy keeps its amortisation.
3022    fn walk_unflushed<C>(&self, mut callback: C) -> Result<Replicated, Error>
3023    where
3024        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3025    {
3026        let end = self.page_buf_offset;
3027        let mut seen = Replicated::NONE;
3028        let mut pos = self.unflushed_start();
3029        while let Some(entry) = self.next_buffered(&mut pos, end) {
3030            let payload = self.buffered_payload(&entry);
3031            callback(&entry.header.to_header(), payload)?;
3032            seen.push(samples_in(entry.is_run(), payload));
3033        }
3034        Ok(seen)
3035    }
3036
3037    pub(crate) fn peek_unflushed<C>(&self, callback: C) -> Result<u32, Error>
3038    where
3039        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3040    {
3041        if !self.mounted {
3042            return Err(Error::NotMounted);
3043        }
3044        Ok(self.walk_unflushed(callback)?.entries)
3045    }
3046
3047    pub(crate) fn drain_unflushed<C>(&mut self, callback: C) -> Result<u32, Error>
3048    where
3049        C: FnMut(&EntryHeader, &[u8]) -> Result<(), Error>,
3050    {
3051        if !self.mounted {
3052            return Err(Error::NotMounted);
3053        }
3054
3055        let scan_start = self.unflushed_start();
3056        let end = self.page_buf_offset;
3057        if scan_start >= end {
3058            return Ok(0);
3059        }
3060
3061        let drained = self.walk_unflushed(callback)?;
3062        if drained.entries == 0 {
3063            return Ok(0);
3064        }
3065        let truncate_to = scan_start;
3066
3067        // Drop the non-durable suffix from the page buffer and undo its
3068        // contribution to the in-RAM index.
3069        let bytes_dropped = (end - truncate_to) as u32;
3070        self.page_buf[truncate_to..].fill(0xFF);
3071        self.page_buf_offset = truncate_to;
3072
3073        if let Some(active_idx) = self.active_sector {
3074            let summary = &mut self.sectors[active_idx as usize];
3075            summary.entry_count = summary.entry_count.saturating_sub(drained.entries);
3076            summary.sample_count = summary.sample_count.saturating_sub(drained.samples);
3077            summary.write_offset = summary.write_offset.saturating_sub(bytes_dropped);
3078        }
3079        self.total_entries = self.total_entries.saturating_sub(drained.entries);
3080        self.total_samples = self.total_samples.saturating_sub(drained.samples);
3081
3082        Ok(drained.entries)
3083    }
3084
3085    /// Index of the oldest sealed sector, optionally restricted to sectors whose
3086    /// contents are fully replicated.
3087    fn oldest_sealed(&self, require_spooled: bool) -> Option<u16> {
3088        let mut oldest_idx = None;
3089        let mut oldest_seq = u32::MAX;
3090        for i in 0..self.sector_count {
3091            let summary = &self.sectors[i as usize];
3092            if summary.state != SectorState::Sealed || summary.sequence >= oldest_seq {
3093                continue;
3094            }
3095            if require_spooled && !self.is_fully_spooled(summary) {
3096                continue;
3097            }
3098            oldest_seq = summary.sequence;
3099            oldest_idx = Some(i);
3100        }
3101        oldest_idx
3102    }
3103
3104    // -------------------------------------------------------------------------
3105    // Page buffer scanning helpers (flush-free reads, no flash needed)
3106    // -------------------------------------------------------------------------
3107
3108    /// Returns the starting offset within `page_buf` for entry scanning.
3109    pub(crate) fn page_buf_scan_start(&self) -> usize {
3110        let active_idx = match self.active_sector {
3111            Some(idx) => idx,
3112            None => return self.page_buf_offset, // no active sector, nothing to scan
3113        };
3114        if self.page_flash_offset == self.sector_offset(active_idx) {
3115            SECTOR_HEADER_SIZE
3116        } else {
3117            0
3118        }
3119    }
3120
3121    /// Step the cursor `pos` over one whole entry in the page buffer.
3122    ///
3123    /// Returns `None` at the first byte that does not begin one, which is how a
3124    /// partially written tail is bounded — and is why every page-buffer walk
3125    /// goes through here rather than repeating the arithmetic. Committed entries
3126    /// are returned too: whether to skip them differs by caller (a reader has
3127    /// them from flash already; a rescue must not assume flash does).
3128    fn next_buffered(&self, pos: &mut usize, end: usize) -> Option<BufferedEntry> {
3129        if *pos + ENTRY_HEADER_SIZE > end || !is_entry_marker(self.page_buf[*pos]) {
3130            return None;
3131        }
3132        let header =
3133            EntryHeaderWire::read_from_bytes(&self.page_buf[*pos..*pos + ENTRY_HEADER_SIZE])
3134                .ok()?;
3135        let payload_len = header.payload_len.get() as usize;
3136        if *pos + ENTRY_OVERHEAD + payload_len > end {
3137            return None;
3138        }
3139        let payload_start = *pos + ENTRY_HEADER_SIZE;
3140        *pos += ENTRY_OVERHEAD + payload_len;
3141        Some(BufferedEntry {
3142            header,
3143            payload_start,
3144            payload_len,
3145        })
3146    }
3147
3148    /// The payload of a buffered entry.
3149    fn buffered_payload(&self, entry: &BufferedEntry) -> &[u8] {
3150        &self.page_buf[entry.payload_start..entry.payload_start + entry.payload_len]
3151    }
3152
3153    /// The sample at one `edge` of a buffered entry, and the header it would
3154    /// have carried had it been appended alone.
3155    fn buffered_sample(&self, entry: &BufferedEntry, edge: Edge) -> (EntryHeader, BufferedSample) {
3156        let located = |run| BufferedSample {
3157            payload_start: entry.payload_start,
3158            payload_len: entry.payload_len,
3159            run,
3160        };
3161
3162        match RunFrame::parse(self.buffered_payload(entry)).filter(|_| entry.is_run()) {
3163            Some(frame) => {
3164                let index = match edge {
3165                    Edge::First => 0,
3166                    Edge::Last => frame.count() - 1,
3167                };
3168                (
3169                    frame.header_at(entry.sensor_id(), entry.timestamp(), index),
3170                    located(Some((frame, index))),
3171                )
3172            }
3173            None => (entry.header.to_header(), located(None)),
3174        }
3175    }
3176
3177    /// Write a located sample into `out` as a schema-tagged payload.
3178    fn copy_buffered_sample(
3179        &self,
3180        sample: &BufferedSample,
3181        out: &mut [u8],
3182    ) -> Result<usize, Error> {
3183        let payload =
3184            &self.page_buf[sample.payload_start..sample.payload_start + sample.payload_len];
3185        match sample.run {
3186            Some((frame, index)) => frame
3187                .write_tagged_sample(payload, index, out)
3188                .ok_or(Error::BufferTooSmall),
3189            None => {
3190                if payload.len() > out.len() {
3191                    return Err(Error::BufferTooSmall);
3192                }
3193                out[..payload.len()].copy_from_slice(payload);
3194                Ok(payload.len())
3195            }
3196        }
3197    }
3198
3199    /// The newest unflushed entry for a sensor, if it beats `min_ts`.
3200    ///
3201    /// Reports `BufferTooSmall` when the winner does not fit `buf`, matching
3202    /// [`find_latest_in_sector`](Self::find_latest_in_sector). Skipping it
3203    /// instead — as this used to — meant a caller with a small buffer was
3204    /// handed an *older* entry, or `None`, and told it was the latest.
3205    pub(crate) fn scan_page_buf_for_latest(
3206        &self,
3207        sensor_id: u16,
3208        min_ts: u64,
3209        buf: &mut [u8],
3210    ) -> Result<Option<(EntryHeader, usize)>, Error> {
3211        let scan_start = self.page_buf_scan_start();
3212        if scan_start >= self.page_buf_offset {
3213            return Ok(None);
3214        }
3215
3216        let mut best: Option<(EntryHeader, BufferedSample)> = None;
3217        let mut best_ts: u64 = min_ts;
3218        let mut pos = scan_start;
3219
3220        while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3221            // Skip committed entries — they are already on flash
3222            if entry.is_committed() || entry.sensor_id() != sensor_id {
3223                continue;
3224            }
3225
3226            // The buffer bound is deliberately *not* part of this test: an
3227            // entry that wins on timestamp wins, and its size is reported
3228            // below rather than letting an older entry take its place.
3229            let (header, sample) = self.buffered_sample(&entry, Edge::Last);
3230            if header.timestamp >= best_ts {
3231                best_ts = header.timestamp;
3232                best = Some((header, sample));
3233            }
3234        }
3235
3236        // Copy payload only for the final winner
3237        let Some((header, sample)) = best else {
3238            return Ok(None);
3239        };
3240        let len = self.copy_buffered_sample(&sample, buf)?;
3241        Ok(Some((header, len)))
3242    }
3243
3244    /// Deliver unflushed samples in a time range.
3245    ///
3246    /// `scratch` receives a copy of each entry's payload, because
3247    /// [`deliver_samples`] frames a run's samples by writing through the buffer
3248    /// it is given and the page buffer is behind a shared reference. The caller
3249    /// lends the same buffer the sector scan used, so this costs no stack.
3250    pub(crate) fn scan_page_buf_for_query<C>(
3251        &self,
3252        sensor_filter: Option<u16>,
3253        t_start: u64,
3254        t_end: u64,
3255        scratch: &mut [u8],
3256        count: &mut u32,
3257        callback: &mut C,
3258    ) -> bool
3259    where
3260        C: FnMut(&EntryHeader, &[u8]) -> bool,
3261    {
3262        let mut pos = self.page_buf_scan_start();
3263
3264        while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3265            // Skip committed entries — already visible via flash reads
3266            let sensor = entry.sensor_id();
3267            if entry.is_committed() || sensor_filter.is_some_and(|f| f != sensor) {
3268                continue;
3269            }
3270
3271            let payload = self.buffered_payload(&entry);
3272            // Cannot fail: `scratch` is a page and a payload is smaller.
3273            let Some(dst) = scratch.get_mut(..payload.len()) else {
3274                continue;
3275            };
3276            dst.copy_from_slice(payload);
3277
3278            if deliver_samples(
3279                entry.is_run(),
3280                sensor,
3281                entry.timestamp(),
3282                dst,
3283                t_start,
3284                t_end,
3285                count,
3286                callback,
3287            ) {
3288                return true; // stopped early
3289            }
3290        }
3291
3292        false
3293    }
3294
3295    pub(crate) fn scan_page_buf_for_oldest(
3296        &self,
3297        sensor_id: u16,
3298        buf: &mut [u8],
3299    ) -> Option<(EntryHeader, usize)> {
3300        let mut pos = self.page_buf_scan_start();
3301
3302        while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3303            // Skip committed entries — already visible via flash reads
3304            if entry.is_committed() || entry.sensor_id() != sensor_id {
3305                continue;
3306            }
3307
3308            let (header, sample) = self.buffered_sample(&entry, Edge::First);
3309            if let Ok(len) = self.copy_buffered_sample(&sample, buf) {
3310                return Some((header, len));
3311            }
3312        }
3313
3314        None
3315    }
3316
3317    pub(crate) fn count_sensor_in_page_buf(&self, sensor_id: u16) -> u32 {
3318        let mut count = 0u32;
3319        let mut pos = self.page_buf_scan_start();
3320
3321        while let Some(entry) = self.next_buffered(&mut pos, self.page_buf_offset) {
3322            // Skip committed entries — already counted via sector scanning
3323            if entry.is_committed() || entry.sensor_id() != sensor_id {
3324                continue;
3325            }
3326            count += samples_in(entry.is_run(), self.buffered_payload(&entry));
3327        }
3328
3329        count
3330    }
3331
3332    // -------------------------------------------------------------------------
3333    // Flash-accessing helpers (take explicit `flash: &mut F` parameter)
3334    // -------------------------------------------------------------------------
3335
3336    fn erase_sector<F: NorFlash>(&mut self, flash: &mut F, sector_idx: u16) -> Result<(), Error> {
3337        let offset = self.sector_offset(sector_idx);
3338        flash.erase(offset, offset + self.sector_size)?;
3339        // After the erase, so the count is of sectors actually erased. A failure
3340        // reaches the caller as an error, which is a louder signal than this.
3341        self.sectors_erased = self.sectors_erased.saturating_add(1);
3342        Ok(())
3343    }
3344
3345    fn init_sector<F: NorFlash>(
3346        &self,
3347        flash: &mut F,
3348        sector_idx: u16,
3349        sequence: u32,
3350        erase_count: u32,
3351    ) -> Result<(), Error> {
3352        let header = self.sector_header(sequence, erase_count);
3353        let offset = self.sector_offset(sector_idx);
3354
3355        // Write header (padded to page size)
3356        let mut page = [0xFFu8; PAGE_SIZE];
3357        page[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
3358        flash.write(offset, &page)?;
3359
3360        Ok(())
3361    }
3362
3363    /// Read and validate the footer of `sector_idx`.
3364    ///
3365    /// Returns `None` for anything that does not describe this sector's current
3366    /// incarnation — an erased page, a torn write, a stale summary — which the
3367    /// caller answers with a body scan.
3368    fn read_sector_footer<F: ReadNorFlash>(
3369        &self,
3370        flash: &mut F,
3371        sector_idx: u16,
3372    ) -> Result<Option<SectorFooter>, Error> {
3373        let offset = self.sector_offset(sector_idx) + self.footer_offset();
3374        let mut buf = [0u8; SECTOR_FOOTER_SIZE];
3375        flash.read(offset, &mut buf)?;
3376
3377        let footer = SectorFooter::read_from_bytes(&buf).map_err(|_| Error::CorruptEntry)?;
3378        let sequence = self.sectors[sector_idx as usize].sequence;
3379        Ok(footer.describes(sequence).then_some(footer))
3380    }
3381
3382    /// Write `sector_idx`'s summary into its reserved final page.
3383    ///
3384    /// Called once per sector, when it is sealed and its contents are final.
3385    fn write_sector_footer<F: NorFlash>(
3386        &self,
3387        flash: &mut F,
3388        sector_idx: u16,
3389    ) -> Result<(), Error> {
3390        // Nothing buffered may be missing from the summary being frozen. Every
3391        // path into `seal_and_advance` either has just flushed or is holding a
3392        // page whose contents are already on flash, so this holds — but it is
3393        // the invariant the footer's correctness rests on, so state it.
3394        debug_assert_eq!(
3395            self.page_buf_offset, self.page_buf_durable,
3396            "a sector is sealed only with a page buffer that flash already has"
3397        );
3398
3399        let footer = SectorFooter::new(&self.sectors[sector_idx as usize]);
3400        let mut page = [0xFFu8; PAGE_SIZE];
3401        page[..SECTOR_FOOTER_SIZE].copy_from_slice(footer.as_bytes());
3402        flash.write(self.sector_offset(sector_idx) + self.footer_offset(), &page)?;
3403        Ok(())
3404    }
3405
3406    /// What must happen before an entry of `entry_size` bytes can be staged.
3407    ///
3408    /// The sector-room test comes first and subsumes the old separate
3409    /// "cursor sat on the data boundary" pre-check: a page never straddles the
3410    /// footer, so whenever an entry fits the *current page* the sector has at
3411    /// least `PAGE_SIZE` left, and the only way `sector_remaining` can fall
3412    /// short is the cursor having already passed the boundary — which is
3413    /// precisely the case that pre-check existed for.
3414    pub(crate) fn plan_append(&self, entry_size: usize) -> Result<AppendStep, Error> {
3415        let active = self.active_sector.ok_or(Error::NoSpace)?;
3416
3417        // Against the footer offset, not the sector size: the last page is
3418        // reserved for the summary written at seal time.
3419        let used = self.page_flash_offset - self.sector_offset(active);
3420        let sector_remaining = self.footer_offset().saturating_sub(used) as usize;
3421
3422        if sector_remaining < entry_size || sector_remaining < ENTRY_OVERHEAD {
3423            return Ok(AppendStep::Seal);
3424        }
3425
3426        if entry_size > PAGE_SIZE - self.page_buf_offset {
3427            return Ok(AppendStep::FlushPage);
3428        }
3429
3430        Ok(AppendStep::Stage)
3431    }
3432
3433    /// Write the entry into the page buffer and record it in the sector index.
3434    ///
3435    /// Pure, and only correct once [`plan_append`](Self::plan_append) has
3436    /// answered [`Stage`](AppendStep::Stage).
3437    ///
3438    /// The payload arrives in two pieces so a run costs no staging buffer — the
3439    /// frame header and the sample bytes go straight into the page buffer, which
3440    /// is also where the entry CRC is then computed from.
3441    #[allow(clippy::too_many_arguments)]
3442    pub(crate) fn stage_entry(
3443        &mut self,
3444        kind: EntryKind,
3445        sensor_id: u16,
3446        timestamp: u64,
3447        span_end: u64,
3448        samples: u32,
3449        head: &[u8],
3450        tail: &[u8],
3451    ) -> Result<(), Error> {
3452        let payload_len = head.len() + tail.len();
3453        let entry_size = ENTRY_OVERHEAD + payload_len;
3454
3455        let header = match kind {
3456            EntryKind::Single => EntryHeaderWire::new(sensor_id, timestamp, payload_len as u16),
3457            EntryKind::Run => EntryHeaderWire::new_run(sensor_id, timestamp, payload_len as u16),
3458        };
3459
3460        // Compute offset_in_sector for CRC: where this entry sits within its sector
3461        let active_idx = self.active_sector.ok_or(Error::NoSpace)?;
3462        let sector_offset = self.sector_offset(active_idx);
3463        let offset_in_sector =
3464            (self.page_flash_offset - sector_offset) + self.page_buf_offset as u32;
3465
3466        // The payload is assembled in the page buffer first, so the CRC is
3467        // computed over one contiguous slice however many pieces it arrived in.
3468        let offset = self.page_buf_offset;
3469        let body = offset + ENTRY_HEADER_SIZE;
3470        self.page_buf[offset..body].copy_from_slice(header.as_bytes());
3471        self.page_buf[body..body + head.len()].copy_from_slice(head);
3472        self.page_buf[body + head.len()..body + payload_len].copy_from_slice(tail);
3473
3474        let crc = compute_entry_crc(
3475            &header,
3476            &self.page_buf[body..body + payload_len],
3477            offset_in_sector,
3478        );
3479        self.page_buf[body + payload_len..offset + entry_size].copy_from_slice(&crc.to_le_bytes());
3480
3481        self.page_buf_offset += entry_size;
3482
3483        // Update sector summary
3484        let summary = &mut self.sectors[active_idx as usize];
3485        summary.entry_count += 1;
3486        summary.sample_count += samples;
3487        summary.write_offset += entry_size as u32;
3488        summary.record_span(timestamp, span_end);
3489        summary.record_sensor(sensor_id);
3490        self.total_entries += 1;
3491        self.total_samples += samples;
3492
3493        Ok(())
3494    }
3495
3496    /// Where the page buffer must be written, or `None` if there is nothing to
3497    /// flush.
3498    ///
3499    /// The three `commit_*`/`*_page` helpers exist so both drivers can express
3500    /// the two-phase commit as *write, mark, write, advance* without either of
3501    /// them restating what marking or advancing means.
3502    pub(crate) fn commit_target(&self) -> Option<u32> {
3503        (self.page_buf_offset > 0).then_some(self.page_flash_offset)
3504    }
3505
3506    /// Flip the buffered entries' flags to committed, in RAM.
3507    ///
3508    /// Phase 2 of the two-phase commit: the caller re-writes the same page
3509    /// afterwards, which only clears bits (1→0) and so needs no erase.
3510    ///
3511    /// Note this makes the buffer claim a durability flash does not yet have —
3512    /// which is exactly why `page_buf_durable`, and not the flags byte, is what
3513    /// [`drain_unflushed`](Self::drain_unflushed) trusts.
3514    pub(crate) fn mark_page_committed(&mut self) {
3515        let scan_start =
3516            if self.page_flash_offset == self.sector_offset(self.active_sector.unwrap_or(0)) {
3517                // First page of sector: entries start after the sector header
3518                SECTOR_HEADER_SIZE
3519            } else {
3520                0
3521            };
3522
3523        let mut pos = scan_start;
3524        while pos + ENTRY_HEADER_SIZE <= self.page_buf_offset {
3525            if is_entry_marker(self.page_buf[pos]) {
3526                // Set flags byte to COMMITTED (0x00)
3527                self.page_buf[pos + 1] = FLAGS_COMMITTED;
3528
3529                // Skip past this entry
3530                let payload_len =
3531                    u16::from_le_bytes([self.page_buf[pos + 12], self.page_buf[pos + 13]]) as usize;
3532                let entry_size = ENTRY_OVERHEAD + payload_len;
3533                pos += entry_size;
3534            } else {
3535                break;
3536            }
3537        }
3538    }
3539
3540    /// Move past the page just made durable and empty the buffer.
3541    pub(crate) fn advance_page(&mut self) {
3542        self.page_flash_offset += PAGE_SIZE as u32;
3543        self.page_buf.fill(0xFF);
3544        self.page_buf_offset = 0;
3545        self.page_buf_durable = 0;
3546
3547        // Update the sector's write_offset to reflect the new page boundary
3548        // so that subsequent appends and reads see the correct position
3549        if let Some(active_idx) = self.active_sector {
3550            let sector_offset = self.sector_offset(active_idx);
3551            self.sectors[active_idx as usize].write_offset = self.page_flash_offset - sector_offset;
3552        }
3553    }
3554
3555    fn flush_page<F: NorFlash>(&mut self, flash: &mut F) -> Result<(), Error> {
3556        let Some(addr) = self.commit_target() else {
3557            return Ok(());
3558        };
3559        // Phase 1: the entries still carry flags=0xFF (uncommitted).
3560        flash.write(addr, &self.page_buf)?;
3561        // Phase 2: mark, then re-write the same page.
3562        self.mark_page_committed();
3563        flash.write(addr, &self.page_buf)?;
3564        self.advance_page();
3565        Ok(())
3566    }
3567
3568    /// Sector-index statistics.
3569    ///
3570    /// Pure — both drivers forward to this rather than each walking the sector
3571    /// array themselves, which they used to do in 30 identical lines apiece.
3572    pub(crate) fn stats(&self) -> DbStats {
3573        let mut used = 0u16;
3574        let mut free = 0u16;
3575        let mut min_erase = u32::MAX;
3576        let mut max_erase = 0u32;
3577        let mut total_erase = 0u64;
3578
3579        for i in 0..self.sector_count as usize {
3580            let ec = self.sectors[i].erase_count;
3581            if ec < min_erase {
3582                min_erase = ec;
3583            }
3584            if ec > max_erase {
3585                max_erase = ec;
3586            }
3587            total_erase += ec as u64;
3588            match self.sectors[i].state {
3589                SectorState::Erased => free += 1,
3590                SectorState::Active | SectorState::Sealed => used += 1,
3591            }
3592        }
3593
3594        if self.sector_count == 0 {
3595            min_erase = 0;
3596        }
3597
3598        DbStats {
3599            total_entries: self.total_entries,
3600            total_samples: self.total_samples,
3601            used_sectors: used,
3602            free_sectors: free,
3603            reserved_sectors: self.reserved_sectors,
3604            min_erase_count: min_erase,
3605            max_erase_count: max_erase,
3606            total_erase_count: total_erase,
3607        }
3608    }
3609
3610    /// Whether this mount mode wants a footer read for this sector.
3611    ///
3612    /// The newest sector's footer is read in **every** mode: there it is not an
3613    /// optimisation but the signal that the sector is already sealed, and
3614    /// appending into it would make its frozen summary a lie.
3615    pub(crate) fn wants_footer(&self, mode: MountMode, is_newest: bool) -> bool {
3616        mode == MountMode::Full || is_newest
3617    }
3618
3619    /// Index a sector from its footer.
3620    pub(crate) fn adopt_footer(&mut self, i: u16, footer: &SectorFooter, stats: &mut MountStats) {
3621        footer.apply_to(&mut self.sectors[i as usize]);
3622        stats.total_entries += footer.entry_count.get();
3623        stats.total_samples += footer.sample_count.get();
3624    }
3625
3626    /// Index a sector from a body scan.
3627    pub(crate) fn adopt_scan(
3628        &mut self,
3629        i: u16,
3630        scanned: &ScannedSector,
3631        corrupt: u32,
3632        stats: &mut MountStats,
3633    ) {
3634        scanned.apply_to(&mut self.sectors[i as usize]);
3635        stats.total_entries += scanned.entries;
3636        stats.total_samples += scanned.samples;
3637        stats.corrupt_entries += corrupt;
3638        stats.scanned_sectors += 1;
3639    }
3640
3641    /// Record a sector known to exist and be sealed, but not indexed.
3642    ///
3643    /// `HeadersOnly` with no footer. `write_offset` covers the whole data region
3644    /// so a later `read_from` still streams it end to end, and the bounds are
3645    /// set wide open so nothing prunes it.
3646    pub(crate) fn adopt_unindexed(&mut self, i: u16) {
3647        let data_limit = self.footer_offset();
3648        let summary = &mut self.sectors[i as usize];
3649        summary.entry_count = 0;
3650        summary.sample_count = 0;
3651        summary.write_offset = data_limit;
3652        summary.min_timestamp = 0;
3653        summary.max_timestamp = u64::MAX;
3654        summary.sensor_bloom = u64::MAX;
3655    }
3656
3657    /// Adopt the totals a mount established, before the active sector is chosen.
3658    pub(crate) fn finish_mount(
3659        &mut self,
3660        mode: MountMode,
3661        max_sequence: u32,
3662        max_epoch: u32,
3663        stats: &MountStats,
3664    ) {
3665        self.total_entries = stats.total_entries;
3666        self.total_samples = stats.total_samples;
3667        self.next_sequence = max_sequence + 1;
3668        self.epoch = max_epoch.saturating_add(1);
3669        self.mount_mode = mode;
3670        // The replica holds the replication watermark, not this log. Until it is
3671        // restored, everything reads as un-replicated — the safe direction.
3672        self.spool_watermark = LogPosition::BEGINNING;
3673        self.spooled_entries = 0;
3674        self.spooled_samples = 0;
3675        self.dropped_unspooled = 0;
3676    }
3677
3678    /// The sector a seal is about to close.
3679    pub(crate) fn sealing(&self) -> Result<u16, Error> {
3680        self.active_sector.ok_or(Error::NoSpace)
3681    }
3682
3683    /// Seal the active sector and choose its successor.
3684    ///
3685    /// **Order is load-bearing.** Marking `old_active` sealed has to happen
3686    /// before [`find_next_sector`](Self::find_next_sector), which counts sealed
3687    /// sectors against `reserved_sectors` and may pick this very one as the
3688    /// victim. Call this only *after* the footer write, which is where the
3689    /// blocking driver had it.
3690    pub(crate) fn begin_seal(&mut self, old_active: u16) -> Result<SealPlan, Error> {
3691        // Seal current sector
3692        self.sectors[old_active as usize].state = SectorState::Sealed;
3693
3694        // Find next sector: prefer erased, otherwise erase oldest sealed
3695        let new_active = self.find_next_sector()?;
3696
3697        // Snapshot the victim before anything touches it: if it was sealed, its
3698        // entries are about to be destroyed and must be accounted for.
3699        let victim = self.sectors[new_active as usize];
3700
3701        // Increment erase count from the target sector (preserving wear history)
3702        let erase_count = victim.erase_count.saturating_add(1);
3703
3704        Ok(SealPlan {
3705            new_active,
3706            erase_count,
3707            victim,
3708        })
3709    }
3710
3711    /// Charge the ring for what the erase just destroyed.
3712    ///
3713    /// Must follow a **successful** erase. Doing it earlier would leave the
3714    /// index claiming a loss that never happened if `erase` failed.
3715    pub(crate) fn account_seal(&mut self, plan: &SealPlan) {
3716        if plan.victim.state == SectorState::Sealed {
3717            self.account_eviction(&plan.victim);
3718        }
3719    }
3720
3721    /// Adopt the freshly initialised sector, after its header has been written.
3722    pub(crate) fn finish_seal(&mut self, plan: &SealPlan) {
3723        // That header carries the current epoch, so any debt from `mount` is paid.
3724        self.epoch_pending = false;
3725
3726        self.sectors[plan.new_active as usize] = SectorSummary {
3727            state: SectorState::Active,
3728            sequence: self.next_sequence,
3729            entry_count: 0,
3730            sample_count: 0,
3731            write_offset: SECTOR_HEADER_SIZE as u32,
3732            min_timestamp: u64::MAX,
3733            max_timestamp: 0,
3734            sensor_bloom: 0,
3735            erase_count: plan.erase_count,
3736        };
3737
3738        self.active_sector = Some(plan.new_active);
3739        self.next_sequence += 1;
3740
3741        // Reset page buffer
3742        let sector_offset = self.sector_offset(plan.new_active);
3743        self.page_flash_offset = sector_offset;
3744        self.page_buf.fill(0xFF);
3745        let header = self.sector_header(
3746            self.sectors[plan.new_active as usize].sequence,
3747            plan.erase_count,
3748        );
3749        self.page_buf[..SECTOR_HEADER_SIZE].copy_from_slice(header.as_bytes());
3750        self.page_buf_offset = SECTOR_HEADER_SIZE;
3751        self.page_buf_durable = SECTOR_HEADER_SIZE;
3752    }
3753
3754    fn seal_and_advance<F: NorFlash>(&mut self, flash: &mut F) -> Result<(), Error> {
3755        let old_active = self.sealing()?;
3756
3757        // The sector's contents are final, so record its summary in the
3758        // reserved final page: that is what lets the next mount index it with a
3759        // single page read instead of a body scan.
3760        //
3761        // A failure here is deliberately not propagated. The footer is an
3762        // optimisation and must never make the log less usable than it would be
3763        // without one — and the failure that matters is exactly the persistent
3764        // kind. A footer page left dirty by an earlier torn write answers
3765        // `NotErased` forever, which would wedge every subsequent append for the
3766        // sake of metadata a body scan reconstructs anyway. Flash that is
3767        // genuinely broken still reports it: the erase and header write below
3768        // are on the same device and are not forgiving.
3769        let _ = self.write_sector_footer(flash, old_active);
3770
3771        let plan = self.begin_seal(old_active)?;
3772        self.erase_sector(flash, plan.new_active)?;
3773        self.account_seal(&plan);
3774        self.init_sector(flash, plan.new_active, self.next_sequence, plan.erase_count)?;
3775        self.finish_seal(&plan);
3776
3777        Ok(())
3778    }
3779
3780    fn scan_sector_entries<F: ReadNorFlash>(
3781        &mut self,
3782        flash: &mut F,
3783        sector_idx: u16,
3784    ) -> Result<(ScannedSector, u32), Error> {
3785        let sector_offset = self.sector_offset(sector_idx);
3786        let entry_start = SECTOR_HEADER_SIZE as u32;
3787        // Bounded by the footer offset, not the sector size: the final page
3788        // holds a summary, not entries.
3789        let mut scanner = SectorScanner::new(sector_offset, entry_start, self.footer_offset());
3790        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3791        let mut buf = [0u8; PAGE_SIZE];
3792
3793        let mut found = ScannedSector {
3794            write_offset: entry_start,
3795            ..ScannedSector::EMPTY
3796        };
3797
3798        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3799            if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
3800                scanner.corrupt_count += 1;
3801                scanner.skip(1);
3802                continue;
3803            }
3804
3805            found.record(&entry, &buf[..entry.payload_len]);
3806
3807            scanner.skip(entry.entry_size);
3808            found.write_offset = scanner.offset();
3809        }
3810
3811        Ok((found, scanner.corrupt_count()))
3812    }
3813
3814    fn find_latest_in_sector<F: ReadNorFlash>(
3815        &self,
3816        flash: &mut F,
3817        sector_idx: u16,
3818        target_sensor: u16,
3819        buf: &mut [u8],
3820    ) -> Result<Option<(EntryHeader, usize)>, Error> {
3821        let sector_offset = self.sector_offset(sector_idx);
3822        let write_offset = self.sectors[sector_idx as usize].write_offset;
3823        let entry_start = SECTOR_HEADER_SIZE as u32;
3824        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3825        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3826        let mut payload_buf = [0u8; PAGE_SIZE];
3827
3828        let mut latest: Option<(EntryHeader, usize)> = None;
3829        let mut latest_ts = 0u64;
3830
3831        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3832            if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
3833                scanner.skip(1);
3834                continue;
3835            }
3836
3837            if entry.sensor_id() == target_sensor {
3838                let (header, payload) =
3839                    entry.edge(&mut payload_buf[..entry.payload_len], Edge::Last);
3840
3841                if header.timestamp >= latest_ts {
3842                    let len = payload.len();
3843                    if len > buf.len() {
3844                        return Err(Error::BufferTooSmall);
3845                    }
3846                    buf[..len].copy_from_slice(payload);
3847                    latest_ts = header.timestamp;
3848                    latest = Some((header, len));
3849                }
3850            }
3851
3852            scanner.skip(entry.entry_size);
3853        }
3854
3855        Ok(latest)
3856    }
3857
3858    #[allow(clippy::too_many_arguments)]
3859    fn scan_sector_for_query<F: ReadNorFlash, C>(
3860        &self,
3861        flash: &mut F,
3862        sector_idx: u16,
3863        sensor_filter: Option<u16>,
3864        t_start: u64,
3865        t_end: u64,
3866        buf: &mut [u8],
3867        count: &mut u32,
3868        callback: &mut C,
3869    ) -> Result<bool, Error>
3870    where
3871        C: FnMut(&EntryHeader, &[u8]) -> bool,
3872    {
3873        let sector_offset = self.sector_offset(sector_idx);
3874        let write_offset = self.sectors[sector_idx as usize].write_offset;
3875        let entry_start = SECTOR_HEADER_SIZE as u32;
3876        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3877        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3878
3879        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3880            if !accept_entry(flash, sector_offset, &entry, buf)? {
3881                scanner.skip(1);
3882                continue;
3883            }
3884
3885            let sensor = entry.sensor_id();
3886            let base = entry.timestamp();
3887
3888            if sensor_filter.is_none_or(|f| f == sensor)
3889                && deliver_samples(
3890                    entry.is_run(),
3891                    sensor,
3892                    base,
3893                    &mut buf[..entry.payload_len],
3894                    t_start,
3895                    t_end,
3896                    count,
3897                    callback,
3898                )
3899            {
3900                return Ok(true); // stopped early
3901            }
3902
3903            scanner.skip(entry.entry_size);
3904        }
3905
3906        Ok(false)
3907    }
3908
3909    fn find_oldest_in_sector<F: ReadNorFlash>(
3910        &self,
3911        flash: &mut F,
3912        sector_idx: u16,
3913        target_sensor: u16,
3914        buf: &mut [u8],
3915    ) -> Result<Option<(EntryHeader, usize)>, Error> {
3916        let sector_offset = self.sector_offset(sector_idx);
3917        let write_offset = self.sectors[sector_idx as usize].write_offset;
3918        let entry_start = SECTOR_HEADER_SIZE as u32;
3919        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
3920        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3921        let mut payload_buf = [0u8; PAGE_SIZE];
3922
3923        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3924            if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
3925                scanner.skip(1);
3926                continue;
3927            }
3928
3929            let sensor = entry.sensor_id();
3930
3931            if sensor == target_sensor {
3932                let (header, payload) =
3933                    entry.edge(&mut payload_buf[..entry.payload_len], Edge::First);
3934
3935                if payload.len() > buf.len() {
3936                    return Err(Error::BufferTooSmall);
3937                }
3938                buf[..payload.len()].copy_from_slice(payload);
3939                return Ok(Some((header, payload.len())));
3940            }
3941
3942            scanner.skip(entry.entry_size);
3943        }
3944
3945        Ok(None)
3946    }
3947
3948    /// Count the entries in `sector_idx` that start below `offset_limit`.
3949    ///
3950    /// Uses the same acceptance test as the mount scan — committed flags and a
3951    /// matching CRC — so the result is always a subset of the sector's
3952    /// `entry_count`, and the accounting it feeds stays comparable with the one
3953    /// `note_spooled` builds incrementally.
3954    ///
3955    /// An entry that straddles `offset_limit` is not counted: the scanner stops
3956    /// when the next entry would cross its limit. Watermarks land on entry
3957    /// boundaries, so that case does not arise from a well-formed position.
3958    pub(crate) fn count_entries_before<F: ReadNorFlash>(
3959        &self,
3960        flash: &mut F,
3961        sector_idx: u16,
3962        offset_limit: u32,
3963    ) -> Result<Replicated, Error> {
3964        let summary = &self.sectors[sector_idx as usize];
3965        let sector_offset = self.sector_offset(sector_idx);
3966        let entry_start = SECTOR_HEADER_SIZE as u32;
3967        let limit = offset_limit.min(summary.write_offset);
3968        if limit <= entry_start {
3969            return Ok(Replicated::NONE);
3970        }
3971
3972        let mut scanner = SectorScanner::new(sector_offset, entry_start, limit);
3973        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
3974        let mut buf = [0u8; PAGE_SIZE];
3975        let mut found = Replicated::NONE;
3976
3977        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
3978            if !accept_entry(flash, sector_offset, &entry, &mut buf)? {
3979                scanner.skip(1);
3980                continue;
3981            }
3982            found.push(samples_in(entry.is_run(), &buf[..entry.payload_len]));
3983            scanner.skip(entry.entry_size);
3984        }
3985
3986        // A prefix cannot hold more than the whole. The clamp matters for a
3987        // `HeadersOnly` mount, where an unscanned sector reports `entry_count = 0`
3988        // and contributes nothing to `total_entries`.
3989        Ok(Replicated {
3990            entries: found.entries.min(summary.entry_count),
3991            samples: found.samples.min(summary.sample_count),
3992        })
3993    }
3994
3995    /// Count the entries in `sector_idx` belonging to `target_sensor`.
3996    ///
3997    /// Uses the same acceptance test as [`scan_sector_for_query`] — a matching
3998    /// entry CRC, and a one-byte resync on failure — because `count` and
3999    /// `query_range` disagreeing about how many entries exist is a defect, not
4000    /// an optimisation. This costs a payload read per entry, and it is the same
4001    /// read `query_range` performs, paid only on sectors the bloom filter did
4002    /// not reject.
4003    ///
4004    /// [`scan_sector_for_query`]: Self::scan_sector_for_query
4005    fn count_sensor_in_sector<F: ReadNorFlash>(
4006        &self,
4007        flash: &mut F,
4008        sector_idx: u16,
4009        target_sensor: u16,
4010    ) -> Result<u32, Error> {
4011        let sector_offset = self.sector_offset(sector_idx);
4012        let write_offset = self.sectors[sector_idx as usize].write_offset;
4013        let entry_start = SECTOR_HEADER_SIZE as u32;
4014        let mut scanner = SectorScanner::new(sector_offset, entry_start, write_offset);
4015        let mut header_buf = [0u8; ENTRY_HEADER_SIZE];
4016        let mut payload_buf = [0u8; PAGE_SIZE];
4017        let mut count = 0u32;
4018
4019        while let Some(entry) = scanner.next_entry(flash, &mut header_buf, PAGE_SIZE)? {
4020            // Every entry is verified, not only the matching ones: a failure
4021            // resyncs by one byte, so skipping the check for a non-matching
4022            // sensor would walk the sector differently from the read path and
4023            // reintroduce the disagreement from the other side.
4024            if !accept_entry(flash, sector_offset, &entry, &mut payload_buf)? {
4025                scanner.skip(1);
4026                continue;
4027            }
4028            if entry.sensor_id() == target_sensor {
4029                // Samples, not entries: a run answers for all of its own, which
4030                // is what `query_range` would yield for it.
4031                count += samples_in(entry.is_run(), &payload_buf[..entry.payload_len]);
4032            }
4033            scanner.skip(entry.entry_size);
4034        }
4035
4036        Ok(count)
4037    }
4038}
4039
4040// ---------------------------------------------------------------------------
4041// Capability ports
4042// ---------------------------------------------------------------------------
4043//
4044// Delegation only, spelled with UFCS. Written as `self.append(..)` these would
4045// be ambiguous to read — the inherent method and the trait method share a name
4046// — and a future signature change on the inherent one would silently turn the
4047// call into unbounded recursion.
4048
4049impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSink
4050    for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
4051where
4052    F: NorFlash + ReadNorFlash,
4053{
4054    fn append(&mut self, sensor_id: u16, timestamp: u64, payload: &[u8]) -> Result<(), Error> {
4055        SensorDb::append(self, sensor_id, timestamp, payload)
4056    }
4057
4058    fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
4059        SensorDb::append_run(self, run)
4060    }
4061
4062    fn sync(&mut self) -> Result<(), Error> {
4063        SensorDb::sync(self)
4064    }
4065}
4066
4067impl<F, const PAGE_SIZE: usize, const MAX_SECTORS: usize> crate::port::LogSource
4068    for SensorDb<F, PAGE_SIZE, MAX_SECTORS>
4069where
4070    F: NorFlash + ReadNorFlash,
4071{
4072    fn latest(
4073        &mut self,
4074        sensor_id: u16,
4075        buf: &mut [u8],
4076    ) -> Result<Option<(EntryHeader, usize)>, Error> {
4077        SensorDb::latest(self, sensor_id, buf)
4078    }
4079
4080    fn oldest(
4081        &mut self,
4082        sensor_id: u16,
4083        buf: &mut [u8],
4084    ) -> Result<Option<(EntryHeader, usize)>, Error> {
4085        SensorDb::oldest(self, sensor_id, buf)
4086    }
4087
4088    fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
4089        SensorDb::count(self, sensor_id)
4090    }
4091
4092    fn query_range(
4093        &mut self,
4094        sensor_id: Option<u16>,
4095        t_start: u64,
4096        t_end: u64,
4097        callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool,
4098    ) -> Result<u32, Error> {
4099        SensorDb::query_range(self, sensor_id, t_start, t_end, callback)
4100    }
4101}
4102
4103#[cfg(all(test, feature = "std"))]
4104mod tests {
4105    extern crate alloc;
4106    use alloc::vec;
4107
4108    use super::*;
4109    use crate::mock::MockFlash;
4110
4111    const PAGE: usize = 256;
4112    const SECTOR: usize = 4096;
4113    const SECTORS: usize = 8;
4114
4115    fn make_db() -> SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS> {
4116        let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4117        let mut db = SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4118        db.format().unwrap();
4119        db
4120    }
4121
4122    #[test]
4123    fn format_and_mount() {
4124        let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4125        let mut db: SensorDb<_, PAGE, SECTORS> =
4126            SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4127        db.format().unwrap();
4128        assert!(db.is_mounted());
4129        assert_eq!(db.stats().total_entries, 0);
4130    }
4131
4132    #[test]
4133    fn append_and_latest() {
4134        let mut db = make_db();
4135        let payload = [0xDE, 0xAD, 0xBE, 0xEF];
4136        db.append(1, 1000, &payload).unwrap();
4137        db.append(2, 1001, &[0x42]).unwrap();
4138        db.append(1, 1002, &[0x01, 0x02]).unwrap();
4139
4140        // Latest for sensor 1 should be the third entry
4141        let mut buf = [0u8; 16];
4142        let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4143        assert_eq!(hdr.sensor_id, 1);
4144        assert_eq!(hdr.timestamp, 1002);
4145        assert_eq!(&buf[..n], &[0x01, 0x02]);
4146
4147        // Latest for sensor 2
4148        let (hdr2, n2) = db.latest(2, &mut buf).unwrap().unwrap();
4149        assert_eq!(hdr2.sensor_id, 2);
4150        assert_eq!(&buf[..n2], &[0x42]);
4151    }
4152
4153    #[test]
4154    fn query_range_filters_correctly() {
4155        let mut db = make_db();
4156        db.append(1, 100, &[0x01]).unwrap();
4157        db.append(1, 200, &[0x02]).unwrap();
4158        db.append(2, 150, &[0x0A]).unwrap();
4159        db.append(1, 300, &[0x03]).unwrap();
4160        db.sync().unwrap();
4161
4162        // Query sensor 1, time range 100..250
4163        let mut results = alloc::vec::Vec::new();
4164        let count = db
4165            .query_range(Some(1), 100, 250, |hdr, payload| {
4166                results.push((hdr.timestamp, payload[0]));
4167                true
4168            })
4169            .unwrap();
4170
4171        assert_eq!(count, 2);
4172        assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4173    }
4174
4175    #[test]
4176    fn survives_remount() {
4177        let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4178        let mut db: SensorDb<_, PAGE, SECTORS> =
4179            SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4180        db.format().unwrap();
4181
4182        db.append(5, 42, &[0xAA, 0xBB]).unwrap();
4183        db.append(5, 43, &[0xCC]).unwrap();
4184        db.sync().unwrap();
4185
4186        let _stats_before = db.stats();
4187
4188        // Simulate power cycle: extract flash, create new DB, mount
4189        let flash = db.into_inner();
4190        let mut db2: SensorDb<_, PAGE, SECTORS> =
4191            SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4192        let mount_stats = db2.mount().unwrap();
4193
4194        assert_eq!(mount_stats.total_entries, 2);
4195
4196        // Verify data survived
4197        let mut buf = [0u8; 16];
4198        let (hdr, n) = db2.latest(5, &mut buf).unwrap().unwrap();
4199        assert_eq!(hdr.timestamp, 43);
4200        assert_eq!(&buf[..n], &[0xCC]);
4201    }
4202
4203    #[test]
4204    fn circular_wrap_reclaims_old_sectors() {
4205        // Use only 4 sectors to force wrapping quickly
4206        const SMALL: usize = 4;
4207        let flash = MockFlash::<PAGE, SECTOR>::new(SMALL * SECTOR);
4208        let mut db: SensorDb<_, PAGE, SMALL> = SensorDb::new(flash, 0, SMALL as u16, 1).unwrap();
4209        db.format().unwrap();
4210
4211        // Fill enough entries to wrap around. Each entry is ~20 bytes.
4212        // Each 4KB sector fits roughly (4096 - 8) / 20 ≈ 204 entries per page,
4213        // but entries can't span pages so per page (256 - 8 first page) / 20 ≈ 12 entries.
4214        // With 16 pages per sector, ~192 entries per sector × 4 sectors = ~768 entries.
4215        // But we have 1 reserved sector so usable = 3 sectors ≈ 576 entries.
4216        for i in 0..800u64 {
4217            let payload = (i as u32).to_le_bytes();
4218            db.append(1, i * 100, &payload).unwrap();
4219        }
4220
4221        let stats = db.stats();
4222        assert!(stats.total_entries > 0);
4223        assert!(stats.used_sectors <= SMALL as u16);
4224
4225        // Most recent entry should still be queryable
4226        let mut buf = [0u8; 4];
4227        let (hdr, _) = db.latest(1, &mut buf).unwrap().unwrap();
4228        assert_eq!(hdr.timestamp, 799 * 100);
4229    }
4230
4231    #[test]
4232    fn compact_frees_sectors() {
4233        let mut db = make_db();
4234        for i in 0..50u64 {
4235            db.append(1, i, &[i as u8]).unwrap();
4236        }
4237        db.sync().unwrap();
4238
4239        let before = db.stats();
4240        let freed = db.compact(1, CompactScope::All).unwrap();
4241        let after = db.stats();
4242
4243        if before.used_sectors > 1 {
4244            assert!(freed > 0);
4245            assert!(after.free_sectors > before.free_sectors);
4246        }
4247    }
4248
4249    #[test]
4250    fn max_payload_works() {
4251        let mut db = make_db();
4252        let max = db.max_payload_size();
4253        let payload = vec![0x42u8; max];
4254        db.append(1, 999, &payload).unwrap();
4255        db.sync().unwrap();
4256
4257        let mut buf = vec![0u8; max];
4258        let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4259        assert_eq!(n, max);
4260        assert_eq!(hdr.payload_len as usize, max);
4261    }
4262
4263    #[test]
4264    fn rejects_oversized_payload() {
4265        let mut db = make_db();
4266        let too_big = vec![0u8; db.max_payload_size() + 1];
4267        let result = db.append(1, 100, &too_big);
4268        assert!(result.is_err());
4269    }
4270
4271    // =========================================================================
4272    // Typed API Tests
4273    // =========================================================================
4274
4275    mod typed_api {
4276        use super::*;
4277        use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
4278
4279        /// Example sensor type for testing: temperature reading
4280        #[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
4281        #[repr(C)]
4282        struct Temperature {
4283            celsius: f32,
4284        }
4285
4286        impl SensorData for Temperature {
4287            const SENSOR_ID: u16 = 0x01;
4288        }
4289
4290        /// Example sensor type: accelerometer reading
4291        #[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
4292        #[repr(C)]
4293        struct Accelerometer {
4294            x: i16,
4295            y: i16,
4296            z: i16,
4297        }
4298
4299        impl SensorData for Accelerometer {
4300            const SENSOR_ID: u16 = 0x02;
4301        }
4302
4303        #[test]
4304        fn typed_roundtrip_layer1() {
4305            let mut db = make_db();
4306
4307            let temp = Temperature { celsius: 25.5 };
4308            db.append_value(0x01, 1000, &temp).unwrap();
4309
4310            let (hdr, retrieved) = db.latest_value::<Temperature>(0x01).unwrap().unwrap();
4311            assert_eq!(hdr.sensor_id, 0x01);
4312            assert_eq!(hdr.timestamp, 1000);
4313            assert_eq!(retrieved.celsius, 25.5);
4314        }
4315
4316        #[test]
4317        fn typed_roundtrip_layer2() {
4318            let mut db = make_db();
4319
4320            let temp = Temperature { celsius: -10.0 };
4321            db.append_sensor(2000, &temp).unwrap();
4322
4323            let (hdr, retrieved) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4324            assert_eq!(hdr.sensor_id, Temperature::SENSOR_ID);
4325            assert_eq!(hdr.timestamp, 2000);
4326            assert_eq!(retrieved.celsius, -10.0);
4327        }
4328
4329        #[test]
4330        fn typed_multiple_sensors() {
4331            let mut db = make_db();
4332
4333            let temp = Temperature { celsius: 22.5 };
4334            let accel = Accelerometer {
4335                x: 100,
4336                y: -50,
4337                z: 980,
4338            };
4339
4340            db.append_sensor(1000, &temp).unwrap();
4341            db.append_sensor(1001, &accel).unwrap();
4342
4343            // Retrieve each type independently
4344            let (_, t) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4345            let (_, a) = db.latest_sensor::<Accelerometer>().unwrap().unwrap();
4346
4347            assert_eq!(t.celsius, 22.5);
4348            assert_eq!(a.x, 100);
4349            assert_eq!(a.y, -50);
4350            assert_eq!(a.z, 980);
4351        }
4352
4353        #[test]
4354        fn cross_api_raw_write_typed_read() {
4355            let mut db = make_db();
4356
4357            // A bare value written raw is *not* a Temperature: the typed API
4358            // frames a schema tag in front, so the untagged bytes are a byte
4359            // short of what it expects.
4360            db.append(Temperature::SENSOR_ID, 3000, &30.0f32.to_ne_bytes())
4361                .unwrap();
4362            assert_eq!(
4363                db.latest_sensor::<Temperature>(),
4364                Err(Error::SizeMismatch {
4365                    expected: 5,
4366                    actual: 4
4367                })
4368            );
4369
4370            // Include the tag and the raw route reaches the typed one.
4371            let mut framed = [0u8; 5];
4372            framed[0] = Temperature::SCHEMA_VERSION;
4373            framed[1..].copy_from_slice(&31.0f32.to_ne_bytes());
4374            db.append(Temperature::SENSOR_ID, 3100, &framed).unwrap();
4375
4376            let (hdr, temp) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4377            assert_eq!(hdr.timestamp, 3100);
4378            assert_eq!(temp.celsius, 31.0);
4379        }
4380
4381        #[test]
4382        fn cross_api_typed_write_raw_read() {
4383            let mut db = make_db();
4384
4385            // Write using typed API
4386            let temp = Temperature { celsius: 42.0 };
4387            db.append_sensor(4000, &temp).unwrap();
4388
4389            // Read using raw API: the schema tag is the first payload byte, so
4390            // the entry is one longer than the value.
4391            let mut buf = [0u8; 16];
4392            let (hdr, n) = db
4393                .latest(Temperature::SENSOR_ID, &mut buf)
4394                .unwrap()
4395                .unwrap();
4396            assert_eq!(hdr.timestamp, 4000);
4397            assert_eq!(n, crate::SCHEMA_TAG_SIZE + 4);
4398            assert_eq!(hdr.payload_len as usize, n);
4399            assert_eq!(buf[0], Temperature::SCHEMA_VERSION);
4400            let celsius = f32::from_ne_bytes([buf[1], buf[2], buf[3], buf[4]]);
4401            assert_eq!(celsius, 42.0);
4402        }
4403
4404        #[test]
4405        fn size_mismatch_detection() {
4406            let mut db = make_db();
4407
4408            // A lone tag byte: the right schema version, the wrong length. That
4409            // is what SizeMismatch now means — the struct changed and
4410            // SCHEMA_VERSION did not.
4411            db.append(Temperature::SENSOR_ID, 5000, &[Temperature::SCHEMA_VERSION])
4412                .unwrap();
4413
4414            let result = db.latest_sensor::<Temperature>();
4415            match result {
4416                Err(Error::SizeMismatch { expected, actual }) => {
4417                    assert_eq!(expected, 5);
4418                    assert_eq!(actual, 1);
4419                }
4420                _ => panic!("Expected SizeMismatch error"),
4421            }
4422        }
4423
4424        #[test]
4425        fn a_foreign_first_byte_is_reported_as_the_version_it_claims() {
4426            let mut db = make_db();
4427            db.append(Temperature::SENSOR_ID, 5000, &[0x42]).unwrap();
4428
4429            assert_eq!(
4430                db.latest_sensor::<Temperature>(),
4431                Err(Error::SchemaMismatch {
4432                    expected: 0,
4433                    found: 0x42
4434                })
4435            );
4436        }
4437
4438        #[test]
4439        fn an_entry_of_another_schema_version_is_named_not_misread() {
4440            // Same layout, different meaning — the case a length check cannot
4441            // catch, and the whole reason the tag exists.
4442            #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
4443            #[repr(C)]
4444            struct Fahrenheit {
4445                degrees: f32,
4446            }
4447
4448            impl SensorData for Fahrenheit {
4449                const SENSOR_ID: u16 = Temperature::SENSOR_ID;
4450                const SCHEMA_VERSION: u8 = 1;
4451            }
4452
4453            let mut db = make_db();
4454            db.append_sensor(1000, &Temperature { celsius: 100.0 })
4455                .unwrap();
4456
4457            assert_eq!(
4458                db.latest_sensor::<Fahrenheit>(),
4459                Err(Error::SchemaMismatch {
4460                    expected: 1,
4461                    found: 0
4462                })
4463            );
4464
4465            // Both eras live in one log under one sensor ID, and each type
4466            // queries its own.
4467            db.append_sensor(2000, &Fahrenheit { degrees: 212.0 })
4468                .unwrap();
4469
4470            let mut celsius = alloc::vec::Vec::new();
4471            db.query_all_sensor::<Temperature, _>(|_, t| {
4472                celsius.push(t.celsius);
4473                true
4474            })
4475            .unwrap();
4476
4477            let mut degrees = alloc::vec::Vec::new();
4478            db.query_all_sensor::<Fahrenheit, _>(|_, f| {
4479                degrees.push(f.degrees);
4480                true
4481            })
4482            .unwrap();
4483
4484            assert_eq!(celsius, [100.0]);
4485            assert_eq!(degrees, [212.0]);
4486
4487            // And the newest entry now is a Fahrenheit.
4488            let (_, f) = db.latest_sensor::<Fahrenheit>().unwrap().unwrap();
4489            assert_eq!(f.degrees, 212.0);
4490        }
4491
4492        #[test]
4493        fn query_sensor_typed() {
4494            let mut db = make_db();
4495
4496            // Write several temperature readings
4497            for i in 0..5 {
4498                let temp = Temperature {
4499                    celsius: 20.0 + i as f32,
4500                };
4501                db.append_sensor(100 + i * 10, &temp).unwrap();
4502            }
4503            db.sync().unwrap();
4504
4505            // Query a time range
4506            let mut readings = alloc::vec::Vec::new();
4507            let count = db
4508                .query_sensor::<Temperature, _>(110, 130, |hdr, temp| {
4509                    readings.push((hdr.timestamp, temp.celsius));
4510                    true
4511                })
4512                .unwrap();
4513
4514            assert_eq!(count, 3); // timestamps 110, 120, 130
4515            assert_eq!(readings.len(), 3);
4516            assert_eq!(readings[0], (110, 21.0));
4517            assert_eq!(readings[1], (120, 22.0));
4518            assert_eq!(readings[2], (130, 23.0));
4519        }
4520
4521        #[test]
4522        fn query_sensor_skips_wrong_size() {
4523            let mut db = make_db();
4524
4525            // Write a valid temperature
4526            let temp = Temperature { celsius: 25.0 };
4527            db.append_sensor(1000, &temp).unwrap();
4528
4529            // Write raw data with wrong size using Temperature's sensor ID
4530            db.append(Temperature::SENSOR_ID, 2000, &[0x01, 0x02])
4531                .unwrap();
4532
4533            // Write another valid temperature
4534            let temp2 = Temperature { celsius: 30.0 };
4535            db.append_sensor(3000, &temp2).unwrap();
4536
4537            db.sync().unwrap();
4538
4539            // Query should skip the malformed entry
4540            let mut readings = alloc::vec::Vec::new();
4541            let count = db
4542                .query_sensor::<Temperature, _>(0, 10000, |hdr, temp| {
4543                    readings.push((hdr.timestamp, temp.celsius));
4544                    true
4545                })
4546                .unwrap();
4547
4548            assert_eq!(count, 2);
4549            assert_eq!(readings[0], (1000, 25.0));
4550            assert_eq!(readings[1], (3000, 30.0));
4551        }
4552
4553        #[test]
4554        fn typed_survives_remount() {
4555            let flash = MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR);
4556            let mut db: SensorDb<_, PAGE, SECTORS> =
4557                SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4558            db.format().unwrap();
4559
4560            let temp = Temperature { celsius: 99.9 };
4561            db.append_sensor(6000, &temp).unwrap();
4562            db.sync().unwrap();
4563
4564            // Simulate power cycle
4565            let flash = db.into_inner();
4566            let mut db2: SensorDb<_, PAGE, SECTORS> =
4567                SensorDb::new(flash, 0, SECTORS as u16, 1).unwrap();
4568            db2.mount().unwrap();
4569
4570            // Verify typed data survived
4571            let (hdr, retrieved) = db2.latest_sensor::<Temperature>().unwrap().unwrap();
4572            assert_eq!(hdr.timestamp, 6000);
4573            assert_eq!(retrieved.celsius, 99.9);
4574        }
4575
4576        #[test]
4577        fn latest_returns_most_recent() {
4578            let mut db = make_db();
4579
4580            db.append_sensor(100, &Temperature { celsius: 10.0 })
4581                .unwrap();
4582            db.append_sensor(200, &Temperature { celsius: 20.0 })
4583                .unwrap();
4584            db.append_sensor(300, &Temperature { celsius: 30.0 })
4585                .unwrap();
4586
4587            let (hdr, temp) = db.latest_sensor::<Temperature>().unwrap().unwrap();
4588            assert_eq!(hdr.timestamp, 300);
4589            assert_eq!(temp.celsius, 30.0);
4590        }
4591
4592        #[test]
4593        fn no_entries_returns_none() {
4594            let mut db = make_db();
4595
4596            // No entries written
4597            let result = db.latest_sensor::<Temperature>().unwrap();
4598            assert!(result.is_none());
4599        }
4600
4601        #[test]
4602        fn oldest_returns_first_entry() {
4603            let mut db = make_db();
4604
4605            db.append_sensor(100, &Temperature { celsius: 10.0 })
4606                .unwrap();
4607            db.append_sensor(200, &Temperature { celsius: 20.0 })
4608                .unwrap();
4609            db.append_sensor(300, &Temperature { celsius: 30.0 })
4610                .unwrap();
4611
4612            let (hdr, temp) = db.oldest_sensor::<Temperature>().unwrap().unwrap();
4613            assert_eq!(hdr.timestamp, 100);
4614            assert_eq!(temp.celsius, 10.0);
4615        }
4616
4617        #[test]
4618        fn oldest_returns_none_when_empty() {
4619            let mut db = make_db();
4620
4621            let result = db.oldest_sensor::<Temperature>().unwrap();
4622            assert!(result.is_none());
4623        }
4624
4625        #[test]
4626        fn count_sensor_counts_correctly() {
4627            let mut db = make_db();
4628
4629            // Write some temperature entries
4630            for i in 0..5 {
4631                db.append_sensor(i * 100, &Temperature { celsius: i as f32 })
4632                    .unwrap();
4633            }
4634
4635            // Write some accelerometer entries
4636            for i in 0..3 {
4637                db.append_sensor(
4638                    i * 100 + 50,
4639                    &Accelerometer {
4640                        x: i as i16,
4641                        y: 0,
4642                        z: 0,
4643                    },
4644                )
4645                .unwrap();
4646            }
4647
4648            db.sync().unwrap();
4649
4650            // Count each sensor type
4651            let temp_count = db.count_sensor::<Temperature>().unwrap();
4652            let accel_count = db.count_sensor::<Accelerometer>().unwrap();
4653            let total = db.count(None).unwrap();
4654
4655            assert_eq!(temp_count, 5);
4656            assert_eq!(accel_count, 3);
4657            assert_eq!(total, 8);
4658        }
4659
4660        #[test]
4661        fn query_all_sensor_gets_all_entries() {
4662            let mut db = make_db();
4663
4664            for i in 0..5 {
4665                db.append_sensor(
4666                    i * 100,
4667                    &Temperature {
4668                        celsius: i as f32 * 10.0,
4669                    },
4670                )
4671                .unwrap();
4672            }
4673            db.sync().unwrap();
4674
4675            let mut readings = alloc::vec::Vec::new();
4676            let count = db
4677                .query_all_sensor::<Temperature, _>(|hdr, temp| {
4678                    readings.push((hdr.timestamp, temp.celsius));
4679                    true
4680                })
4681                .unwrap();
4682
4683            assert_eq!(count, 5);
4684            assert_eq!(readings.len(), 5);
4685            assert_eq!(readings[0], (0, 0.0));
4686            assert_eq!(readings[4], (400, 40.0));
4687        }
4688    }
4689
4690    // =========================================================================
4691    // Raw API Tests for new methods
4692    // =========================================================================
4693
4694    #[test]
4695    fn query_all_gets_all_entries() {
4696        let mut db = make_db();
4697
4698        db.append(1, 100, &[0x01]).unwrap();
4699        db.append(1, 200, &[0x02]).unwrap();
4700        db.append(2, 150, &[0x0A]).unwrap();
4701        db.sync().unwrap();
4702
4703        // Query all entries for sensor 1
4704        let mut results = alloc::vec::Vec::new();
4705        let count = db
4706            .query_all(Some(1), |hdr, payload| {
4707                results.push((hdr.timestamp, payload[0]));
4708                true
4709            })
4710            .unwrap();
4711
4712        assert_eq!(count, 2);
4713        assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4714
4715        // Query all entries (no filter)
4716        let mut all_results = alloc::vec::Vec::new();
4717        let total = db
4718            .query_all(None, |hdr, _| {
4719                all_results.push(hdr.timestamp);
4720                true
4721            })
4722            .unwrap();
4723
4724        assert_eq!(total, 3);
4725    }
4726
4727    #[test]
4728    fn oldest_gets_first_entry() {
4729        let mut db = make_db();
4730
4731        db.append(1, 300, &[0x03]).unwrap();
4732        db.append(1, 100, &[0x01]).unwrap();
4733        db.append(1, 200, &[0x02]).unwrap();
4734        db.sync().unwrap();
4735
4736        let mut buf = [0u8; 16];
4737        // oldest() returns by sequence order (write order), not timestamp
4738        let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4739        assert_eq!(hdr.timestamp, 300); // First written entry
4740        assert_eq!(&buf[..n], &[0x03]);
4741    }
4742
4743    #[test]
4744    fn oldest_returns_none_for_missing_sensor() {
4745        let mut db = make_db();
4746
4747        db.append(1, 100, &[0x01]).unwrap();
4748        db.sync().unwrap();
4749
4750        let mut buf = [0u8; 16];
4751        let result = db.oldest(99, &mut buf).unwrap();
4752        assert!(result.is_none());
4753    }
4754
4755    #[test]
4756    fn count_works_correctly() {
4757        let mut db = make_db();
4758
4759        db.append(1, 100, &[0x01]).unwrap();
4760        db.append(1, 200, &[0x02]).unwrap();
4761        db.append(2, 150, &[0x0A]).unwrap();
4762        db.sync().unwrap();
4763
4764        assert_eq!(db.count(Some(1)).unwrap(), 2);
4765        assert_eq!(db.count(Some(2)).unwrap(), 1);
4766        assert_eq!(db.count(Some(99)).unwrap(), 0);
4767        assert_eq!(db.count(None).unwrap(), 3);
4768    }
4769
4770    #[test]
4771    fn count_uses_cached_total_for_none() {
4772        let mut db = make_db();
4773
4774        for i in 0..10 {
4775            db.append(1, i, &[i as u8]).unwrap();
4776        }
4777
4778        // count(None) should use cached total without scanning
4779        assert_eq!(db.count(None).unwrap(), 10);
4780        assert_eq!(db.stats().total_entries, 10);
4781    }
4782
4783    // =========================================================================
4784    // Sector rotation
4785    // =========================================================================
4786
4787    #[test]
4788    fn a_long_run_of_appends_rotates_sectors() {
4789        // Small enough that 500 entries cannot fit without rotating.
4790        const SMALL: usize = 4;
4791        let flash = MockFlash::<PAGE, SECTOR>::new(SMALL * SECTOR);
4792        let mut db: SensorDb<_, PAGE, SMALL> = SensorDb::new(flash, 0, SMALL as u16, 1).unwrap();
4793        db.format().unwrap();
4794
4795        let payload = [0x42u8; 4];
4796        for i in 0..500u64 {
4797            db.append(1, i * 10, &payload).unwrap();
4798        }
4799        db.sync().unwrap();
4800
4801        let stats = db.stats();
4802        assert!(stats.total_entries > 0);
4803        assert!(stats.used_sectors > 1);
4804
4805        let mut buf = [0u8; 4];
4806        let (hdr, _) = db.latest(1, &mut buf).unwrap().unwrap();
4807        assert_eq!(hdr.timestamp, 499 * 10);
4808    }
4809
4810    // =========================================================================
4811    // Auto traits
4812    // =========================================================================
4813
4814    #[test]
4815    fn a_database_is_sync_when_its_driver_is() {
4816        // The whole payoff of dropping the `RefCell`. It was `!Sync`, so the
4817        // only way to share a `SensorDb` was a `Mutex` — which yields `&mut`,
4818        // making the `&self` reads it bought unreachable in exactly the setting
4819        // they were for. A compile-time check, so it cannot rot into a comment.
4820        fn assert_sync<T: Sync>() {}
4821        fn assert_send<T: Send>() {}
4822
4823        assert_sync::<SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS>>();
4824        assert_send::<SensorDb<MockFlash<PAGE, SECTOR>, PAGE, SECTORS>>();
4825    }
4826
4827    // =========================================================================
4828    // Flush-free read tests
4829    // =========================================================================
4830
4831    #[test]
4832    fn read_without_sync_sees_buffered_entries() {
4833        let mut db = make_db();
4834
4835        db.append(1, 100, &[0x01]).unwrap();
4836        db.append(1, 200, &[0x02]).unwrap();
4837        db.append(2, 150, &[0x0A]).unwrap();
4838        // No sync!
4839
4840        // latest sees the buffered entry
4841        let mut buf = [0u8; 16];
4842        let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4843        assert_eq!(hdr.timestamp, 200);
4844        assert_eq!(&buf[..n], &[0x02]);
4845
4846        // oldest sees the first buffered entry
4847        let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4848        assert_eq!(hdr.timestamp, 100);
4849        assert_eq!(&buf[..n], &[0x01]);
4850
4851        // count sees all buffered entries
4852        assert_eq!(db.count(Some(1)).unwrap(), 2);
4853        assert_eq!(db.count(Some(2)).unwrap(), 1);
4854        assert_eq!(db.count(None).unwrap(), 3);
4855
4856        // query_range sees all buffered entries
4857        let mut results = alloc::vec::Vec::new();
4858        let count = db
4859            .query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4860                results.push((hdr.timestamp, payload[0]));
4861                true
4862            })
4863            .unwrap();
4864        assert_eq!(count, 2);
4865        assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4866    }
4867
4868    #[test]
4869    fn read_after_sync_sees_committed_and_buffered() {
4870        let mut db = make_db();
4871
4872        // Write and sync (committed)
4873        db.append(1, 100, &[0x01]).unwrap();
4874        db.append(1, 200, &[0x02]).unwrap();
4875        db.sync().unwrap();
4876
4877        // Write more without sync (buffered)
4878        db.append(1, 300, &[0x03]).unwrap();
4879        db.append(2, 250, &[0x0B]).unwrap();
4880
4881        // latest sees the newest buffered entry
4882        let mut buf = [0u8; 16];
4883        let (hdr, n) = db.latest(1, &mut buf).unwrap().unwrap();
4884        assert_eq!(hdr.timestamp, 300);
4885        assert_eq!(&buf[..n], &[0x03]);
4886
4887        // oldest sees the oldest committed entry
4888        let (hdr, n) = db.oldest(1, &mut buf).unwrap().unwrap();
4889        assert_eq!(hdr.timestamp, 100);
4890        assert_eq!(&buf[..n], &[0x01]);
4891
4892        // count sees committed + buffered
4893        assert_eq!(db.count(Some(1)).unwrap(), 3);
4894        assert_eq!(db.count(Some(2)).unwrap(), 1);
4895        assert_eq!(db.count(None).unwrap(), 4);
4896
4897        // query_range sees both committed and buffered
4898        let mut results = alloc::vec::Vec::new();
4899        db.query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4900            results.push((hdr.timestamp, payload[0]));
4901            true
4902        })
4903        .unwrap();
4904        assert_eq!(results, vec![(100, 0x01), (200, 0x02), (300, 0x03)]);
4905    }
4906
4907    #[test]
4908    fn query_range_order_with_buffered() {
4909        let mut db = make_db();
4910
4911        // Committed entries
4912        db.append(1, 100, &[0x01]).unwrap();
4913        db.append(1, 200, &[0x02]).unwrap();
4914        db.sync().unwrap();
4915
4916        // Buffered entries
4917        db.append(1, 300, &[0x03]).unwrap();
4918        db.append(1, 400, &[0x04]).unwrap();
4919
4920        // Verify committed entries come first, buffered entries come after
4921        let mut timestamps = alloc::vec::Vec::new();
4922        db.query_range(Some(1), 0, u64::MAX, |hdr, _| {
4923            timestamps.push(hdr.timestamp);
4924            true
4925        })
4926        .unwrap();
4927        assert_eq!(timestamps, vec![100, 200, 300, 400]);
4928    }
4929
4930    #[test]
4931    fn page_buf_empty_after_sync() {
4932        let mut db = make_db();
4933
4934        db.append(1, 100, &[0x01]).unwrap();
4935        db.append(1, 200, &[0x02]).unwrap();
4936        db.sync().unwrap();
4937
4938        // After sync, page buffer scanning should find nothing
4939        // (all entries are committed on flash). Verify by checking
4940        // that count(Some(1)) matches the sector-scanned count.
4941        assert_eq!(db.count(Some(1)).unwrap(), 2);
4942
4943        // Verify with query_range too
4944        let mut results = alloc::vec::Vec::new();
4945        db.query_range(Some(1), 0, u64::MAX, |hdr, payload| {
4946            results.push((hdr.timestamp, payload[0]));
4947            true
4948        })
4949        .unwrap();
4950        assert_eq!(results, vec![(100, 0x01), (200, 0x02)]);
4951    }
4952}