pigeonhole-db 1.1.0

data/vendor/format/src/shm.rs

@@ -0,0 +1,805 @@
+//! Shared-memory region layout. See `FORMAT.md` §11.
+//!
+//! ```text
+//! [header 4 KiB][watermarks: 64 B x shards][view area: 2 buffers][reader slots: 64 B x n]
+//! [row epochs: 8 B x slots][arenas]
+//! ```
+//!
+//! Fields that change while the region is live are accessed as atomics at the offsets given
+//! here; `pigeonhole-shm` does the atomic access, this module only fixes the numbers.
+//!
+//! ```
+//! use pigeonhole_format::shm::{ARENA_ALIGN, HEADER_LEN, ShmHeader};
+//!
+//! let h = ShmHeader::layout([1; 16], 4, 128, 4 << 20, 64 << 20, 4096, 66, 1234);
+//! assert_eq!(h.arenas_off % ARENA_ALIGN as u64, 0);
+//! let mut page = [0u8; HEADER_LEN];
+//! h.encode(&mut page);
+//! assert_eq!(ShmHeader::decode(&page).unwrap(), h);
+//! ```
+
+use crate::bytes::{Reader, le_u32, le_u64, put_at};
+use crate::version::SHM_MAGIC;
+use crate::{Error, FamilyId, ManifestVersion, ShmLayoutVersion, TableId, TabletId};
+
+/// Magic of the directory region.
+pub const DIRECTORY_MAGIC: [u8; 8] = *b"PHDBSHMD";
+
+/// Size of the region header.
+pub const HEADER_LEN: usize = 4096;
+/// Size of one shard's watermark line.
+pub const WATERMARK_STRIDE: usize = 64;
+/// Size of one reader slot.
+pub const READER_SLOT_LEN: usize = 64;
+/// Alignment of each shard arena (so NUMA binding works on whole pages).
+pub const ARENA_ALIGN: usize = 2 * 1024 * 1024;
+/// Size of one row-epoch slot (an atomic `u64`, D281).
+pub const ROW_EPOCH_LEN: usize = 8;
+/// Alignment of the row-epoch table.
+pub const ROW_EPOCHS_ALIGN: usize = 64;
+/// [`header::ROW_EPOCH_HASH`]: xxh3-64 of the row with the seed plus the table id
+/// ([`row_epoch_hash`]), the only hash this build knows.
+pub const ROW_EPOCH_HASH_XXH3: u32 = 1;
+/// [`header::ROW_EPOCH_FLAGS`] bit: the writer raises the slots (its row cache is on). A
+/// reader caches only when it is set.
+pub const ROW_EPOCHS_MAINTAINED: u32 = 1;
+
+/// The hash that picks a row's row-epoch slot (FORMAT §11.7, D281):
+/// `xxh3_64_with_seed(seed + table, row)`, the seed plus the table id wrapping in `u64`; the
+/// slot is `hash & (slots − 1)`. Specified algorithm and bytes, so every build of every
+/// process agrees (perf287's review of #947): a reader looking at a slot the writer never
+/// raises would serve a stale row for ever. The table goes into the seed rather than the
+/// input, so the row is hashed in place (a concatenated key cost a cached point get about
+/// 60 instructions, callgrind).
+///
+/// ```
+/// use pigeonhole_format::shm::row_epoch_hash;
+///
+/// assert_eq!(row_epoch_hash(42, 7, b"row"), twox_hash::XxHash3_64::oneshot_with_seed(49, b"row"));
+/// ```
+#[inline]
+pub fn row_epoch_hash(seed: u64, table: u32, row: &[u8]) -> u64 {
+    twox_hash::XxHash3_64::oneshot_with_seed(seed.wrapping_add(u64::from(table)), row)
+}
+
+/// Byte offsets of the header fields.
+pub mod header {
+    /// `[u8; 8]` [`SHM_MAGIC`](crate::version::SHM_MAGIC).
+    pub const MAGIC: usize = 0;
+    /// `u32` layout version.
+    pub const LAYOUT_VERSION: usize = 8;
+    /// `u32` header length (4096).
+    pub const HEADER_LEN: usize = 12;
+    /// `u64` total region length.
+    pub const REGION_LEN: usize = 16;
+    /// `[u8; 16]` database id from the superblock.
+    pub const DB_ID: usize = 24;
+    /// `u64` this region's generation (also in its name).
+    pub const GENERATION: usize = 40;
+    /// `u32` atomic: 0 initializing, 1 ready, 2 abandoned (a newer generation replaced it;
+    /// attached processes must re-attach through the directory).
+    pub const STATE: usize = 48;
+    /// `u32` shard count.
+    pub const SHARD_COUNT: usize = 52;
+    /// `u32` reader slot count.
+    pub const READER_SLOT_COUNT: usize = 56;
+    /// `u32` length of one view buffer.
+    pub const VIEW_BUFFER_LEN: usize = 60;
+    /// `u64` atomic: current manifest version.
+    pub const MANIFEST_VERSION: usize = 64;
+    /// `u64` atomic: `(view_version << 1) | buffer_index` of the current view. View versions
+    /// start at 1; 0 means none published yet.
+    pub const VIEW_POINTER: usize = 72;
+    /// `u32` writer process id.
+    pub const WRITER_PID: usize = 80;
+    /// `u64` writer process start time (opaque, platform-defined).
+    pub const WRITER_START_TIME: usize = 88;
+    /// `u64` offset of the watermark table.
+    pub const WATERMARKS_OFF: usize = 96;
+    /// `u64` offset of the view area.
+    pub const VIEWS_OFF: usize = 104;
+    /// `u64` offset of the reader-slot table.
+    pub const READER_SLOTS_OFF: usize = 112;
+    /// `u64` offset of shard 0's arena.
+    pub const ARENAS_OFF: usize = 120;
+    /// `u64` length of each shard arena.
+    pub const ARENA_LEN: usize = 128;
+    /// `u64` atomic: next global seqno to reserve.
+    pub const NEXT_SEQNO: usize = 136;
+    /// `u64` device number of the main file.
+    pub const FILE_DEVICE: usize = 144;
+    /// `u64` inode (file index on Windows) of the main file.
+    pub const FILE_INODE: usize = 152;
+    /// `u64` offset of the row-epoch table (layout version 5, D281): the row caches' write
+    /// watermarks, one atomic `u64` per slot.
+    pub const ROW_EPOCHS_OFF: usize = 160;
+    /// `u32` row-epoch slots, a power of two.
+    pub const ROW_EPOCH_SLOTS: usize = 168;
+    /// `u32` which hash picks a row's slot: 1 is [`row_epoch_hash`](super::row_epoch_hash)
+    /// (xxh3). Any other value is refused at attach.
+    pub const ROW_EPOCH_HASH: usize = 172;
+    /// `u64` seed of the hash that maps a `(table, row)` to its slot, random per generation.
+    pub const ROW_EPOCH_SEED: usize = 176;
+    /// `u32` row-epoch flags: bit 0, the writer raises the slots
+    /// ([`ROW_EPOCHS_MAINTAINED`](super::ROW_EPOCHS_MAINTAINED)).
+    pub const ROW_EPOCH_FLAGS: usize = 184;
+    /// `u64` atomic (layout version 6, D278): the lowest decided cross-shard seqno not yet
+    /// applied on every participant; `u64::MAX` when none. Snapshots stay below it. At 192,
+    /// 8-aligned past D281's row-epoch fields (160..188, then padding).
+    pub const CROSS_HELD: usize = 192;
+}
+
+/// Byte offsets within a watermark line.
+pub mod watermark {
+    /// `u64` atomic: the lowest seqno this shard holds unapplied (its current group's lower
+    /// bound); `u64::MAX` when idle. Decided cross-shard seqnos are held in the header's
+    /// [`CROSS_HELD`](super::header::CROSS_HELD) instead (layout version 6, D278).
+    pub const PENDING: usize = 0;
+    /// `u64` atomic (layout version 2, D227): the lowest seqno this shard holds that is not
+    /// yet durable at its commit's level: `PENDING`'s seqnos and every applied group whose
+    /// sync has not returned; `u64::MAX` when idle. Durable snapshots read it, and
+    /// [`CROSS_HELD`](super::header::CROSS_HELD).
+    pub const DURABLE: usize = 8;
+    /// `u64` atomic (layout version 7, D310): the lowest seqno this shard holds whose WAL
+    /// record is not yet in its stream file, among the records the change feed needs (a
+    /// fed table's `Durability::None` commits, buffered until the lazy flush or a stronger
+    /// write); `u64::MAX` when it holds none. The change feed's frontier stays below it.
+    /// Stored before `PENDING` lets the seqno go, and lowered only there or under a hold
+    /// that still covers the seqno, so a reader that loads `PENDING` and then this (Acquire
+    /// both) never passes an unwritten record. Only a writer with the feed on stores
+    /// anything but `u64::MAX`.
+    pub const WRITTEN: usize = 16;
+    /// `u64` atomic (layout version 7, D310): the lowest seqno this shard holds whose fed
+    /// record no sync covers yet (`Durability::None` and `Buffered`), stored as
+    /// [`WRITTEN`] is: a durable change feed stays below it, so it never delivers a change
+    /// a power loss could still undo. `u64::MAX` when it holds none.
+    pub const SYNCED: usize = 24;
+    /// `u64` atomic (layout version 8, D310 PR 4): the smallest epoch of any segment of this
+    /// shard's stream not yet recyclable (the writer's `FeedMarks::floor`); never goes down. 0
+    /// until a writer with the feed on stores it. A reader process's change feed reads it for
+    /// expiry and as rule C's backstop.
+    pub const FEED_FLOOR: usize = 32;
+    /// `u64` atomic (layout version 8): the stream's checkpoint `Lsn` (`FeedMarks::checkpoint`),
+    /// stored once the checkpoint edit is durable; never goes down. 0 until stored.
+    pub const FEED_CKPT: usize = 40;
+    /// `u64` atomic (layout version 8, simp724's B1 on #1352): the largest start bound the
+    /// stream's retained history can't serve: the key of the writer's checkpoint-history
+    /// entry at the floor (`Feed::oldest_bound`), so some record dropped below the floor may
+    /// have a key up to it. A reader process's feed asked to start after a seqno below it
+    /// has lost history and expires. Stored (`fetch_max`, Release) before the floor it
+    /// belongs to, so a reader that loads `FEED_FLOOR` and then this (Acquire both) gets a
+    /// bound at least that floor's; raised at checkpoints too. 0 until stored.
+    pub const FEED_BOUND: usize = 48;
+}
+
+/// Byte offsets within a reader slot.
+pub mod reader_slot {
+    /// `u32` atomic: 0 free, 1 claiming, 2 active.
+    pub const STATE: usize = 0;
+    /// `u32` process id.
+    pub const PID: usize = 4;
+    /// `u64` process start time.
+    pub const START_TIME: usize = 8;
+    /// `u64` atomic: pinned snapshot seqno, 0 if none.
+    pub const PINNED_SEQNO: usize = 16;
+    /// `u64` atomic: pinned view version, 0 if none.
+    pub const PINNED_VIEW: usize = 24;
+    /// `u64` generation the slot was claimed under.
+    pub const GENERATION: usize = 32;
+}
+
+/// The immutable part of the header, written once when the region is built.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ShmHeader {
+    /// Layout version.
+    pub layout_version: ShmLayoutVersion,
+    /// Total region length.
+    pub region_len: u64,
+    /// Database id.
+    pub db_id: [u8; 16],
+    /// Shards (one arena and one watermark line each).
+    pub shard_count: u32,
+    /// Reader slots.
+    pub reader_slot_count: u32,
+    /// Length of each of the two view buffers.
+    pub view_buffer_len: u32,
+    /// Offset of the watermark table.
+    pub watermarks_off: u64,
+    /// Offset of the view area.
+    pub views_off: u64,
+    /// Offset of the reader-slot table.
+    pub reader_slots_off: u64,
+    /// Offset of shard 0's arena.
+    pub arenas_off: u64,
+    /// Length of each arena.
+    pub arena_len: u64,
+    /// Offset of the row-epoch table.
+    pub row_epochs_off: u64,
+    /// Row-epoch slots (a power of two).
+    pub row_epoch_slots: u32,
+    /// Seed of the row-epoch hash (set by the builder; [`ShmHeader::layout`] leaves it 0).
+    pub row_epoch_seed: u64,
+    /// Which hash picks a row's slot ([`ROW_EPOCH_HASH_XXH3`]).
+    pub row_epoch_hash: u32,
+    /// Row-epoch flags ([`ROW_EPOCHS_MAINTAINED`]; set by the builder, 0 from `layout`).
+    pub row_epoch_flags: u32,
+    /// Device of the main file.
+    pub file_device: u64,
+    /// Inode of the main file.
+    pub file_inode: u64,
+}
+
+impl ShmHeader {
+    /// Computes a layout for the given sizes, aligning each area.
+    #[allow(clippy::too_many_arguments)]
+    pub fn layout(
+        db_id: [u8; 16],
+        shard_count: u32,
+        reader_slot_count: u32,
+        view_buffer_len: u32,
+        arena_len: u64,
+        row_epoch_slots: u32,
+        file_device: u64,
+        file_inode: u64,
+    ) -> Self {
+        // Saturating arithmetic: an absurd request yields a layout `decode` rejects rather
+        // than a panic.
+        let align = |v: u64, a: u64| v.div_ceil(a).saturating_mul(a);
+        let arena_len = align(arena_len, ARENA_ALIGN as u64);
+        let watermarks_off = HEADER_LEN as u64;
+        let views_off = watermarks_off + WATERMARK_STRIDE as u64 * u64::from(shard_count);
+        let reader_slots_off = align(views_off + 2 * u64::from(view_buffer_len), 64);
+        let row_epochs_off = align(
+            reader_slots_off + READER_SLOT_LEN as u64 * u64::from(reader_slot_count),
+            ROW_EPOCHS_ALIGN as u64,
+        );
+        let arenas_off = align(
+            row_epochs_off + ROW_EPOCH_LEN as u64 * u64::from(row_epoch_slots),
+            ARENA_ALIGN as u64,
+        );
+        let region_len =
+            arenas_off.saturating_add(arena_len.saturating_mul(u64::from(shard_count)));
+        Self {
+            layout_version: ShmLayoutVersion::CURRENT,
+            region_len,
+            db_id,
+            shard_count,
+            reader_slot_count,
+            view_buffer_len,
+            watermarks_off,
+            views_off,
+            reader_slots_off,
+            arenas_off,
+            arena_len,
+            row_epochs_off,
+            row_epoch_slots,
+            row_epoch_seed: 0,
+            row_epoch_hash: ROW_EPOCH_HASH_XXH3,
+            row_epoch_flags: 0,
+            file_device,
+            file_inode,
+        }
+    }
+
+    /// Encodes the immutable fields (atomic fields are left zero). `generation`, `writer_pid`
+    /// and `writer_start_time` are not part of this struct; `pigeonhole-shm` writes them at
+    /// their [`header`] offsets.
+    pub fn encode(&self, out: &mut [u8; HEADER_LEN]) {
+        out.fill(0);
+        let o = &mut out[..];
+        put_at(o, header::MAGIC, &SHM_MAGIC);
+        put_at(
+            o,
+            header::LAYOUT_VERSION,
+            &self.layout_version.0.to_le_bytes(),
+        );
+        put_at(o, header::HEADER_LEN, &(HEADER_LEN as u32).to_le_bytes());
+        put_at(o, header::REGION_LEN, &self.region_len.to_le_bytes());
+        put_at(o, header::DB_ID, &self.db_id);
+        put_at(o, header::SHARD_COUNT, &self.shard_count.to_le_bytes());
+        put_at(
+            o,
+            header::READER_SLOT_COUNT,
+            &self.reader_slot_count.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::VIEW_BUFFER_LEN,
+            &self.view_buffer_len.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::WATERMARKS_OFF,
+            &self.watermarks_off.to_le_bytes(),
+        );
+        put_at(o, header::VIEWS_OFF, &self.views_off.to_le_bytes());
+        put_at(
+            o,
+            header::READER_SLOTS_OFF,
+            &self.reader_slots_off.to_le_bytes(),
+        );
+        put_at(o, header::ARENAS_OFF, &self.arenas_off.to_le_bytes());
+        put_at(o, header::ARENA_LEN, &self.arena_len.to_le_bytes());
+        put_at(o, header::FILE_DEVICE, &self.file_device.to_le_bytes());
+        put_at(o, header::FILE_INODE, &self.file_inode.to_le_bytes());
+        put_at(
+            o,
+            header::ROW_EPOCHS_OFF,
+            &self.row_epochs_off.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::ROW_EPOCH_SLOTS,
+            &self.row_epoch_slots.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::ROW_EPOCH_SEED,
+            &self.row_epoch_seed.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::ROW_EPOCH_HASH,
+            &self.row_epoch_hash.to_le_bytes(),
+        );
+        put_at(
+            o,
+            header::ROW_EPOCH_FLAGS,
+            &self.row_epoch_flags.to_le_bytes(),
+        );
+    }
+
+    /// Decodes and validates magic, layout version and offsets against `region_len`.
+    ///
+    /// The layout version must equal [`ShmLayoutVersion::CURRENT`] exactly. The areas must
+    /// appear in order without overlapping, arenas must be [`ARENA_ALIGN`]-aligned and sized,
+    /// and everything must lie within `region_len`. The row-epoch table is another process's
+    /// data that every reader indexes with `hash & (slots - 1)` and loads atomically (D281,
+    /// perf287's M1): its slot count must be a nonzero power of two and its offset
+    /// [`ROW_EPOCHS_ALIGN`]-aligned, between the reader slots and the arenas, so a validated
+    /// index never leaves the table.
+    pub fn decode(bytes: &[u8]) -> crate::Result<Self> {
+        const WHAT: &str = "shm header";
+        let Some(b) = bytes.get(..HEADER_LEN) else {
+            return Err(Error::Truncated { what: WHAT });
+        };
+        if b[..8] != SHM_MAGIC {
+            return Err(Error::BadMagic { what: WHAT });
+        }
+        let layout_version = ShmLayoutVersion(le_u32(b, header::LAYOUT_VERSION));
+        if layout_version != ShmLayoutVersion::CURRENT {
+            return Err(Error::UnsupportedVersion {
+                what: WHAT,
+                found: layout_version.0,
+            });
+        }
+        let h = Self {
+            layout_version,
+            region_len: le_u64(b, header::REGION_LEN),
+            db_id: b[header::DB_ID..header::DB_ID + 16]
+                .try_into()
+                .expect("16 bytes"),
+            shard_count: le_u32(b, header::SHARD_COUNT),
+            reader_slot_count: le_u32(b, header::READER_SLOT_COUNT),
+            view_buffer_len: le_u32(b, header::VIEW_BUFFER_LEN),
+            watermarks_off: le_u64(b, header::WATERMARKS_OFF),
+            views_off: le_u64(b, header::VIEWS_OFF),
+            reader_slots_off: le_u64(b, header::READER_SLOTS_OFF),
+            arenas_off: le_u64(b, header::ARENAS_OFF),
+            arena_len: le_u64(b, header::ARENA_LEN),
+            row_epochs_off: le_u64(b, header::ROW_EPOCHS_OFF),
+            row_epoch_slots: le_u32(b, header::ROW_EPOCH_SLOTS),
+            row_epoch_seed: le_u64(b, header::ROW_EPOCH_SEED),
+            row_epoch_hash: le_u32(b, header::ROW_EPOCH_HASH),
+            row_epoch_flags: le_u32(b, header::ROW_EPOCH_FLAGS),
+            file_device: le_u64(b, header::FILE_DEVICE),
+            file_inode: le_u64(b, header::FILE_INODE),
+        };
+        let fits = |off: u64, n: u64, stride: u64, next: u64| {
+            n.checked_mul(stride)
+                .and_then(|len| off.checked_add(len))
+                .is_some_and(|end| end <= next)
+        };
+        let ok = le_u32(b, header::HEADER_LEN) as usize == HEADER_LEN
+            && h.watermarks_off >= HEADER_LEN as u64
+            && fits(
+                h.watermarks_off,
+                h.shard_count.into(),
+                WATERMARK_STRIDE as u64,
+                h.views_off,
+            )
+            && fits(h.views_off, 2, h.view_buffer_len.into(), h.reader_slots_off)
+            && fits(
+                h.reader_slots_off,
+                h.reader_slot_count.into(),
+                READER_SLOT_LEN as u64,
+                h.row_epochs_off,
+            )
+            && h.row_epoch_slots.is_power_of_two()
+            && h.row_epoch_hash == ROW_EPOCH_HASH_XXH3
+            && h.row_epochs_off.is_multiple_of(ROW_EPOCHS_ALIGN as u64)
+            && fits(
+                h.row_epochs_off,
+                h.row_epoch_slots.into(),
+                ROW_EPOCH_LEN as u64,
+                h.arenas_off,
+            )
+            && h.arenas_off.is_multiple_of(ARENA_ALIGN as u64)
+            && h.arena_len.is_multiple_of(ARENA_ALIGN as u64)
+            && fits(
+                h.arenas_off,
+                h.shard_count.into(),
+                h.arena_len,
+                h.region_len,
+            );
+        if !ok {
+            return Err(Error::Corrupt { what: WHAT });
+        }
+        Ok(h)
+    }
+}
+
+/// Name of the directory region: `phdb-` followed by 16 lowercase hex digits of
+/// `xxh3_64(device LE ++ inode LE)` of the main file, identical on every process however it
+/// spells the path. The directory is one page that records the current generation; its layout
+/// never changes, so it is never rebuilt (decision D27).
+pub fn directory_name(device: u64, inode: u64) -> String {
+    let mut id = [0u8; 16];
+    id[..8].copy_from_slice(&device.to_le_bytes());
+    id[8..].copy_from_slice(&inode.to_le_bytes());
+    format!("phdb-{:016x}", crate::checksum::xxh3_64(&id))
+}
+
+/// Name of the region for `generation`: the directory name, `-`, and the generation in
+/// lowercase hex (at most 31 bytes, macOS's `shm_open` limit). A rebuilt region always has a
+/// new name, so an old mapping that some process still holds (Windows keeps named mappings
+/// alive while any handle is open) is never mistaken for the new one.
+///
+/// The 31-byte bound holds for generations below `2^36` (nine hex digits).
+///
+/// ```
+/// use pigeonhole_format::shm::{directory_name, region_name};
+///
+/// let dir = directory_name(66, 1234);
+/// assert_eq!(dir.len(), 21);
+/// assert_eq!(region_name(66, 1234, 0x2a), format!("{dir}-2a"));
+/// ```
+pub fn region_name(device: u64, inode: u64, generation: u64) -> String {
+    format!("{}-{generation:x}", directory_name(device, inode))
+}
+
+/// Byte offsets within the directory region (4096 bytes, layout fixed forever).
+pub mod directory {
+    /// `[u8; 8]` magic `PHDBSHMD`.
+    pub const MAGIC: usize = 0;
+    /// `u32` directory format (always 1).
+    pub const FORMAT: usize = 8;
+    /// `u64` atomic: generation of the current region (0 = none yet).
+    pub const GENERATION: usize = 16;
+    /// `u32` atomic: layout version of the current region.
+    pub const LAYOUT_VERSION: usize = 24;
+    /// Size of the directory region.
+    pub const LEN: usize = 4096;
+}
+
+/// One tablet in a published view.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ViewTablet {
+    /// Tablet.
+    pub tablet: TabletId,
+    /// Table.
+    pub table: TableId,
+    /// Owning shard.
+    pub shard: u16,
+    /// Inclusive start row (unescaped); empty means unbounded.
+    pub start: Vec<u8>,
+    /// Exclusive end row; `None` means unbounded.
+    pub end: Option<Vec<u8>>,
+}
+
+/// One memtable in a published view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ViewMemtable {
+    /// Tablet.
+    pub tablet: TabletId,
+    /// Family.
+    pub family: FamilyId,
+    /// Shard whose arena holds it.
+    pub shard: u16,
+    /// 0 for the active memtable, then 1, 2, ... for frozen ones, newest first.
+    pub age: u8,
+    /// Offset of the memtable header within the shard arena.
+    pub root: u32,
+}
+
+/// A view as published in shared memory: what a reader process needs to read the writer's
+/// memtables and know which manifest version goes with them.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ViewRecord {
+    /// View version (strictly increasing, starting at 1).
+    pub view_version: u64,
+    /// Manifest version this view's SST set comes from.
+    pub manifest_version: ManifestVersion,
+    /// The tablet map.
+    pub tablets: Vec<ViewTablet>,
+    /// Every memtable a reader must consult.
+    pub memtables: Vec<ViewMemtable>,
+}
+
+impl ViewRecord {
+    /// Encoded length, so the writer can check it against the view buffer before publishing.
+    pub fn encoded_len(&self) -> usize {
+        VIEW_HEADER_LEN
+            + self
+                .tablets
+                .iter()
+                .map(ViewTablet::encoded_len)
+                .sum::<usize>()
+            + VIEW_MEMTABLE_LEN * self.memtables.len()
+    }
+
+    /// Encodes with a CRC32C so a reader can detect a torn copy.
+    pub fn encode(&self, out: &mut Vec<u8>) {
+        let start = out.len();
+        out.extend_from_slice(&self.view_version.to_le_bytes());
+        out.extend_from_slice(&self.manifest_version.to_le_bytes());
+        out.extend_from_slice(&(self.encoded_len() as u32).to_le_bytes());
+        out.extend_from_slice(&(self.tablets.len() as u32).to_le_bytes());
+        out.extend_from_slice(&(self.memtables.len() as u32).to_le_bytes());
+        out.extend_from_slice(&[0; 4]); // crc, filled below
+        for t in &self.tablets {
+            let end = t.end.as_deref().unwrap_or_default();
+            out.extend_from_slice(&t.tablet.0.to_le_bytes());
+            out.extend_from_slice(&t.table.0.to_le_bytes());
+            out.extend_from_slice(&t.shard.to_le_bytes());
+            out.extend_from_slice(&u16::from(t.end.is_some()).to_le_bytes());
+            out.extend_from_slice(&(t.start.len() as u32).to_le_bytes());
+            out.extend_from_slice(&(end.len() as u32).to_le_bytes());
+            out.extend_from_slice(&t.start);
+            out.extend_from_slice(end);
+            out.resize(start + (out.len() - start).next_multiple_of(8), 0);
+        }
+        for m in &self.memtables {
+            out.extend_from_slice(&m.tablet.0.to_le_bytes());
+            out.extend_from_slice(&m.family.0.to_le_bytes());
+            out.extend_from_slice(&m.shard.to_le_bytes());
+            out.push(m.age);
+            out.push(0);
+            out.extend_from_slice(&m.root.to_le_bytes());
+            out.extend_from_slice(&[0; 4]);
+        }
+        let crc = crate::checksum::crc32c(&out[start..]);
+        out[start + 28..start + 32].copy_from_slice(&crc.to_le_bytes());
+    }
+
+    /// Decodes and verifies a copied view buffer. `bytes` may extend past the record (a whole
+    /// view buffer); `byte_len` says where it ends.
+    pub fn decode(bytes: &[u8]) -> crate::Result<Self> {
+        const WHAT: &str = "shm view record";
+        let Some(h) = bytes.get(..VIEW_HEADER_LEN) else {
+            return Err(Error::Truncated { what: WHAT });
+        };
+        let byte_len = le_u32(h, 16) as usize;
+        let tablet_count = le_u32(h, 20) as usize;
+        let memtable_count = le_u32(h, 24) as usize;
+        if byte_len < VIEW_HEADER_LEN {
+            return Err(Error::Corrupt { what: WHAT });
+        }
+        let Some(rec) = bytes.get(..byte_len) else {
+            return Err(Error::Truncated { what: WHAT });
+        };
+        let crc = crate::checksum::crc32c_append(
+            crate::checksum::crc32c_append(crate::checksum::crc32c(&rec[..28]), &[0; 4]),
+            &rec[32..],
+        );
+        if crc != le_u32(h, 28) {
+            return Err(Error::Checksum { what: WHAT });
+        }
+        let body = byte_len - VIEW_HEADER_LEN;
+        // Bound the allocations by what the record can hold.
+        if tablet_count > body / VIEW_TABLET_FIXED_LEN || memtable_count > body / VIEW_MEMTABLE_LEN
+        {
+            return Err(Error::Corrupt { what: WHAT });
+        }
+        let mut r = Reader::new(&rec[VIEW_HEADER_LEN..], WHAT);
+        let mut tablets = Vec::with_capacity(tablet_count);
+        for _ in 0..tablet_count {
+            let tablet = TabletId(r.u64()?);
+            let table = TableId(r.u32()?);
+            let shard = r.u16()?;
+            let flags = r.u16()?;
+            let start_len = r.u32()? as usize;
+            let end_len = r.u32()? as usize;
+            let start = r.take(start_len)?.to_vec();
+            let end_bytes = r.take(end_len)?;
+            let end = if flags & 1 != 0 {
+                Some(end_bytes.to_vec())
+            } else if end_len == 0 {
+                None
+            } else {
+                return Err(Error::Corrupt { what: WHAT });
+            };
+            r.take(r.pos().next_multiple_of(8) - r.pos())?;
+            tablets.push(ViewTablet {
+                tablet,
+                table,
+                shard,
+                start,
+                end,
+            });
+        }
+        let mut memtables = Vec::with_capacity(memtable_count);
+        for _ in 0..memtable_count {
+            let tablet = TabletId(r.u64()?);
+            let family = FamilyId(r.u32()?);
+            let shard = r.u16()?;
+            let age = r.u8()?;
+            r.u8()?;
+            let root = r.u32()?;
+            r.u32()?;
+            memtables.push(ViewMemtable {
+                tablet,
+                family,
+                shard,
+                age,
+                root,
+            });
+        }
+        if r.remaining() != 0 {
+            return Err(Error::Corrupt { what: WHAT });
+        }
+        Ok(Self {
+            view_version: le_u64(h, 0),
+            manifest_version: le_u64(h, 8),
+            tablets,
+            memtables,
+        })
+    }
+}
+
+/// Size of the fixed part of a view record.
+const VIEW_HEADER_LEN: usize = 32;
+/// Size of the fixed part of a view tablet entry (before its row bytes and padding).
+const VIEW_TABLET_FIXED_LEN: usize = 24;
+/// Size of a view memtable entry.
+const VIEW_MEMTABLE_LEN: usize = 24;
+
+impl ViewTablet {
+    fn encoded_len(&self) -> usize {
+        let rows = self.start.len() + self.end.as_ref().map_or(0, Vec::len);
+        (VIEW_TABLET_FIXED_LEN + rows).next_multiple_of(8)
+    }
+}
+
+/// Memtable layout inside a shard arena. Offsets are `u32`, relative to the arena base; `0` is
+/// null (the first 64 bytes of every arena are reserved).
+pub mod memtable {
+    /// Maximum skiplist height.
+    pub const MAX_HEIGHT: usize = 16;
+    /// Size of the memtable header.
+    pub const HEADER_LEN: usize = 64;
+    /// Header: `u32` [`MEMTABLE_MAGIC`](crate::version::MEMTABLE_MAGIC).
+    pub const H_MAGIC: usize = 0;
+    /// Header: `u16` layout version (2: nodes carry a stale-tail offset, D277).
+    pub const H_VERSION: usize = 4;
+    /// Header: `u8` flags (bit 0: frozen; bit 1: the writer records stale tails, D277).
+    pub const H_FLAGS: usize = 6;
+    /// Header: `u32` offset of the head node (height [`MAX_HEIGHT`]).
+    pub const H_HEAD: usize = 8;
+    /// Header: `u32` atomic entry count.
+    pub const H_COUNT: usize = 12;
+    /// Header: `u64` atomic bytes allocated.
+    pub const H_BYTES: usize = 16;
+    /// Header: `u64` atomic largest seqno inserted.
+    pub const H_MAX_SEQNO: usize = 24;
+    /// Header: `u64` smallest seqno inserted.
+    pub const H_MIN_SEQNO: usize = 32;
+    /// Node: `u32` internal key length.
+    pub const N_KEY_LEN: usize = 0;
+    /// Node: `u32` stored value length.
+    pub const N_VALUE_LEN: usize = 4;
+    /// Node: `u8` height.
+    pub const N_HEIGHT: usize = 8;
+    /// Node: `u32` stale-tail offset (D194, D277): a later node of the same column, or 0.
+    /// Written once, before the node is linked.
+    pub const N_TAIL: usize = 12;
+    /// Node: tower of `height` atomic `u32` next offsets, starting here; key bytes then value
+    /// bytes follow the tower. Nodes are 4-byte aligned.
+    pub const N_TOWER: usize = 16;
+}
+
+#[cfg(test)]
+mod reader_slot_tests {
+    use super::*;
+
+    /// The default reader slot count went from 126 to 128 (#693 PR 5): the slot area is
+    /// padded up to the arenas' 2 MiB alignment, so for the default 4 MiB view buffers and any
+    /// shard count up to 256, the region is exactly as large either way.
+    #[test]
+    fn two_more_default_slots_cost_no_space() {
+        for shards in [1u32, 2, 4, 8, 16, 64, 256] {
+            let len =
+                |slots| ShmHeader::layout([0; 16], shards, slots, 4 << 20, 64 << 20, 4096, 0, 0);
+            let (old, new) = (len(126), len(128));
+            assert_eq!(old.region_len, new.region_len, "{shards} shards");
+            assert_eq!(old.arenas_off, new.arenas_off, "{shards} shards");
+        }
+    }
+}
+
+#[cfg(test)]
+mod row_epoch_tests {
+    use super::*;
+
+    /// D281 (perf287's M1): the row-epoch table's fields come from another process, so a bad
+    /// one is refused at decode (every attach decodes the header), never indexed.
+    #[test]
+    fn a_bad_row_epoch_table_is_corrupt() {
+        let good = ShmHeader::layout([0; 16], 2, 4, 4096, 1, 1 << 12, 0, 0);
+        let decode = |h: ShmHeader| {
+            let mut page = [0u8; HEADER_LEN];
+            h.encode(&mut page);
+            ShmHeader::decode(&page)
+        };
+        assert_eq!(decode(good), Ok(good));
+        let slots_end = good.reader_slots_off + READER_SLOT_LEN as u64 * 4;
+        let cases = [
+            (
+                "no slots",
+                ShmHeader {
+                    row_epoch_slots: 0,
+                    ..good
+                },
+            ),
+            (
+                "not a power of two",
+                ShmHeader {
+                    row_epoch_slots: 3,
+                    ..good
+                },
+            ),
+            (
+                "misaligned",
+                ShmHeader {
+                    row_epochs_off: good.row_epochs_off + 8,
+                    ..good
+                },
+            ),
+            (
+                "over the reader slots",
+                ShmHeader {
+                    row_epochs_off: slots_end - 64,
+                    ..good
+                },
+            ),
+            (
+                "into the arenas",
+                ShmHeader {
+                    row_epoch_slots: 1 << 20,
+                    ..good
+                },
+            ),
+            (
+                "past the region",
+                ShmHeader {
+                    row_epochs_off: !63,
+                    ..good
+                },
+            ),
+            (
+                "an unknown slot hash",
+                ShmHeader {
+                    row_epoch_hash: 2,
+                    ..good
+                },
+            ),
+        ];
+        for (what, h) in cases {
+            assert_eq!(
+                decode(h),
+                Err(Error::Corrupt { what: "shm header" }),
+                "{what}"
+            );
+        }
+    }
+}