pigeonhole-db 1.1.0

data/vendor/format/src/sst.rs

@@ -0,0 +1,233 @@
+//! SST footer and properties. An SST is
+//! `data blocks, index partitions, top index, row filter, column filter, properties, footer`
+//! laid out from the start of its extent. See `FORMAT.md` §5.
+//!
+//! ```
+//! use pigeonhole_format::block::BlockAddr;
+//! use pigeonhole_format::sst::Footer;
+//! use pigeonhole_format::FormatVersion;
+//!
+//! let footer = Footer {
+//!     top_index: BlockAddr { offset: 4096, len: 200 },
+//!     row_filter: BlockAddr::default(),
+//!     column_filter: BlockAddr::default(),
+//!     properties: BlockAddr { offset: 4296, len: 120 },
+//!     compression_dict: BlockAddr::default(),
+//!     version: FormatVersion::CURRENT,
+//!     flags: 0,
+//! };
+//! assert_eq!(Footer::decode(&footer.encode()).unwrap(), footer);
+//! ```
+
+use crate::Error;
+use crate::block::BlockAddr;
+use crate::bytes::{Reader, le_u32, le_u64};
+use crate::version::SST_MAGIC;
+use crate::{FamilyId, FormatVersion, Seqno, TableId, TabletId, Timestamp};
+
+/// Size of the fixed footer at the end of every SST.
+pub const FOOTER_LEN: usize = 104;
+
+/// The fixed-size footer. Its last 8 bytes are [`SST_MAGIC`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Footer {
+    /// Top-level index block.
+    pub top_index: BlockAddr,
+    /// Row-key filter block, or zero length if the family has no filter.
+    pub row_filter: BlockAddr,
+    /// Row+qualifier filter block, or zero length.
+    pub column_filter: BlockAddr,
+    /// Properties block.
+    pub properties: BlockAddr,
+    /// Compression dictionary block, or zero length (reserved for zstd dictionaries).
+    pub compression_dict: BlockAddr,
+    /// Format version of this SST.
+    pub version: FormatVersion,
+    /// The SST's incompatible feature bits (format 4, D269; reserved and zero before): a
+    /// build that does not know a bit refuses the SST ([`Error::UnsupportedFeature`]). A
+    /// feature that sets one also sets its bit in the superblock, so an older build refuses
+    /// the file at open rather than mid-read. No bit is defined yet.
+    pub flags: u32,
+}
+
+/// The SST feature bits ([`Footer::flags`]) this build knows (none yet).
+pub const KNOWN_SST_FEATURES: u32 = 0;
+
+impl Footer {
+    /// Encodes to exactly [`FOOTER_LEN`] bytes (checksum and magic included).
+    pub fn encode(&self) -> [u8; FOOTER_LEN] {
+        let mut out = [0; FOOTER_LEN];
+        let addrs = [
+            self.top_index,
+            self.row_filter,
+            self.column_filter,
+            self.properties,
+            self.compression_dict,
+        ];
+        for (i, a) in addrs.iter().enumerate() {
+            out[16 * i..16 * i + 8].copy_from_slice(&a.offset.to_le_bytes());
+            out[16 * i + 8..16 * i + 12].copy_from_slice(&a.len.to_le_bytes());
+        }
+        out[80..84].copy_from_slice(&self.version.0.to_le_bytes());
+        out[84..88].copy_from_slice(&self.flags.to_le_bytes());
+        let checksum = crate::checksum::xxh3_64(&out[..88]);
+        out[88..96].copy_from_slice(&checksum.to_le_bytes());
+        out[96..].copy_from_slice(&SST_MAGIC);
+        out
+    }
+
+    /// Decodes and verifies magic, checksum and version. Reads the last [`FOOTER_LEN`] bytes
+    /// of `bytes`, so the tail of an SST (or the whole SST) can be passed directly.
+    pub fn decode(bytes: &[u8]) -> crate::Result<Self> {
+        let Some(start) = bytes.len().checked_sub(FOOTER_LEN) else {
+            return Err(Error::Truncated { what: "sst footer" });
+        };
+        let b = &bytes[start..];
+        if b[96..] != SST_MAGIC {
+            return Err(Error::BadMagic { what: "sst footer" });
+        }
+        if crate::checksum::xxh3_64(&b[..88]) != le_u64(b, 88) {
+            return Err(Error::Checksum { what: "sst footer" });
+        }
+        let version = FormatVersion(le_u32(b, 80));
+        version.check("sst footer")?;
+        let flags = le_u32(b, 84);
+        if flags & !KNOWN_SST_FEATURES != 0 {
+            return Err(Error::UnsupportedFeature {
+                what: "sst feature bits",
+                value: u64::from(flags & !KNOWN_SST_FEATURES),
+            });
+        }
+        let addr = |i: usize| BlockAddr {
+            offset: le_u64(b, 16 * i),
+            len: le_u32(b, 16 * i + 8),
+        };
+        Ok(Self {
+            top_index: addr(0),
+            row_filter: addr(1),
+            column_filter: addr(2),
+            properties: addr(3),
+            compression_dict: addr(4),
+            version,
+            flags,
+        })
+    }
+}
+
+/// Summary statistics stored in the properties block.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct Properties {
+    /// Table the SST belongs to.
+    pub table: TableId,
+    /// Family the SST belongs to.
+    pub family: FamilyId,
+    /// Tablet that wrote it.
+    pub tablet: TabletId,
+    /// Total entries.
+    pub entries: u64,
+    /// Distinct rows.
+    pub rows: u64,
+    /// Delete entries of any kind.
+    pub deletes: u64,
+    /// Merge operands.
+    pub merges: u64,
+    /// Sum of internal key lengths.
+    pub raw_key_bytes: u64,
+    /// Sum of stored value lengths.
+    pub raw_value_bytes: u64,
+    /// Data blocks.
+    pub data_blocks: u32,
+    /// Index partitions.
+    pub index_partitions: u32,
+    /// Smallest and largest seqno.
+    pub seqno_range: (Seqno, Seqno),
+    /// Smallest and largest timestamp (drives FIFO-by-time and TTL drops).
+    pub ts_range: (Timestamp, Timestamp),
+    /// Creation time, microseconds since the Unix epoch.
+    pub created_micros: u64,
+    /// Smallest internal key.
+    pub smallest_key: Vec<u8>,
+    /// Largest internal key.
+    pub largest_key: Vec<u8>,
+    /// Merge operator name in force when written, empty if none.
+    pub merge_operator: String,
+    /// `Some(max_versions)` when a bottommost compaction wrote the SST with nothing holding
+    /// its purge back (no live snapshot, nothing above its inputs, every other source of a
+    /// counter family listed), under a family keeping `max_versions` (0: every version):
+    /// a later rewrite drops nothing but what expires meanwhile (D268, ICR 0053). `None`:
+    /// unknown (any other writer, or an SST written before the property).
+    pub fully_purged: Option<u32>,
+}
+
+/// `Properties::fully_purged`'s flag bit in the purge word.
+const FULLY_PURGED: u32 = 1;
+
+impl Properties {
+    /// Appends the logical properties block.
+    pub fn encode(&self, out: &mut Vec<u8>) {
+        out.extend_from_slice(&self.table.0.to_le_bytes());
+        out.extend_from_slice(&self.family.0.to_le_bytes());
+        out.extend_from_slice(&self.tablet.0.to_le_bytes());
+        for v in [
+            self.entries,
+            self.rows,
+            self.deletes,
+            self.merges,
+            self.raw_key_bytes,
+            self.raw_value_bytes,
+        ] {
+            out.extend_from_slice(&v.to_le_bytes());
+        }
+        out.extend_from_slice(&self.data_blocks.to_le_bytes());
+        out.extend_from_slice(&self.index_partitions.to_le_bytes());
+        for v in [
+            self.seqno_range.0,
+            self.seqno_range.1,
+            self.ts_range.0,
+            self.ts_range.1,
+            self.created_micros,
+        ] {
+            out.extend_from_slice(&v.to_le_bytes());
+        }
+        crate::varint::put_bytes(out, &self.smallest_key);
+        crate::varint::put_bytes(out, &self.largest_key);
+        crate::varint::put_bytes(out, self.merge_operator.as_bytes());
+        let (flags, max_versions) = self.fully_purged.map_or((0, 0), |v| (FULLY_PURGED, v));
+        out.extend_from_slice(&flags.to_le_bytes());
+        out.extend_from_slice(&max_versions.to_le_bytes());
+    }
+
+    /// Decodes a logical properties block. Trailing bytes after the last known field are
+    /// ignored, so later versions can append fields.
+    pub fn decode(bytes: &[u8]) -> crate::Result<Self> {
+        let mut r = Reader::new(bytes, "sst properties");
+        let mut props = Self {
+            table: TableId(r.u32()?),
+            family: FamilyId(r.u32()?),
+            tablet: TabletId(r.u64()?),
+            entries: r.u64()?,
+            rows: r.u64()?,
+            deletes: r.u64()?,
+            merges: r.u64()?,
+            raw_key_bytes: r.u64()?,
+            raw_value_bytes: r.u64()?,
+            data_blocks: r.u32()?,
+            index_partitions: r.u32()?,
+            seqno_range: (r.u64()?, r.u64()?),
+            ts_range: (r.u64()?, r.u64()?),
+            created_micros: r.u64()?,
+            smallest_key: r.bytes()?.to_vec(),
+            largest_key: r.bytes()?.to_vec(),
+            merge_operator: r.string()?,
+            fully_purged: None,
+        };
+        // The purge word and its `max_versions` (D268), absent from blocks written before
+        // them; unknown flag bits are ignored.
+        if r.remaining() >= 8 {
+            let flags = r.u32()?;
+            let max_versions = r.u32()?;
+            props.fully_purged = (flags & FULLY_PURGED != 0).then_some(max_versions);
+        }
+        Ok(props)
+    }
+}

data/vendor/format/src/superblock.rs

@@ -0,0 +1,345 @@
+//! Superblocks (pages 0 and 1) and the lock page (page 2). See `FORMAT.md` §8.
+
+use crate::bytes::{le_u32, le_u64};
+use crate::version::SUPERBLOCK_MAGIC;
+use crate::{Error, FormatVersion, ManifestVersion, PAGE_SIZE};
+
+/// Page number of the first superblock.
+pub const SUPERBLOCK_PAGE_A: u64 = 0;
+/// Page number of the second superblock.
+pub const SUPERBLOCK_PAGE_B: u64 = 1;
+/// Page reserved for byte-range locks; never read or written.
+pub const LOCK_PAGE: u64 = 2;
+/// First page available to the extent allocator (pages 0-15 are reserved).
+pub const FIRST_DATA_PAGE: u64 = 16;
+
+/// Absolute file offset of the writer lock byte (held exclusive by the one writer).
+pub const WRITER_LOCK_BYTE: u64 = LOCK_PAGE * crate::PAGE_SIZE as u64;
+/// Absolute file offset of the presence lock byte (held shared by every open process).
+pub const PRESENCE_LOCK_BYTE: u64 = WRITER_LOCK_BYTE + 1;
+/// Absolute file offset of the shared-memory init byte (held exclusive while a process
+/// creates, validates or rebuilds the shared-memory region).
+pub const SHM_INIT_LOCK_BYTE: u64 = WRITER_LOCK_BYTE + 2;
+/// Absolute file offset of reader slot 0's liveness lock byte (shared-memory layout 3,
+/// #693 PR 3): slot `i` is byte `READER_LOCK_BASE + i`, held exclusive by the reader process
+/// that owns the slot for as long as it does. The writer frees a slot only once it can take
+/// that byte itself. 2^62 lies beyond any file this format can reach, so no read or write
+/// ever touches these bytes (on Windows, where byte-range locks are mandatory, that matters).
+pub const READER_LOCK_BASE: u64 = 1 << 62;
+
+/// Number of meaningful bytes at the start of a superblock page; the rest is zero.
+pub const SUPERBLOCK_LEN: usize = 128;
+/// The superblock page's extension area (format 4, D269; FORMAT §8.2): reserved for later
+/// 1.x features, zero until one uses it. The superblock checksum does not cover it, so a
+/// feature that stores data here brings its own checksum. Every format 4 build carries the
+/// area unchanged into each root commit (`pigeonhole-pager`), so an unaware build keeps a
+/// compat feature's data here; data tied to the root goes stale when that build commits a
+/// new root, and the feature must detect that. [`Superblock::encode`] zeroes it.
+pub const EXTENSION_AREA: std::ops::Range<usize> = SUPERBLOCK_LEN..crate::PAGE_SIZE - 8;
+
+/// A power-of-two run of pages: `64 KiB << size_class` bytes starting at `page`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ExtentRef {
+    /// First page.
+    pub page: u64,
+    /// Size class: 0 = 64 KiB, 1 = 128 KiB, ... 10 = 64 MiB.
+    pub size_class: u8,
+}
+
+impl ExtentRef {
+    /// Largest size class (64 MiB).
+    pub const MAX_CLASS: u8 = 10;
+
+    /// Absolute byte offset in the main file.
+    pub fn offset(&self) -> u64 {
+        self.page.saturating_mul(PAGE_SIZE as u64)
+    }
+
+    /// Length in bytes. Saturates for a size class above [`MAX_CLASS`](Self::MAX_CLASS),
+    /// which decoders reject.
+    pub fn len(&self) -> u64 {
+        (64u64 * 1024)
+            .checked_shl(u32::from(self.size_class))
+            .unwrap_or(u64::MAX)
+    }
+
+    /// Validates a decoded extent: page past the reserved pages, known size class, aligned to
+    /// its own size.
+    pub(crate) fn validate(self, what: &'static str) -> crate::Result<Self> {
+        let pages = self.len() / PAGE_SIZE as u64;
+        if self.page < FIRST_DATA_PAGE
+            || self.size_class > Self::MAX_CLASS
+            || !self.page.is_multiple_of(pages)
+        {
+            return Err(Error::Corrupt { what });
+        }
+        Ok(self)
+    }
+
+    /// Always false; extents are never empty. Present for API symmetry with `len`.
+    pub fn is_empty(&self) -> bool {
+        false
+    }
+}
+
+/// The file's feature sets (format 4, D269; FORMAT §8.2), as ext4 has them. A file sets a
+/// bit only once it uses the feature, so a file that uses none stays openable by every 1.x
+/// build. A build that meets a bit it does not know:
+/// - `incompat`: refuses the file ([`Error::UnsupportedFeature`]);
+/// - `ro_compat`: may read it but not write it;
+/// - `compat`: ignores it, and keeps it when it rewrites the superblock.
+///
+/// **A compat feature's data must stay correct, or detectably stale, after a build that
+/// does not know the feature commits.** Such a build keeps the bit and the
+/// [`EXTENSION_AREA`] bytes, but it may change the root they describe, and it drops manifest
+/// edits with skippable tags (128..=255) at its next manifest snapshot. A feature that
+/// cannot tolerate that is `ro_compat`, so builds that do not know it cannot write.
+///
+/// Setting or clearing an `incompat` or `ro_compat` bit commits both superblock pages before
+/// the file relies on the change: otherwise the other page keeps the old bits, and a build
+/// may refuse the file, or write to it, by the stale page.
+///
+/// ```
+/// use pigeonhole_format::superblock::Features;
+///
+/// assert!(Features::default().check_read().is_ok());
+/// assert!(Features { incompat: 1 << 40, ..Features::default() }.check_read().is_err());
+/// let ro = Features { ro_compat: 1 << 5, ..Features::default() };
+/// assert!(ro.check_read().is_ok() && ro.check_write().is_err());
+/// assert!(Features { compat: 1, ..Features::default() }.check_write().is_ok());
+/// ```
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
+pub struct Features {
+    /// Features an older build may read and write, ignoring them.
+    pub compat: u64,
+    /// Features an older build may read but must not write.
+    pub ro_compat: u64,
+    /// Features an older build must refuse the file for.
+    pub incompat: u64,
+}
+
+impl Features {
+    /// The `compat` bits this build knows (none yet).
+    pub const KNOWN_COMPAT: u64 = 0;
+    /// The `ro_compat` bits this build knows (none yet).
+    pub const KNOWN_RO_COMPAT: u64 = 0;
+    /// The `incompat` bits this build knows: bit 0, the Min, Max and Hll family kinds
+    /// ([`INCOMPAT_AGGREGATES`](crate::manifest::INCOMPAT_AGGREGATES), D294).
+    pub const KNOWN_INCOMPAT: u64 = crate::manifest::INCOMPAT_AGGREGATES;
+
+    /// `incompat` bits this build does not know.
+    pub fn unknown_incompat(&self) -> u64 {
+        self.incompat & !Self::KNOWN_INCOMPAT
+    }
+
+    /// `ro_compat` bits this build does not know.
+    pub fn unknown_ro_compat(&self) -> u64 {
+        self.ro_compat & !Self::KNOWN_RO_COMPAT
+    }
+
+    /// Fails with [`Error::UnsupportedFeature`] if the file uses an incompatible feature this
+    /// build does not know: it must not even read it.
+    pub fn check_read(&self) -> crate::Result<()> {
+        match self.unknown_incompat() {
+            0 => Ok(()),
+            bits => Err(Error::UnsupportedFeature {
+                what: "incompatible feature bits",
+                value: bits,
+            }),
+        }
+    }
+
+    /// As [`check_read`](Self::check_read), and also fails if the file uses a
+    /// read-only-compatible feature this build does not know: it may read it, not write it.
+    pub fn check_write(&self) -> crate::Result<()> {
+        self.check_read()?;
+        match self.unknown_ro_compat() {
+            0 => Ok(()),
+            bits => Err(Error::UnsupportedFeature {
+                what: "read-only-compatible feature bits (the file can be opened read-only)",
+                value: bits,
+            }),
+        }
+    }
+}
+
+/// One superblock. The valid copy with the higher `sequence` is current.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Superblock {
+    /// Format version of the file.
+    pub version: FormatVersion,
+    /// Page size; always 4096 in version 1.
+    pub page_size: u32,
+    /// Incremented by every root commit.
+    pub sequence: u64,
+    /// Random id chosen at creation; WAL segments and the shared-memory region carry it.
+    pub db_id: [u8; 16],
+    /// Extent holding the manifest snapshot block; `None` for an empty database.
+    pub snapshot: Option<ExtentRef>,
+    /// Length of the snapshot block in bytes.
+    pub snapshot_len: u32,
+    /// Extent holding the manifest delta log; `None` if no delta follows the snapshot.
+    pub log: Option<ExtentRef>,
+    /// Bytes of the delta log that belong to this root (later bytes are not live).
+    pub log_len: u32,
+    /// Manifest version this root represents (the last delta's, or the snapshot's).
+    pub manifest_version: ManifestVersion,
+    /// High-water mark of the file, in pages.
+    pub file_pages: u64,
+    /// Bit 0: the last writer closed cleanly. Other bits reserved.
+    pub flags: u64,
+    /// The file's feature sets (format 4; zero in older versions, whose bytes 96..120 are
+    /// reserved).
+    pub features: Features,
+}
+
+impl Superblock {
+    /// Encodes into a full page buffer (bytes past [`SUPERBLOCK_LEN`] are zero).
+    pub fn encode(&self, page: &mut [u8; crate::PAGE_SIZE]) {
+        page.fill(0);
+        let p = &mut page[..];
+        put(p, 0, &SUPERBLOCK_MAGIC);
+        put(p, 8, &self.version.0.to_le_bytes());
+        put(p, 12, &self.page_size.to_le_bytes());
+        put(p, 16, &self.sequence.to_le_bytes());
+        put(p, 24, &self.db_id);
+        let snap = self.snapshot.map_or((0, 0), |e| (e.page, e.size_class));
+        put(p, 40, &snap.0.to_le_bytes());
+        p[48] = snap.1;
+        put(p, 52, &self.snapshot_len.to_le_bytes());
+        put(p, 56, &self.manifest_version.to_le_bytes());
+        put(p, 64, &self.file_pages.to_le_bytes());
+        put(p, 72, &self.flags.to_le_bytes());
+        let log = self.log.map_or((0, 0), |e| (e.page, e.size_class));
+        put(p, 80, &log.0.to_le_bytes());
+        p[88] = log.1;
+        put(p, 92, &self.log_len.to_le_bytes());
+        put(p, 96, &self.features.compat.to_le_bytes());
+        put(p, 104, &self.features.ro_compat.to_le_bytes());
+        put(p, 112, &self.features.incompat.to_le_bytes());
+        let checksum = crate::checksum::xxh3_64(&p[..120]);
+        put(p, 120, &checksum.to_le_bytes());
+    }
+
+    /// Decodes and verifies magic, checksum and version.
+    pub fn decode(page: &[u8]) -> crate::Result<Self> {
+        let Some(b) = page.get(..SUPERBLOCK_LEN) else {
+            return Err(Error::Truncated { what: "superblock" });
+        };
+        if b[..8] != SUPERBLOCK_MAGIC {
+            return Err(Error::BadMagic { what: "superblock" });
+        }
+        if crate::checksum::xxh3_64(&b[..120]) != le_u64(b, 120) {
+            return Err(Error::Checksum { what: "superblock" });
+        }
+        let version = FormatVersion(le_u32(b, 8));
+        version.check("superblock")?;
+        let page_size = le_u32(b, 12);
+        if page_size as usize != PAGE_SIZE {
+            return Err(Error::Corrupt {
+                what: "superblock page size",
+            });
+        }
+        let extent = |page: u64, size_class: u8, what| match page {
+            0 => Ok(None),
+            _ => ExtentRef { page, size_class }.validate(what).map(Some),
+        };
+        let snapshot = extent(le_u64(b, 40), b[48], "superblock snapshot extent")?;
+        let snapshot_len = le_u32(b, 52);
+        let log = extent(le_u64(b, 80), b[88], "superblock log extent")?;
+        let log_len = le_u32(b, 92);
+        // A length must fit its extent; an absent extent has length zero.
+        let fits =
+            |e: Option<ExtentRef>, len: u32| e.map_or(len == 0, |e| u64::from(len) <= e.len());
+        if !fits(snapshot, snapshot_len) || !fits(log, log_len) {
+            return Err(Error::Corrupt {
+                what: "superblock manifest length",
+            });
+        }
+        Ok(Self {
+            version,
+            page_size,
+            sequence: le_u64(b, 16),
+            db_id: b[24..40].try_into().expect("16 bytes"),
+            snapshot,
+            snapshot_len,
+            manifest_version: le_u64(b, 56),
+            file_pages: le_u64(b, 64),
+            flags: le_u64(b, 72),
+            log,
+            log_len,
+            // Bytes 96..120 were reserved (written zero) before format 4.
+            features: if version >= FormatVersion(4) {
+                Features {
+                    compat: le_u64(b, 96),
+                    ro_compat: le_u64(b, 104),
+                    incompat: le_u64(b, 112),
+                }
+            } else {
+                Features::default()
+            },
+        })
+    }
+
+    /// Picks the current superblock from the two decode results, or fails if neither is valid.
+    /// Returns it with its page number ([`SUPERBLOCK_PAGE_A`] or [`SUPERBLOCK_PAGE_B`]); the
+    /// next root commit overwrites the other page. On a tie in `sequence`, A wins. If both
+    /// fail, an [`Error::UnsupportedVersion`] is preferred (a newer file, not a corrupt one).
+    ///
+    /// ```
+    /// use pigeonhole_format::superblock::Superblock;
+    /// use pigeonhole_format::FormatVersion;
+    ///
+    /// let sb = |sequence| Superblock {
+    ///     version: FormatVersion::CURRENT,
+    ///     page_size: 4096,
+    ///     sequence,
+    ///     db_id: [7; 16],
+    ///     snapshot: None,
+    ///     snapshot_len: 0,
+    ///     log: None,
+    ///     log_len: 0,
+    ///     manifest_version: 0,
+    ///     file_pages: 16,
+    ///     flags: 0,
+    ///     features: Default::default(),
+    /// };
+    /// let mut page = [0u8; 4096];
+    /// sb(5).encode(&mut page);
+    /// let a = Superblock::decode(&page);
+    /// sb(6).encode(&mut page);
+    /// let b = Superblock::decode(&page);
+    /// assert_eq!(Superblock::choose(a, b).unwrap(), (sb(6), 1));
+    /// ```
+    pub fn choose(a: crate::Result<Self>, b: crate::Result<Self>) -> crate::Result<(Self, u64)> {
+        // A slot using an incompatible feature this build does not know is refused like a
+        // newer version: a newer build set the bit (in both slots, before using the feature),
+        // and the other slot may be one it has not rewritten yet.
+        let features = |r: crate::Result<Self>| r.and_then(|s| s.features.check_read().map(|()| s));
+        let (a, b) = (features(a), features(b));
+        match (a, b) {
+            // A slot with a valid checksum but a newer version was written by a newer build
+            // (an upgrade that may have finished only that slot): never pass it over for the
+            // older slot, whose root that build may already have freed (#496).
+            (Err(e @ (Error::UnsupportedVersion { .. } | Error::UnsupportedFeature { .. })), _)
+            | (_, Err(e @ (Error::UnsupportedVersion { .. } | Error::UnsupportedFeature { .. }))) => {
+                Err(e)
+            }
+            (Ok(a), Ok(b)) if b.sequence > a.sequence => Ok((b, SUPERBLOCK_PAGE_B)),
+            (Ok(a), _) => Ok((a, SUPERBLOCK_PAGE_A)),
+            (Err(_), Ok(b)) => Ok((b, SUPERBLOCK_PAGE_B)),
+            (Err(ea), Err(eb)) => match (&ea, &eb) {
+                (_, Error::UnsupportedVersion { .. })
+                    if !matches!(ea, Error::UnsupportedVersion { .. }) =>
+                {
+                    Err(eb)
+                }
+                _ => Err(ea),
+            },
+        }
+    }
+}
+
+fn put(buf: &mut [u8], off: usize, v: &[u8]) {
+    crate::bytes::put_at(buf, off, v);
+}