Skip to main content

forgedb_storage_native/
lib.rs

1//! ForgeDB Storage Engine
2//!
3//! High-performance columnar storage engine for ForgeDB with positional I/O reads,
4//! WAL integration, and tombstone-based deletion tracking.
5//!
6//! # Overview
7//!
8//! `forgedb-storage` is the core storage engine for ForgeDB, implementing a columnar storage
9//! architecture optimized for both read and write performance. The crate provides:
10//!
11//! - **Columnar storage format** - Fixed-size and variable-length columns stored separately
12//! - **Positional I/O reads** - Concurrent-safe reads via `pread(2)`-style positional I/O
13//!   (`FileExt::read_exact_at`) that avoids touching the shared file cursor; multiple `&self`
14//!   readers on the same column can execute concurrently without synchronisation
15//! - **Seek-based writes** - Append methods seek to end-of-file before writing, taking `&mut self`
16//!   for exclusive ownership during the seek + write sequence
17//! - **WAL integration** - Write-Ahead Log support for ACID properties and crash recovery
18//! - **Tombstone tracking** - Efficient soft-delete mechanism without data movement
19//! - **Type-safe API** - Strong typing for columns and database operations
20//!
21//! # Architecture
22//!
23//! ## Columnar Storage Format
24//!
25//! The storage engine uses a columnar layout where each column is stored in separate files:
26//!
27//! ```text
28//! data/
29//! ├── manifest.json              # Database metadata
30//! ├── tombstones.bin            # Deletion bitmap
31//! ├── fixed/
32//! │   └── u64_0.bin            # Fixed-size column (8 bytes per row)
33//! └── variable/
34//!     ├── string_data_0.bin    # Variable-length data
35//!     └── string_offsets_0.bin # (offset, length) pairs
36//! ```
37//!
38//! ## Fixed-Size vs Variable-Length Columns
39//!
40//! **Fixed-Size Columns** (u64, i64, f64, uuid):
41//! - Storage: `fixed/{type}_{index}.bin`
42//! - Layout: Sequential values with no overhead
43//! - Access: O(1) random access via `offset = index * value_size`
44//!
45//! **Variable-Length Columns** (strings):
46//! - Data file: `variable/string_data_{index}.bin` (append-only)
47//! - Offsets file: `variable/string_offsets_{index}.bin` (offset, length pairs)
48//! - Access: O(1) random access (read offset pair, then read string)
49//!
50//! ## Tombstone Bitmap
51//!
52//! Deletions are tracked using a tombstone bitmap:
53//! - Storage: `tombstones.bin` (1 byte per row)
54//! - Format: 0 = active, 1 = deleted
55//! - Benefits: No data movement, fast deletes, preserves row IDs
56//!
57//! # Examples
58//!
59//! ## Describing a model's physical layout (`Manifest`)
60//!
61//! Generated code owns the directory layout and drives the column types directly;
62//! the schema-blind [`Manifest`] records the physical layout (read by backup /
63//! the inspector), persisted next to the column files.
64//!
65//! ```rust,no_run
66//! use forgedb_storage_native::{Manifest, ColumnMetadata, ColumnType};
67//! use std::path::PathBuf;
68//!
69//! let manifest = Manifest {
70//!     schema_version: 1,
71//!     engine_version: 1,
72//!     row_count: 42,
73//!     columns: vec![
74//!         ColumnMetadata { name: "id".to_string(), column_type: ColumnType::U64, column_index: 0, ..Default::default() },
75//!         ColumnMetadata { name: "email".to_string(), column_type: ColumnType::String, column_index: 1, ..Default::default() },
76//!     ],
77//!     wal_enabled: false,
78//!     last_checkpoint: 0,
79//!     compaction_epoch: 0,
80//!     row_anchor: None,
81//!     auto_sequences: Default::default(),
82//! };
83//! manifest.save_to(&PathBuf::from("./mydb/manifest.json"))?;
84//! let reopened = Manifest::load_from(&PathBuf::from("./mydb/manifest.json"))?;
85//! assert_eq!(reopened.row_count, 42);
86//! # Ok::<(), std::io::Error>(())
87//! ```
88//!
89//! ## Working with Columns
90//!
91//! ```rust,no_run
92//! use forgedb_storage_native::FixedColumn;
93//! use std::path::PathBuf;
94//!
95//! // Fixed-size column
96//! let mut id_column = FixedColumn::new(PathBuf::from("./data/fixed/u64_0.bin"), 8)?;
97//! id_column.append_u64(1001)?;
98//! let id = id_column.read_u64(0)?;  // &self — concurrent reads are safe
99//! assert_eq!(id, 1001);
100//! id_column.flush()?;  // explicit fsync before a checkpoint or close
101//! # Ok::<(), std::io::Error>(())
102//! ```
103//!
104//! # Durability Model
105//!
106//! Column files (`FixedColumn`, `VariableColumn`, `Tombstones`) **do not fsync on every append**.
107//! Appended bytes are visible to subsequent reads via the OS page cache, but a crash before an
108//! explicit [`FixedColumn::flush`] / [`VariableColumn::flush`] / [`Tombstones::flush`] call can
109//! lose the most recent appends from those files.
110//!
111//! The **WAL is the crash-durability boundary**: all mutations should be recorded in the WAL
112//! (via [`WalManager`]) before being applied to the column files. On recovery, the WAL is replayed
113//! into the columnar materialization. Call `flush()` at commit / checkpoint boundaries to durably
114//! persist the column files.
115//!
116//! # Public API
117//!
118//! ## Core Types
119//!
120//! - [`Manifest`] - Physical-layout metadata stored in manifest.json
121//! - [`FixedColumn`] - Storage for fixed-size column data
122//! - [`VariableColumn`] - Storage for variable-length column data
123//! - [`Tombstones`] - Deletion tracking bitmap
124//!
125//! ## WAL Re-exports
126//!
127//! Types from [`forgedb-wal`](../forgedb_wal) for convenience:
128//! - [`FsyncPolicy`] - Controls when WAL is fsynced to disk
129//! - [`WalEntry`] - A framed opaque-bytes entry (model tag + `Raw` payload)
130//! - [`WalManager`] - High-level WAL interface
131//! - [`WalOperation`] - The `Raw { payload }` operation variant
132//!
133//! # Related Crates
134//!
135//! - [`forgedb-wal`](../forgedb_wal) - Write-Ahead Log for durability
136//! - [`forgedb-compaction`](../forgedb_compaction) - Background compaction for space reclamation
137
138// WAL re-exports (schema-agnostic substrate surface only)
139pub use forgedb_wal::{FsyncPolicy, WalEntry, WalManager, WalOperation};
140
141mod dir_lock;
142pub use dir_lock::DirLock;
143
144use std::fs::{self, File, OpenOptions};
145use std::io::{self, IoSlice, Seek, SeekFrom, Write};
146use std::os::unix::fs::FileExt;
147use std::path::PathBuf;
148
149/// Push a file's dirty page-cache pages to the storage device **without** a
150/// device-cache barrier (#153 — single-barrier checkpoint).
151///
152/// On macOS, `File::sync_all`/`sync_data` both map to `fcntl(F_FULLFSYNC)` — an
153/// expensive device barrier (~3.5 ms). `libc::fsync` is the *cheap* flush
154/// (~27 µs) that only pushes the file's data into the drive's (volatile) write
155/// cache; a single [`device_barrier`] afterward flushes that whole cache to
156/// permanent media, covering **every** file `fsync`ed this way on the same
157/// device. So a checkpoint of N columns costs N cheap fsyncs + ONE barrier
158/// instead of N barriers. On non-macOS, `sync_data` (fdatasync) is the cheapest
159/// available durable flush.
160#[cfg(target_os = "macos")]
161fn fsync_to_drive(file: &File) -> io::Result<()> {
162    use std::os::unix::io::AsRawFd;
163    // SAFETY: `file` is a live, open descriptor for the duration of the call.
164    if unsafe { libc::fsync(file.as_raw_fd()) } == -1 {
165        return Err(io::Error::last_os_error());
166    }
167    Ok(())
168}
169
170#[cfg(not(target_os = "macos"))]
171fn fsync_to_drive(file: &File) -> io::Result<()> {
172    file.sync_data()
173}
174
175/// Issue ONE device-cache barrier (#153). On macOS `fcntl(F_FULLFSYNC)` tells
176/// the drive to flush its entire write cache to permanent media — which makes
177/// durable every file previously handed to [`fsync_to_drive`] on the same
178/// device, so a checkpoint needs only one of these. On non-macOS, `sync_all` is
179/// the barrier.
180#[cfg(target_os = "macos")]
181fn device_barrier(file: &File) -> io::Result<()> {
182    use std::os::unix::io::AsRawFd;
183    // SAFETY: `file` is a live, open descriptor for the duration of the call.
184    if unsafe { libc::fcntl(file.as_raw_fd(), libc::F_FULLFSYNC) } == -1 {
185        return Err(io::Error::last_os_error());
186    }
187    Ok(())
188}
189
190#[cfg(not(target_os = "macos"))]
191fn device_barrier(file: &File) -> io::Result<()> {
192    file.sync_all()
193}
194
195/// Default schema serial for manifests written before the field existed.
196/// Old on-disk manifests deserialize as v1 (the original layout), not v0.
197fn default_schema_version() -> u32 {
198    1
199}
200
201/// Default engine generation for every manifest written before #254 added the
202/// field: generation 1, the baseline. This is what makes the counter additive
203/// rather than a second format break.
204fn default_engine_version() -> u32 {
205    1
206}
207
208/// Manifest stores metadata about the database
209#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
210pub struct Manifest {
211    /// The **app's** schema-migration serial: how many migrations from its own
212    /// `migrations/` lineage have been applied. Derived by
213    /// `MigrationLineage::current_schema_version`, baked into generated code as
214    /// `EXPECTED_SCHEMA_VERSION`, and compared by the generated `open()` guard,
215    /// which refuses a dir whose schema is not the one this binary was generated
216    /// from (#74 Phase 1). Lineage-sourced, never hand-edited.
217    ///
218    /// **The on-disk key stays `format_version` (#254).** Only the Rust name
219    /// changed, because the old one described the engine rather than the app.
220    /// A *different* vestigial `schema_version` key — hardcoded to `1` at every
221    /// write site, never incremented, never compared — used to occupy this name
222    /// on disk; it is deleted, and serde's unknown-key tolerance is what lets a
223    /// manifest still carrying it deserialize. Reading the wrong one of those two
224    /// is not a subtle bug: it would compare the open-guard against a constant.
225    #[serde(rename = "format_version", default = "default_schema_version")]
226    pub schema_version: u32,
227    /// ForgeDB's own **engine byte-format generation** (#254) — owned by the
228    /// released version line, not by the app. It covers both value
229    /// reinterpretation and physical layout, which is why it is not
230    /// `layout_version`.
231    ///
232    /// Orthogonal to `schema_version` above: a schema mismatch means *the app's
233    /// schema changed* and is fixed by the app's migration bin; an engine
234    /// mismatch means *ForgeDB changed* and is fixed by `forgedb migrate engine`.
235    /// Conflating them would send a user to regenerate a schema that is correct.
236    ///
237    /// Generations are assigned at merge order, not at design time — two format
238    /// changes in one cycle would otherwise both claim the same number and
239    /// whichever landed second would silently redefine the other's meaning.
240    ///
241    /// | gen | change |
242    /// |---|---|
243    /// | 1 | baseline — everything written before this field existed |
244    /// | 2 | timestamp values are microseconds, not seconds (#254) |
245    #[serde(default = "default_engine_version")]
246    pub engine_version: u32,
247    pub row_count: usize,
248    pub columns: Vec<ColumnMetadata>,
249    #[serde(default)]
250    pub wal_enabled: bool,
251    #[serde(default)]
252    pub last_checkpoint: u64,
253    /// Generation counter bumped on every compaction. A byte-watermark
254    /// incremental backup (#57) is valid only within one epoch — compaction
255    /// rewrites files and shifts offsets, so crossing an epoch forces a fresh
256    /// full backup. Additive (`#[serde(default)]`) for on-disk back-compat.
257    #[serde(default)]
258    pub compaction_epoch: u64,
259    /// On-disk layout format version, so a schema-blind reader (backup #57,
260    /// inspector #63) can refuse mismatched bytes instead of misreading them.
261    /// Which file's length authoritatively counts committed rows, and how many
262    /// bytes it spends per row. For a model this is `tombstones.bin` (1 byte/row,
263    /// appended last per insert); for an M2M junction it is `fixed/right.bin`
264    /// (16 bytes/row, appended last per link). A schema-blind reader derives the
265    /// committed row count as `len(anchor) / bytes_per_row` — the live watermark,
266    /// independent of the (possibly stale) `row_count` field above. `None` on
267    /// legacy manifests ⇒ fall back to `tombstones.bin`.
268    #[serde(default)]
269    pub row_anchor: Option<RowAnchor>,
270    /// Per-field allocation high-water marks, as an **opaque** `name -> highest
271    /// value handed out` map (#187).
272    ///
273    /// The substrate neither parses these keys nor branches on them: it stores
274    /// and returns strings and integers. Which fields appear, what the numbers
275    /// mean, and every read and write of them belong to generated code — the
276    /// same class of layout metadata as `compaction_epoch`.
277    ///
278    /// It exists because a rescan alone cannot survive compaction: compaction
279    /// physically drops dead rows, so a post-compaction reopen derives a *lower*
280    /// maximum than was actually issued and hands the same value out twice. The
281    /// contract is a **floor, not a source of truth** — a reader takes
282    /// `max(persisted, scanned)`, so a crash that loses the tip falls back to the
283    /// scan, which is always safe. That is what buys durability without an fsync
284    /// per allocation.
285    ///
286    /// `BTreeMap` (not `HashMap`) so the serialized JSON is byte-stable across
287    /// writes. Additive (`#[serde(default)]`) for on-disk back-compat.
288    #[serde(default)]
289    pub auto_sequences: std::collections::BTreeMap<String, u64>,
290}
291
292/// Physical descriptor of the file whose length counts committed rows.
293/// Layout fact only — names a file and a per-row byte stride, never a schema
294/// semantic. See [`Manifest::row_anchor`].
295#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
296pub struct RowAnchor {
297    /// Anchor file path relative to the model/junction directory.
298    pub relative_path: String,
299    /// Bytes the anchor file spends per committed row (`1` for tombstones,
300    /// `16` for a junction's uuid `right` column).
301    pub bytes_per_row: usize,
302}
303
304impl Manifest {
305    /// Load a manifest from an explicit path (e.g. a per-model
306    /// `<model>/manifest.json`). Used by
307    /// schema-blind ops tooling — `forgedb-backup` (#57), the inspector (#63) —
308    /// that reads layout metadata for one model directory.
309    pub fn load_from(path: &std::path::Path) -> io::Result<Manifest> {
310        let content = fs::read_to_string(path)?;
311        serde_json::from_str(&content)
312            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
313    }
314
315    /// Atomically write this manifest to `path` via temp-file + `fsync` +
316    /// `rename`. A crash mid-write leaves the intact previous manifest rather
317    /// than a truncated/garbage one that would fail to parse on the next open.
318    /// The temp file is `<path>.tmp`.
319    pub fn save_to(&self, path: &std::path::Path) -> io::Result<()> {
320        let content = serde_json::to_string_pretty(self)
321            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
322
323        if let Some(parent) = path.parent() {
324            fs::create_dir_all(parent)?;
325        }
326
327        let mut tmp_path = path.as_os_str().to_owned();
328        tmp_path.push(".tmp");
329        let tmp_path = PathBuf::from(tmp_path);
330        {
331            let mut tmp = OpenOptions::new()
332                .write(true)
333                .create(true)
334                .truncate(true)
335                .open(&tmp_path)?;
336            tmp.write_all(content.as_bytes())?;
337            tmp.sync_all()?;
338        }
339        fs::rename(&tmp_path, path)?;
340        Ok(())
341    }
342}
343
344/// Whether a column is fixed-width (positional I/O) or variable-length
345/// (offset-indexed data file). Physical-layout fact only — never a schema
346/// semantic. Lets a schema-blind reader bound each file without guessing.
347#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
348pub enum ColumnKind {
349    #[default]
350    Fixed,
351    Variable,
352}
353
354#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
355pub struct ColumnMetadata {
356    pub name: String,
357    pub column_type: ColumnType,
358    pub column_index: usize,
359    /// Bytes per row for a fixed column; `0` for a variable column (its width
360    /// lives in the offsets file). Lets backup compute a fixed column's exact
361    /// committed length as `row_count * value_size` without guessing.
362    #[serde(default)]
363    pub value_size: usize,
364    /// Fixed vs. variable — selects how a reader bounds the column's files.
365    #[serde(default)]
366    pub kind: ColumnKind,
367    /// Column file path relative to the model directory (e.g.
368    /// `fixed/u32_0.bin` or `variable/string_data_1.bin`). For a variable
369    /// column this is the data file; the offsets file is the same path with
370    /// `_data.bin` → `_offsets.bin` (the storage-layout convention `stats.rs`
371    /// already relies on).
372    #[serde(default)]
373    pub relative_path: String,
374}
375
376#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
377pub enum ColumnType {
378    #[default]
379    U32,
380    U64,
381    I32,
382    I64,
383    F64,
384    Bool,
385    Uuid,
386    Timestamp,
387    String,
388    /// Fixed-size byte array (for char(N), structs, fixed arrays)
389    FixedBytes(usize),
390}
391
392/// A read snapshot: an immutable row-count watermark captured at a point in time.
393///
394/// This is the substrate primitive behind lock-free snapshot-isolated reads
395/// (see the `mvcc-concurrency` proposal, Direction A). Because the storage
396/// engine is **append-only** — rows are only ever appended, never moved or
397/// mutated in place — a row's *position* is stable for its whole lifetime.
398/// So a single integer, the row count at capture time, fully defines a
399/// consistent view: exactly the rows whose index is below the watermark were
400/// committed when the snapshot was taken, and every one of them is still at the
401/// same index now.
402///
403/// A `Snapshot` carries **no** per-row version metadata and no reference to any
404/// column data — it is a bare `usize`. Readers pass it to `*_at` accessors,
405/// which clamp their scan to `visible(index)`. Rows appended after capture have
406/// `index >= watermark` and are therefore invisible, so concurrent writers
407/// cannot make a reader observe a torn or partial row.
408///
409/// It is schema-agnostic substrate: it knows nothing about any `.forge` model,
410/// only about row positions. Generated code composes per-model watermarks into
411/// its own snapshot struct.
412#[derive(Debug, Clone, Copy, PartialEq, Eq)]
413pub struct Snapshot {
414    watermark: usize,
415}
416
417impl Snapshot {
418    /// Capture a snapshot at the given committed row count.
419    pub fn new(row_count: usize) -> Self {
420        Self {
421            watermark: row_count,
422        }
423    }
424
425    /// The captured row count. Rows at index `0..watermark` are visible.
426    pub fn watermark(&self) -> usize {
427        self.watermark
428    }
429
430    /// Whether the row at `index` was committed as of this snapshot.
431    pub fn visible(&self, index: usize) -> bool {
432        index < self.watermark
433    }
434}
435
436/// Fixed-size column storage backed by a seek-based file.
437///
438/// # Durability
439///
440/// Append methods write to the OS page cache but do **not** call `fsync` per append.
441/// Data written by `append_*` is immediately readable (via `read_*`) on the same or
442/// any other file descriptor to the same file, but a crash before [`flush`](FixedColumn::flush)
443/// may lose the most recent appends. Call `flush()` at commit boundaries or before
444/// advancing the WAL checkpoint.
445/// The backing of one columnar export batch — the substrate half of the
446/// language bindings' Arrow / columnar-export path.
447///
448/// A columnar export hands the caller (generated FFI glue) a single contiguous,
449/// stable-pointer byte buffer for one column at one live-row selection. This
450/// type owns that buffer through *whichever* of the two production paths
451/// produced it, behind an identical `as_ptr()` / `len()` surface so the consumer
452/// (e.g. an Arrow `ArrowArray`) is **alias-or-gather transparent**:
453///
454/// - [`ColumnExport::Mapped`] — a **zero-copy `mmap` alias** of the column
455///   file's dense prefix, taken when the live selection is exactly the
456///   contiguous prefix `[0, n)` (no updates, no tombstones). No bytes are
457///   copied; the pointer aliases the page cache directly. Because numeric
458///   columns are stored little-endian (`to_le_bytes`), the mapped prefix *is* a
459///   valid Arrow primitive buffer as-is.
460/// - [`ColumnExport::Owned`] — a gathered contiguous copy (`FixedColumn::gather`),
461///   the fallback whenever the selection is not an aliasable dense prefix
462///   (update-heavy or tombstoned tables), or is empty.
463///
464/// # Safety / aliasing invariant (`Mapped`)
465///
466/// The mapped prefix aliases live file pages, so it relies on the same
467/// single-writer, append-only discipline the reader handles already assume:
468/// prefix rows `[0, n)` are committed and immutable (appends only ever extend
469/// past `n`, never rewrite mapped bytes), and a compaction/rollback that would
470/// renumber or truncate below `n` does not run while an export is outstanding
471/// (exports are synchronous reads taken on the single writer). Under that
472/// discipline the alias observes a stable snapshot.
473pub enum ColumnExport {
474    /// A gathered / copied contiguous buffer.
475    Owned(Vec<u8>),
476    /// A zero-copy read-only `mmap` alias of the column file's dense prefix.
477    Mapped(memmap2::Mmap),
478}
479
480impl ColumnExport {
481    /// Pointer to the first byte of the exported buffer. Stable across moving
482    /// the `ColumnExport` (both a `Vec`'s heap allocation and an `Mmap`'s mapped
483    /// address are independent of where the owner struct itself lives), so the
484    /// FFI layer can capture it, then move `self` into an owner box.
485    #[must_use]
486    pub fn as_ptr(&self) -> *const u8 {
487        match self {
488            ColumnExport::Owned(v) => v.as_ptr(),
489            ColumnExport::Mapped(m) => m.as_ptr(),
490        }
491    }
492
493    /// Total exported byte length (`live_rows * value_size`).
494    #[must_use]
495    pub fn len(&self) -> usize {
496        match self {
497            ColumnExport::Owned(v) => v.len(),
498            ColumnExport::Mapped(m) => m.len(),
499        }
500    }
501
502    #[must_use]
503    pub fn is_empty(&self) -> bool {
504        self.len() == 0
505    }
506
507    /// The exported bytes as a slice.
508    #[must_use]
509    pub fn as_slice(&self) -> &[u8] {
510        match self {
511            ColumnExport::Owned(v) => v.as_slice(),
512            ColumnExport::Mapped(m) => &m[..],
513        }
514    }
515}
516
517/// An in-memory bulk-loaded selection of a [`FixedColumn`]'s rows (#168).
518///
519/// Produced by [`FixedColumn::gather_buffered`], it holds one column's selected
520/// rows as a single contiguous buffer (a zero-copy `mmap` alias of the dense
521/// prefix, or a gathered copy) and exposes the **same** positional
522/// `read_*` accessors as [`FixedColumn`], addressed by **slot** (`0..n` over the
523/// selection order) rather than physical row index.  Decoding one column of a
524/// scan from this buffer costs no syscalls; it lets the generated column scan
525/// decode with the identical per-field logic it uses for per-row reads.
526///
527/// Errors mirror [`FixedColumn`]: an out-of-range slot returns `InvalidInput`.
528pub struct BufferedFixedColumn {
529    buf: ColumnExport,
530    value_size: usize,
531}
532
533impl BufferedFixedColumn {
534    /// Number of buffered slots (`indices.len()` from the gather).
535    #[must_use]
536    pub fn len(&self) -> usize {
537        self.buf.len() / self.value_size
538    }
539
540    #[must_use]
541    pub fn is_empty(&self) -> bool {
542        self.len() == 0
543    }
544
545    /// The `value_size`-wide bytes at `slot`, or `InvalidInput` if out of range.
546    fn slot_bytes(&self, slot: usize) -> io::Result<&[u8]> {
547        let start = slot * self.value_size;
548        let end = start + self.value_size;
549        self.buf.as_slice().get(start..end).ok_or_else(|| {
550            io::Error::new(io::ErrorKind::InvalidInput, "Slot out of bounds")
551        })
552    }
553
554    pub fn read_u32(&self, slot: usize) -> io::Result<u32> {
555        let b = self.slot_bytes(slot)?;
556        Ok(u32::from_le_bytes(b[..4].try_into().unwrap()))
557    }
558
559    pub fn read_u64(&self, slot: usize) -> io::Result<u64> {
560        let b = self.slot_bytes(slot)?;
561        Ok(u64::from_le_bytes(b[..8].try_into().unwrap()))
562    }
563
564    pub fn read_i32(&self, slot: usize) -> io::Result<i32> {
565        let b = self.slot_bytes(slot)?;
566        Ok(i32::from_le_bytes(b[..4].try_into().unwrap()))
567    }
568
569    pub fn read_i64(&self, slot: usize) -> io::Result<i64> {
570        let b = self.slot_bytes(slot)?;
571        Ok(i64::from_le_bytes(b[..8].try_into().unwrap()))
572    }
573
574    pub fn read_f64(&self, slot: usize) -> io::Result<f64> {
575        let b = self.slot_bytes(slot)?;
576        Ok(f64::from_le_bytes(b[..8].try_into().unwrap()))
577    }
578
579    pub fn read_bool(&self, slot: usize) -> io::Result<bool> {
580        let b = self.slot_bytes(slot)?;
581        Ok(b[0] != 0)
582    }
583
584    pub fn read_uuid(&self, slot: usize) -> io::Result<[u8; 16]> {
585        let b = self.slot_bytes(slot)?;
586        Ok(b[..16].try_into().unwrap())
587    }
588
589    pub fn read_timestamp(&self, slot: usize) -> io::Result<i64> {
590        let b = self.slot_bytes(slot)?;
591        Ok(i64::from_le_bytes(b[..8].try_into().unwrap()))
592    }
593
594    /// The whole `value_size`-wide value at `slot` (for char(N) / struct /
595    /// fixed-array / nullable / optional-FK columns decoded via `read_unaligned`).
596    pub fn read_bytes(&self, slot: usize) -> io::Result<Vec<u8>> {
597        Ok(self.slot_bytes(slot)?.to_vec())
598    }
599
600    /// The whole `value_size`-wide slot at `slot`, **borrowed** (#238).
601    ///
602    /// The zero-copy counterpart of [`Self::read_bytes`], which is exactly this
603    /// plus a `.to_vec()`; both stay, because a caller that wants an owned buffer
604    /// should not have to write the copy itself.
605    ///
606    /// Borrowing is sound here and nowhere else on the fixed path: this type owns
607    /// its bytes (a gathered `Vec` or an `Mmap` alias of the dense prefix), so the
608    /// `&self` lifetime is the buffer's. [`FixedColumn`] and [`FixedColumnReader`]
609    /// read through the file on every access and have nothing to lend — the same
610    /// split that put [`BufferedVariableColumn::read_str`] on the buffered tier
611    /// only (#224).
612    pub fn read_slice(&self, slot: usize) -> io::Result<&[u8]> {
613        self.slot_bytes(slot)
614    }
615
616    /// The whole `value_size`-wide slot at `slot` as UTF-8, **borrowed** (#238).
617    ///
618    /// For a column where the slot *is* the value and carries no framing:
619    /// `string(N!)` (#238 res 6 — exactly N ASCII characters, therefore exactly N
620    /// bytes, therefore no length prefix), and any other fixed UTF-8 payload.
621    ///
622    /// It deliberately does **not** understand a length prefix. Which slots carry
623    /// one, and how wide it is, is #238's per-declaration layout choice; teaching
624    /// it to a schema-agnostic crate would move generated knowledge into the
625    /// substrate. Prefixed slots read through [`Self::read_slice`] and decode in
626    /// generated code.
627    ///
628    /// # Errors
629    ///
630    /// `InvalidInput` if the slot is out of range; `InvalidData` if the slot's
631    /// bytes are not valid UTF-8 — same contract as
632    /// [`BufferedVariableColumn::read_str`].
633    pub fn read_str(&self, slot: usize) -> io::Result<&str> {
634        std::str::from_utf8(self.slot_bytes(slot)?)
635            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
636    }
637}
638
639/// Selection size at or above which [`FixedColumn::gather`] maps the spanned
640/// region once and copies out of memory, instead of issuing one `read_exact_at`
641/// per index (#221).
642///
643/// Below this a handful of `pread`s beats a mapping's setup + teardown; above
644/// it the per-row syscall loop dominates completely — a 22-column scan of
645/// 10 000 live rows was 220 000 syscalls (~112 ms) before #221. Deliberately
646/// conservative rather than tuned: the point is to leave tiny gathers exactly
647/// as they were while removing the per-row syscall from bulk scans.
648const GATHER_MMAP_MIN_ROWS: usize = 8;
649
650pub struct FixedColumn {
651    file: File,
652    row_count: usize,
653    value_size: usize, // bytes per value
654}
655
656impl FixedColumn {
657    pub fn new(path: PathBuf, value_size: usize) -> io::Result<Self> {
658        // A zero value_size would divide-by-zero when deriving row_count below,
659        // and makes every offset computation meaningless.
660        if value_size == 0 {
661            return Err(io::Error::new(
662                io::ErrorKind::InvalidInput,
663                "FixedColumn value_size must be non-zero",
664            ));
665        }
666
667        // Create parent directory if needed
668        if let Some(parent) = path.parent() {
669            fs::create_dir_all(parent)?;
670        }
671
672        let file = OpenOptions::new()
673            .read(true)
674            .write(true)
675            .create(true)
676            .truncate(false)
677            .open(&path)?;
678
679        let row_count = file.metadata()?.len() as usize / value_size;
680
681        Ok(FixedColumn {
682            file,
683            row_count,
684            value_size,
685        })
686    }
687
688    pub fn append_u32(&mut self, value: u32) -> io::Result<()> {
689        self.file.seek(SeekFrom::End(0))?;
690        self.file.write_all(&value.to_le_bytes())?;
691        self.row_count += 1;
692        Ok(())
693    }
694
695    pub fn read_u32(&self, index: usize) -> io::Result<u32> {
696        if index >= self.row_count {
697            return Err(io::Error::new(
698                io::ErrorKind::InvalidInput,
699                "Index out of bounds",
700            ));
701        }
702
703        let offset = (index * self.value_size) as u64;
704        let mut buf = [0u8; 4];
705        self.file.read_exact_at(&mut buf, offset)?;
706        Ok(u32::from_le_bytes(buf))
707    }
708
709    pub fn append_u64(&mut self, value: u64) -> io::Result<()> {
710        self.file.seek(SeekFrom::End(0))?;
711        self.file.write_all(&value.to_le_bytes())?;
712        self.row_count += 1;
713        Ok(())
714    }
715
716    pub fn read_u64(&self, index: usize) -> io::Result<u64> {
717        if index >= self.row_count {
718            return Err(io::Error::new(
719                io::ErrorKind::InvalidInput,
720                "Index out of bounds",
721            ));
722        }
723
724        let offset = (index * self.value_size) as u64;
725        let mut buf = [0u8; 8];
726        self.file.read_exact_at(&mut buf, offset)?;
727        Ok(u64::from_le_bytes(buf))
728    }
729
730    pub fn append_i32(&mut self, value: i32) -> io::Result<()> {
731        self.file.seek(SeekFrom::End(0))?;
732        self.file.write_all(&value.to_le_bytes())?;
733        self.row_count += 1;
734        Ok(())
735    }
736
737    pub fn read_i32(&self, index: usize) -> io::Result<i32> {
738        if index >= self.row_count {
739            return Err(io::Error::new(
740                io::ErrorKind::InvalidInput,
741                "Index out of bounds",
742            ));
743        }
744
745        let offset = (index * self.value_size) as u64;
746        let mut buf = [0u8; 4];
747        self.file.read_exact_at(&mut buf, offset)?;
748        Ok(i32::from_le_bytes(buf))
749    }
750
751    pub fn append_i64(&mut self, value: i64) -> io::Result<()> {
752        self.file.seek(SeekFrom::End(0))?;
753        self.file.write_all(&value.to_le_bytes())?;
754        self.row_count += 1;
755        Ok(())
756    }
757
758    pub fn read_i64(&self, index: usize) -> io::Result<i64> {
759        if index >= self.row_count {
760            return Err(io::Error::new(
761                io::ErrorKind::InvalidInput,
762                "Index out of bounds",
763            ));
764        }
765
766        let offset = (index * self.value_size) as u64;
767        let mut buf = [0u8; 8];
768        self.file.read_exact_at(&mut buf, offset)?;
769        Ok(i64::from_le_bytes(buf))
770    }
771
772    pub fn append_f64(&mut self, value: f64) -> io::Result<()> {
773        self.file.seek(SeekFrom::End(0))?;
774        self.file.write_all(&value.to_le_bytes())?;
775        self.row_count += 1;
776        Ok(())
777    }
778
779    pub fn read_f64(&self, index: usize) -> io::Result<f64> {
780        if index >= self.row_count {
781            return Err(io::Error::new(
782                io::ErrorKind::InvalidInput,
783                "Index out of bounds",
784            ));
785        }
786
787        let offset = (index * self.value_size) as u64;
788        let mut buf = [0u8; 8];
789        self.file.read_exact_at(&mut buf, offset)?;
790        Ok(f64::from_le_bytes(buf))
791    }
792
793    pub fn append_bool(&mut self, value: bool) -> io::Result<()> {
794        self.file.seek(SeekFrom::End(0))?;
795        self.file.write_all(&[if value { 1u8 } else { 0u8 }])?;
796        self.row_count += 1;
797        Ok(())
798    }
799
800    pub fn read_bool(&self, index: usize) -> io::Result<bool> {
801        if index >= self.row_count {
802            return Err(io::Error::new(
803                io::ErrorKind::InvalidInput,
804                "Index out of bounds",
805            ));
806        }
807
808        let offset = (index * self.value_size) as u64;
809        let mut buf = [0u8; 1];
810        self.file.read_exact_at(&mut buf, offset)?;
811        Ok(buf[0] != 0)
812    }
813
814    pub fn append_uuid(&mut self, value: [u8; 16]) -> io::Result<()> {
815        self.file.seek(SeekFrom::End(0))?;
816        self.file.write_all(&value)?;
817        self.row_count += 1;
818        Ok(())
819    }
820
821    pub fn read_uuid(&self, index: usize) -> io::Result<[u8; 16]> {
822        if index >= self.row_count {
823            return Err(io::Error::new(
824                io::ErrorKind::InvalidInput,
825                "Index out of bounds",
826            ));
827        }
828
829        let offset = (index * self.value_size) as u64;
830        let mut buf = [0u8; 16];
831        self.file.read_exact_at(&mut buf, offset)?;
832        Ok(buf)
833    }
834
835    pub fn append_timestamp(&mut self, value: i64) -> io::Result<()> {
836        self.file.seek(SeekFrom::End(0))?;
837        self.file.write_all(&value.to_le_bytes())?;
838        self.row_count += 1;
839        Ok(())
840    }
841
842    pub fn read_timestamp(&self, index: usize) -> io::Result<i64> {
843        if index >= self.row_count {
844            return Err(io::Error::new(
845                io::ErrorKind::InvalidInput,
846                "Index out of bounds",
847            ));
848        }
849
850        let offset = (index * self.value_size) as u64;
851        let mut buf = [0u8; 8];
852        self.file.read_exact_at(&mut buf, offset)?;
853        Ok(i64::from_le_bytes(buf))
854    }
855
856    /// Append arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
857    pub fn append_bytes(&mut self, value: &[u8]) -> io::Result<()> {
858        if value.len() != self.value_size {
859            return Err(io::Error::new(
860                io::ErrorKind::InvalidInput,
861                format!("Expected {} bytes, got {}", self.value_size, value.len()),
862            ));
863        }
864
865        self.file.seek(SeekFrom::End(0))?;
866        self.file.write_all(value)?;
867        self.row_count += 1;
868        Ok(())
869    }
870
871    /// Read arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
872    pub fn read_bytes(&self, index: usize) -> io::Result<Vec<u8>> {
873        if index >= self.row_count {
874            return Err(io::Error::new(
875                io::ErrorKind::InvalidInput,
876                "Index out of bounds",
877            ));
878        }
879
880        let offset = (index * self.value_size) as u64;
881        let mut buf = vec![0u8; self.value_size];
882        self.file.read_exact_at(&mut buf, offset)?;
883        Ok(buf)
884    }
885
886    /// Copy the physical rows at `indices` into one contiguous owned buffer, in
887    /// the order given (`indices.len() * value_size` bytes).
888    ///
889    /// This is the class-1 columnar-read primitive behind the language bindings'
890    /// Arrow / columnar-export **gather** path — the fallback taken whenever the
891    /// live selection is *not* an aliasable dense prefix (update-heavy or
892    /// tombstoned tables) and a contiguous copy of exactly the live rows is
893    /// needed. It is schema-agnostic: `indices` are opaque physical row
894    /// positions the caller computed (generated code derives the live set from
895    /// `id_to_row` + tombstone liveness, exactly as `all()` / `all_at()` do
896    /// today); `gather` never reads a field name, type, or schema.
897    ///
898    /// # Performance (#221)
899    ///
900    /// For a selection of at least [`GATHER_MMAP_MIN_ROWS`] rows this maps the
901    /// spanned region `[min(indices), max(indices)]` **once** and copies out of
902    /// that mapping in contiguous runs, rather than issuing one `read_exact_at`
903    /// per index. Live selections under append-only churn are long runs broken
904    /// by the holes superseded rows leave behind, so runs are typically far
905    /// longer than one row and the copy collapses to a handful of `memcpy`s.
906    ///
907    /// The mapping is held only for the duration of the call and the returned
908    /// buffer is owned, so this relies on a strictly weaker form of the
909    /// aliasing invariant documented on [`ColumnExport`]: the spanned rows are
910    /// committed (`< row_count`, so within the file's length) and no concurrent
911    /// truncation runs, which the single-writer discipline already guarantees.
912    ///
913    /// Known-unmeasured case: a *sparse* selection spanning a very large file
914    /// faults in one page per isolated row, reading more bytes than the
915    /// per-row path would. It still trades syscalls for faults plus readahead,
916    /// and real live sets stay dense (amplification is bounded by the generated
917    /// compaction ceiling), but it has not been benchmarked.
918    ///
919    /// # Errors
920    ///
921    /// Returns `Err(InvalidInput)` if any index is `>= self.len()`.
922    pub fn gather(&self, indices: &[usize]) -> io::Result<Vec<u8>> {
923        if indices.is_empty() {
924            return Ok(Vec::new());
925        }
926
927        // Bounds-check the whole selection up front: the mapped path spans
928        // `min..=max`, so an out-of-range index has to be rejected before the
929        // span is computed (and `gather` is all-or-nothing either way).
930        let mut lo = usize::MAX;
931        let mut hi = 0usize;
932        for &index in indices {
933            if index >= self.row_count {
934                return Err(io::Error::new(
935                    io::ErrorKind::InvalidInput,
936                    "Index out of bounds",
937                ));
938            }
939            lo = lo.min(index);
940            hi = hi.max(index);
941        }
942
943        let mut out = vec![0u8; indices.len() * self.value_size];
944
945        if indices.len() >= GATHER_MMAP_MIN_ROWS {
946            let offset = (lo * self.value_size) as u64;
947            let map_len = (hi + 1 - lo) * self.value_size;
948            // A failed mapping is not fatal — the per-row loop below produces
949            // byte-identical output — so fall through instead of propagating.
950            let mapped = unsafe {
951                memmap2::MmapOptions::new()
952                    .offset(offset)
953                    .len(map_len)
954                    .map(&self.file)
955            };
956            if let Ok(mmap) = mapped {
957                let src = &mmap[..];
958                let mut slot = 0usize;
959                while slot < indices.len() {
960                    // Extend the run while the selection stays consecutive.
961                    let start = slot;
962                    while slot + 1 < indices.len() && indices[slot + 1] == indices[slot] + 1 {
963                        slot += 1;
964                    }
965                    slot += 1;
966                    let len = (slot - start) * self.value_size;
967                    let s = (indices[start] - lo) * self.value_size;
968                    let d = start * self.value_size;
969                    out[d..d + len].copy_from_slice(&src[s..s + len]);
970                }
971                return Ok(out);
972            }
973        }
974
975        for (slot, &index) in indices.iter().enumerate() {
976            let src = (index * self.value_size) as u64;
977            let dst = slot * self.value_size;
978            self.file
979                .read_exact_at(&mut out[dst..dst + self.value_size], src)?;
980        }
981        Ok(out)
982    }
983
984    /// Export the physical rows at `indices` as a [`ColumnExport`], taking the
985    /// **zero-copy `mmap` alias** fast path when `indices` is the contiguous
986    /// dense prefix `[0, n)` and falling back to [`gather`](Self::gather)
987    /// (an owned copy) otherwise. The returned buffer is identical bytes either
988    /// way (`indices.len() * value_size`), so the FFI / Arrow consumer is
989    /// alias-or-gather transparent.
990    ///
991    /// This is the class-1 columnar-read primitive the language bindings' Arrow
992    /// export links: `indices` are opaque physical row positions the caller
993    /// (generated code) computed from the live set; `export` reads no field
994    /// name, type, or schema — it only inspects the indices' shape to decide
995    /// whether they alias a prefix.
996    ///
997    /// # Errors
998    ///
999    /// Returns `Err(InvalidInput)` if any index is `>= self.len()`, or an I/O
1000    /// error if the `mmap` of the aliasable prefix fails.
1001    pub fn export(&self, indices: &[usize]) -> io::Result<ColumnExport> {
1002        let n = indices.len();
1003        // A dense prefix is `indices == [0, 1, ..., n-1]`, entirely within the
1004        // committed rows. Empty selections take the trivial owned path.
1005        let is_dense_prefix =
1006            n > 0 && n <= self.row_count && indices.iter().enumerate().all(|(i, &x)| x == i);
1007
1008        if is_dense_prefix {
1009            // Alias exactly the first `n * value_size` bytes of the column file
1010            // — no copy. Safe under the single-writer/append-only invariant
1011            // documented on `ColumnExport`.
1012            let map_len = n * self.value_size;
1013            let mmap = unsafe { memmap2::MmapOptions::new().len(map_len).map(&self.file)? };
1014            return Ok(ColumnExport::Mapped(mmap));
1015        }
1016
1017        Ok(ColumnExport::Owned(self.gather(indices)?))
1018    }
1019
1020    /// Bulk-load the physical rows at `indices` into an in-memory
1021    /// [`BufferedFixedColumn`] whose positional `read_*(slot)` accessors read
1022    /// from memory instead of the file (#168 column scan).
1023    ///
1024    /// This is the class-1 read primitive behind the generated column-pruned
1025    /// sequential scan: a scan over `n` rows pays **one** bulk read per column
1026    /// (a zero-copy `mmap` alias when `indices` is the dense prefix `[0, n)` — the
1027    /// common append-only case — or a single gathered copy otherwise) rather than
1028    /// `n` per-row `read_exact_at` syscalls.  `indices` are opaque physical row
1029    /// positions the caller (generated code) computed from the live set; the
1030    /// returned buffer's `read_*` methods take a **slot** `0..indices.len()`
1031    /// indexing into that selection, in the given order.  Reads no field name,
1032    /// type, or schema.
1033    ///
1034    /// # Errors
1035    ///
1036    /// Propagates [`export`](Self::export)'s errors (out-of-bounds index or a
1037    /// failed `mmap`).
1038    pub fn gather_buffered(&self, indices: &[usize]) -> io::Result<BufferedFixedColumn> {
1039        Ok(BufferedFixedColumn {
1040            buf: self.export(indices)?,
1041            value_size: self.value_size,
1042        })
1043    }
1044
1045    /// Flush all pending writes to disk (fsync).
1046    ///
1047    /// This is the explicit durability checkpoint: after `flush()` returns `Ok(())`,
1048    /// all previous appends are guaranteed to survive a crash. Call this at transaction
1049    /// commit boundaries or before advancing the WAL checkpoint.
1050    pub fn flush(&mut self) -> io::Result<()> {
1051        self.file.sync_all()
1052    }
1053
1054    /// Push this column's data to the drive cache **without** a device barrier
1055    /// (#153).  Pair with a single [`FixedColumn::barrier`] (on any column of the
1056    /// same device) to make a whole checkpoint's columns durable with ONE
1057    /// barrier instead of N.  See [`fsync_to_drive`].
1058    pub fn sync_to_drive(&self) -> io::Result<()> {
1059        fsync_to_drive(&self.file)
1060    }
1061
1062    /// Issue the single device-cache barrier for a checkpoint (#153): flushes the
1063    /// drive's write cache to permanent media, making durable every column
1064    /// previously `sync_to_drive`d on the same device.  See [`device_barrier`].
1065    pub fn barrier(&self) -> io::Result<()> {
1066        device_barrier(&self.file)
1067    }
1068
1069    #[must_use]
1070    pub fn len(&self) -> usize {
1071        self.row_count
1072    }
1073
1074    #[must_use]
1075    pub fn is_empty(&self) -> bool {
1076        self.row_count == 0
1077    }
1078
1079    /// Refresh the in-memory `row_count` from the on-disk file length (#84).
1080    ///
1081    /// Reads `read_exact_at` the file positionally, bounded by `row_count`.  For
1082    /// the Tier 3 multi-process writer path a *peer* process may have appended
1083    /// values since this handle opened; `sync_from_disk` re-derives `row_count`
1084    /// from the shared file so the peer's committed rows become readable (paired
1085    /// with `Tombstones::sync_from_disk` and `VariableColumn::sync_from_disk`).
1086    /// A no-op for the single-writer path, which maintains `row_count` in memory.
1087    pub fn sync_from_disk(&mut self) -> io::Result<()> {
1088        self.row_count = self.file.metadata()?.len() as usize / self.value_size;
1089        Ok(())
1090    }
1091
1092    /// Truncate the column to hold exactly `rows` rows, discarding everything
1093    /// after that point.
1094    ///
1095    /// This is the crash-recovery primitive: after replaying a WAL, generated
1096    /// code calls `truncate_to_rows` on every column to realign them back to the
1097    /// last consistent row watermark before resuming appends.  Any partial
1098    /// trailing value left by a torn write is physically removed so the next
1099    /// `append_*` lands at exactly row `rows`.
1100    ///
1101    /// # Errors
1102    ///
1103    /// Returns `Err(InvalidInput)` if `rows > self.len()` — truncation cannot
1104    /// extend a column.  All other errors come from the underlying `set_len`
1105    /// syscall.
1106    pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1107        if rows > self.row_count {
1108            return Err(io::Error::new(
1109                io::ErrorKind::InvalidInput,
1110                "truncate_to_rows beyond current length",
1111            ));
1112        }
1113        self.file.set_len((rows * self.value_size) as u64)?;
1114        self.row_count = rows;
1115        Ok(())
1116    }
1117
1118    /// Open a read-only, positionally-reading view over this column's file
1119    /// (#56 Direction B).  The returned [`FixedColumnReader`] shares the file
1120    /// via an independent (`try_clone`d) descriptor, so a single `&mut self`
1121    /// writer can keep appending while many `&self` readers read concurrently
1122    /// without a lock.  See [`FixedColumnReader`] for the full model.
1123    pub fn reader(&self) -> io::Result<FixedColumnReader> {
1124        Ok(FixedColumnReader {
1125            file: self.file.try_clone()?,
1126            value_size: self.value_size,
1127        })
1128    }
1129}
1130
1131/// An in-memory bulk-loaded selection of a [`VariableColumn`]'s rows (#168).
1132///
1133/// Produced by [`VariableColumn::gather_buffered`]; holds the column's data
1134/// bytes plus each selected slot's `(absolute offset, length)` so `read_string`
1135/// slices from memory without a syscall.  The variable-column peer of
1136/// [`BufferedFixedColumn`]: same `read_string` name as [`VariableColumn`],
1137/// addressed by **slot** (`0..n` over the selection order).
1138pub struct BufferedVariableColumn {
1139    /// The spanned data region — a lazily-paged `mmap` alias when it is large
1140    /// enough to be worth mapping, an owned copy otherwise (#222).
1141    data: ColumnExport,
1142    /// File offset `data` starts at, so the absolute offsets in `slots` can be
1143    /// rebased onto it. Zero when the whole region is buffered, and zero on the
1144    /// sparse path (#228), where `data` is packed and `slots` already index into it.
1145    base: u64,
1146    // (offset, byte length) per slot, in selection order. The offset is absolute in
1147    // the data FILE on the spanned path and relative to `data` on the packed sparse
1148    // path — `base` is what reconciles them, so `read_str` needs no branch.
1149    slots: Vec<(u64, u64)>,
1150}
1151
1152impl BufferedVariableColumn {
1153    #[must_use]
1154    pub fn len(&self) -> usize {
1155        self.slots.len()
1156    }
1157
1158    #[must_use]
1159    pub fn is_empty(&self) -> bool {
1160        self.slots.is_empty()
1161    }
1162
1163    /// The slot's value **borrowed from the buffered span** — no allocation, no
1164    /// copy (#224).
1165    ///
1166    /// #222 made the span an `mmap` alias of the data region, so a scan already
1167    /// holds every live string's bytes; this is the read that stops copying them
1168    /// back out. The borrow is tied to `&self` and the mapping is owned by `self`,
1169    /// so the compiler guarantees the `&str` cannot outlive the pages it points at
1170    /// — a *tighter* constraint than the type already operates under, not a new
1171    /// aliasing exposure.
1172    ///
1173    /// UTF-8 is validated on every read (cheap next to the allocation it replaces)
1174    /// so an on-disk corruption surfaces as [`io::ErrorKind::InvalidData`] rather
1175    /// than as an unchecked `&str`.
1176    pub fn read_str(&self, slot: usize) -> io::Result<&str> {
1177        let &(offset, length) = self.slots.get(slot).ok_or_else(|| {
1178            io::Error::new(io::ErrorKind::InvalidInput, "Slot out of bounds")
1179        })?;
1180        // Slots carry absolute file offsets; `base` is where the buffered span
1181        // starts. Touching a mapped page here is what pulls it in — dead versions
1182        // between live rows are never addressed, so they are never read.
1183        let start = offset.saturating_sub(self.base) as usize;
1184        let end = start + length as usize;
1185        let bytes = self.data.as_slice().get(start..end).ok_or_else(|| {
1186            io::Error::new(io::ErrorKind::InvalidData, "Variable slot out of data bounds")
1187        })?;
1188        std::str::from_utf8(bytes).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1189    }
1190
1191    /// The slot's value as an owned `String`. Kept for callers that genuinely need
1192    /// ownership; it is [`read_str`](Self::read_str) plus the copy, so there is one
1193    /// decode path and the two can never disagree.
1194    pub fn read_string(&self, slot: usize) -> io::Result<String> {
1195        self.read_str(slot).map(str::to_owned)
1196    }
1197}
1198
1199/// Variable-length column storage (for strings).
1200///
1201/// Stores data in an append-only data file plus a separate offset index file.
1202///
1203/// # Durability
1204///
1205/// Append methods write to the OS page cache but do **not** call `fsync` per append.
1206/// Call [`flush`](VariableColumn::flush) at commit boundaries to guarantee durability.
1207/// Spanned-data-region size at or above which [`VariableColumn::gather_buffered`]
1208/// maps rather than reads (#222).
1209///
1210/// Below this the span is small enough that a single bounded read costs less than a
1211/// mapping's setup and teardown; above it, mapping is what keeps dead versions inside
1212/// the span from being paid for — untouched pages are never faulted in. Conservative
1213/// rather than tuned; the shape of the win does not depend on the exact crossover.
1214const VAR_MMAP_MIN_BYTES: usize = 64 * 1024;
1215
1216/// Selection sparsity at which [`VariableColumn::gather_buffered`] reads each
1217/// offsets entry on its own instead of the whole spanned slice (#228).
1218///
1219/// The spanned read is one syscall for `span_rows * 16` bytes; the per-index read
1220/// is `n` syscalls of 16 bytes. The former wins while the selection is dense, and
1221/// loses badly once it is not: a two-row selection at opposite ends of a 20 000-row
1222/// column read 320 KB of offsets per column to use 32 bytes of it.
1223///
1224/// That shape is not hypothetical — it is what an index-pushdown candidate set
1225/// looks like. Since #228 unified the pushdown arm on the buffered scan, a handful
1226/// of scattered candidates reach here directly, and before this branch existed the
1227/// pushdown measured **5x slower** than the per-row positional decode it replaced.
1228///
1229/// The crossover is where `n` syscalls cost what the spanned read costs, which on
1230/// a warm page cache lands near `span_rows ≈ 190n`. `128` sits just under that:
1231/// conservative toward the spanned read (better locality, and it is the path the
1232/// dense common case takes), while still catching every sparse case by a wide
1233/// margin. The exact value is not load-bearing — the two costs differ by orders of
1234/// magnitude on either side of it, not by a few percent.
1235const SPARSE_OFFSETS_SPAN_FACTOR: usize = 128;
1236
1237pub struct VariableColumn {
1238    data_file: File,
1239    offsets_file: File,
1240    row_count: usize,
1241    current_data_offset: u64,
1242}
1243
1244impl VariableColumn {
1245    pub fn new(data_path: PathBuf, offsets_path: PathBuf) -> io::Result<Self> {
1246        // Create parent directories
1247        if let Some(parent) = data_path.parent() {
1248            fs::create_dir_all(parent)?;
1249        }
1250
1251        let data_file = OpenOptions::new()
1252            .read(true)
1253            .write(true)
1254            .create(true)
1255            .truncate(false)
1256            .open(&data_path)?;
1257
1258        let offsets_file = OpenOptions::new()
1259            .read(true)
1260            .write(true)
1261            .create(true)
1262            .truncate(false)
1263            .open(&offsets_path)?;
1264
1265        let current_data_offset = data_file.metadata()?.len();
1266        let row_count = offsets_file.metadata()?.len() as usize / 16; // 16 bytes per (offset, length)
1267
1268        Ok(VariableColumn {
1269            data_file,
1270            offsets_file,
1271            row_count,
1272            current_data_offset,
1273        })
1274    }
1275
1276    pub fn append_string(&mut self, value: &str) -> io::Result<()> {
1277        let bytes = value.as_bytes();
1278        let length = bytes.len() as u64;
1279
1280        // Write data to data file
1281        self.data_file.seek(SeekFrom::End(0))?;
1282        self.data_file.write_all(bytes)?;
1283
1284        // Write (offset, length) to offsets file
1285        self.offsets_file.seek(SeekFrom::End(0))?;
1286        self.offsets_file
1287            .write_all(&self.current_data_offset.to_le_bytes())?;
1288        self.offsets_file.write_all(&length.to_le_bytes())?;
1289
1290        self.current_data_offset += length;
1291        self.row_count += 1;
1292
1293        Ok(())
1294    }
1295
1296    /// Append a single tag byte followed by `value`'s bytes, as one row (#231).
1297    ///
1298    /// Exactly equivalent to `append_string(&format!("{tag_char}{value}"))` for any
1299    /// `tag` that is a valid single-byte UTF-8 scalar, but without materializing
1300    /// the concatenation: the tag and the value are written from their own slices
1301    /// in one vectored write, so a tagged append costs no allocation and no copy
1302    /// of the value.
1303    ///
1304    /// This is the write-side sibling of [`BufferedVariableColumn::read_str`]
1305    /// (#224) and it is schema-agnostic in exactly the same way — it knows nothing
1306    /// about what the tag *means*. Generated code uses it for the 1-byte presence
1307    /// tag on nullable `string`/`json` columns (`0x00` = None, `0x01` = Some), but
1308    /// the column stores opaque bytes either way.
1309    ///
1310    /// # Note on UTF-8
1311    ///
1312    /// The stored row is only valid UTF-8 — and so only readable by
1313    /// [`read_string`](VariableColumn::read_string) — when `tag < 0x80`. Tags at or
1314    /// above `0x80` produce a leading continuation/lead byte with nothing to
1315    /// complete it. The column itself is byte-oriented and will store them
1316    /// faithfully; it is the caller's job to keep tags in the ASCII range if the
1317    /// row must round-trip as a `String`.
1318    pub fn append_tagged(&mut self, tag: u8, value: &str) -> io::Result<()> {
1319        let bytes = value.as_bytes();
1320        let length = bytes.len() as u64 + 1;
1321
1322        self.data_file.seek(SeekFrom::End(0))?;
1323        let tag = [tag];
1324        let mut slices = [IoSlice::new(&tag), IoSlice::new(bytes)];
1325        let mut slices: &mut [IoSlice<'_>] = &mut slices;
1326        while !slices.is_empty() {
1327            let written = self.data_file.write_vectored(slices)?;
1328            if written == 0 {
1329                return Err(io::Error::new(
1330                    io::ErrorKind::WriteZero,
1331                    "failed to write whole tagged value",
1332                ));
1333            }
1334            IoSlice::advance_slices(&mut slices, written);
1335        }
1336
1337        // One 16-byte write rather than two, matching the (offset, length) pair
1338        // layout `append_string` produces.
1339        let mut entry = [0u8; 16];
1340        entry[..8].copy_from_slice(&self.current_data_offset.to_le_bytes());
1341        entry[8..].copy_from_slice(&length.to_le_bytes());
1342        self.offsets_file.seek(SeekFrom::End(0))?;
1343        self.offsets_file.write_all(&entry)?;
1344
1345        self.current_data_offset += length;
1346        self.row_count += 1;
1347
1348        Ok(())
1349    }
1350
1351    pub fn read_string(&self, index: usize) -> io::Result<String> {
1352        if index >= self.row_count {
1353            return Err(io::Error::new(
1354                io::ErrorKind::InvalidInput,
1355                "Index out of bounds",
1356            ));
1357        }
1358
1359        // Read offset and length from offsets file using positional I/O
1360        let offsets_pos = (index * 16) as u64;
1361        let mut offset_buf = [0u8; 8];
1362        let mut length_buf = [0u8; 8];
1363        self.offsets_file.read_exact_at(&mut offset_buf, offsets_pos)?;
1364        self.offsets_file
1365            .read_exact_at(&mut length_buf, offsets_pos + 8)?;
1366
1367        let offset = u64::from_le_bytes(offset_buf);
1368        let length = u64::from_le_bytes(length_buf);
1369
1370        // Read data from data file using positional I/O
1371        let mut data = vec![0u8; length as usize];
1372        self.data_file.read_exact_at(&mut data, offset)?;
1373
1374        String::from_utf8(data).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1375    }
1376
1377    /// Bulk-load the rows at `indices` into an in-memory
1378    /// [`BufferedVariableColumn`] whose `read_string(slot)` reads from memory
1379    /// (#168 column scan).
1380    ///
1381    /// Reads only the **spanned** slice of the offsets index and maps only the
1382    /// **spanned** data region, so a scan over `n` variable rows pays one bounded
1383    /// read plus one mapping rather than `3n` per-row `read_exact_at` syscalls
1384    /// (offset + length + data). `indices` are opaque physical row positions;
1385    /// reads no schema.
1386    ///
1387    /// # Performance (#222)
1388    ///
1389    /// This used to read the **entire** committed offsets index and the **entire**
1390    /// data region into owned buffers on every call, ignoring `indices` — dead
1391    /// versions included. That made a scan cost `~A x live_bytes`, a slope in
1392    /// amplification rather than the fixed columns' step, and it was measured as
1393    /// exactly that: at 2 000 live rows the narrow scan went 563 µs -> 5.8 ms
1394    /// across A = 1 -> 16, doubling with each doubling of A.
1395    ///
1396    /// Both reads are now bounded to `[min(indices), max(indices)]`. Append order
1397    /// makes data offsets monotonic in row index, so that row span maps to one
1398    /// contiguous byte span. The data span is **mapped** rather than read when it
1399    /// is large enough to be worth it, which is what removes the slope: dead
1400    /// versions inside the span cost address space, not I/O, because only pages
1401    /// actually addressed by `read_string` are ever faulted in.
1402    ///
1403    /// The residual cost is page granularity — a live row drags in its whole page,
1404    /// including any dead bytes sharing it — so the win depends on how clustered
1405    /// the live set is. Append-only helps here: an updated row is re-appended at
1406    /// the tail, so churn tends to concentrate live rows rather than scatter them.
1407    ///
1408    /// # Sparse selections (#228)
1409    ///
1410    /// Bounding to the span is the wrong trade when the selection is a handful of
1411    /// rows scattered across the column — the offsets read is then almost entirely
1412    /// rows nobody asked for. Below [`SPARSE_OFFSETS_SPAN_FACTOR`] density the
1413    /// offsets are read per index instead. This mirrors what
1414    /// [`FixedColumn::gather`] already does via `GATHER_MMAP_MIN_ROWS`; the data
1415    /// region still maps by span, which costs address space rather than I/O.
1416    ///
1417    /// # Errors
1418    ///
1419    /// `InvalidInput` if any index is `>= self.len()`; other errors come from the
1420    /// underlying reads.
1421    pub fn gather_buffered(&self, indices: &[usize]) -> io::Result<BufferedVariableColumn> {
1422        if indices.is_empty() {
1423            return Ok(BufferedVariableColumn {
1424                data: ColumnExport::Owned(Vec::new()),
1425                base: 0,
1426                slots: Vec::new(),
1427            });
1428        }
1429
1430        // Bounds-check the whole selection first, and take the row span.
1431        let mut lo = usize::MAX;
1432        let mut hi = 0usize;
1433        for &index in indices {
1434            if index >= self.row_count {
1435                return Err(io::Error::new(
1436                    io::ErrorKind::InvalidInput,
1437                    "Index out of bounds",
1438                ));
1439            }
1440            lo = lo.min(index);
1441            hi = hi.max(index);
1442        }
1443
1444        // A few rows scattered across the column: bounding to the span would read
1445        // almost entirely rows nobody asked for, and map a data region orders of
1446        // magnitude larger than the bytes wanted.  Gather them individually
1447        // instead (#228 — see `SPARSE_OFFSETS_SPAN_FACTOR`).
1448        if hi + 1 - lo > indices.len().saturating_mul(SPARSE_OFFSETS_SPAN_FACTOR) {
1449            return self.gather_sparse(indices);
1450        }
1451
1452        // Only the spanned slice of the offsets index (16 bytes/row), not all
1453        // `row_count` rows.
1454        let mut offsets = vec![0u8; (hi + 1 - lo) * 16];
1455        self.offsets_file
1456            .read_exact_at(&mut offsets, (lo * 16) as u64)?;
1457
1458        let mut slots = Vec::with_capacity(indices.len());
1459        let mut data_lo = u64::MAX;
1460        let mut data_hi = 0u64;
1461        for &index in indices {
1462            let b = (index - lo) * 16;
1463            let offset = u64::from_le_bytes(offsets[b..b + 8].try_into().unwrap());
1464            let length = u64::from_le_bytes(offsets[b + 8..b + 16].try_into().unwrap());
1465            data_lo = data_lo.min(offset);
1466            data_hi = data_hi.max(offset + length);
1467            slots.push((offset, length));
1468        }
1469
1470        // Every selected row empty (or a zero-length span) — nothing to map.
1471        if data_hi <= data_lo {
1472            return Ok(BufferedVariableColumn {
1473                data: ColumnExport::Owned(Vec::new()),
1474                base: data_lo.min(data_hi),
1475                slots,
1476            });
1477        }
1478
1479        let span = (data_hi - data_lo) as usize;
1480        let data = if span >= VAR_MMAP_MIN_BYTES {
1481            // A failed mapping is not fatal — the bounded read below yields the
1482            // same bytes — so fall through rather than propagate.
1483            let mapped = unsafe {
1484                memmap2::MmapOptions::new()
1485                    .offset(data_lo)
1486                    .len(span)
1487                    .map(&self.data_file)
1488            };
1489            match mapped {
1490                Ok(m) => ColumnExport::Mapped(m),
1491                Err(_) => {
1492                    let mut v = vec![0u8; span];
1493                    self.data_file.read_exact_at(&mut v, data_lo)?;
1494                    ColumnExport::Owned(v)
1495                }
1496            }
1497        } else {
1498            let mut v = vec![0u8; span];
1499            self.data_file.read_exact_at(&mut v, data_lo)?;
1500            ColumnExport::Owned(v)
1501        };
1502
1503        Ok(BufferedVariableColumn { data, base: data_lo, slots })
1504    }
1505
1506    /// The sparse-selection arm of [`gather_buffered`](Self::gather_buffered)
1507    /// (#228): read each selected row's offsets entry and bytes individually, into
1508    /// one **packed** buffer holding only the rows asked for.
1509    ///
1510    /// The spanned arm is the right shape when the selection covers most of its
1511    /// span — one bounded offsets read, and a data region whose dead versions cost
1512    /// address space rather than I/O because only addressed pages fault in. It is
1513    /// the wrong shape when a handful of rows are scattered across the whole
1514    /// column: the offsets read is then almost all rows nobody wants, and the
1515    /// mapping's setup and teardown are paid in full to reach a few hundred bytes.
1516    ///
1517    /// That case is not hypothetical — it is what an index-pushdown candidate set
1518    /// looks like, and since #228 those reach here directly instead of being
1519    /// decoded per row. Measured on a 20 000-row column, two rows at opposite ends
1520    /// cost 5x the per-row positional decode this replaced; packing them brings it
1521    /// back to parity, while every denser selection keeps the spanned arm's win.
1522    ///
1523    /// The packed buffer means `slots` here hold **offsets into `data`**, not
1524    /// absolute file offsets, with `base` 0 — the one place that distinction
1525    /// exists. `read_str` computes `offset - base` either way, so it needs no
1526    /// branch and cannot tell the two apart.
1527    fn gather_sparse(&self, indices: &[usize]) -> io::Result<BufferedVariableColumn> {
1528        let mut slots = Vec::with_capacity(indices.len());
1529        let mut data: Vec<u8> = Vec::new();
1530        let mut entry = [0u8; 16];
1531        for &index in indices {
1532            self.offsets_file
1533                .read_exact_at(&mut entry, (index * 16) as u64)?;
1534            let offset = u64::from_le_bytes(entry[..8].try_into().unwrap());
1535            let length = u64::from_le_bytes(entry[8..].try_into().unwrap());
1536            let start = data.len();
1537            data.resize(start + length as usize, 0);
1538            if length > 0 {
1539                self.data_file.read_exact_at(&mut data[start..], offset)?;
1540            }
1541            slots.push((start as u64, length));
1542        }
1543        Ok(BufferedVariableColumn {
1544            data: ColumnExport::Owned(data),
1545            base: 0,
1546            slots,
1547        })
1548    }
1549
1550    /// Flush all pending writes to disk (fsync both data and offsets files).
1551    ///
1552    /// After `flush()` returns `Ok(())`, all previous appends are guaranteed to
1553    /// survive a crash. Call at commit boundaries or before advancing the WAL checkpoint.
1554    pub fn flush(&mut self) -> io::Result<()> {
1555        self.data_file.sync_all()?;
1556        self.offsets_file.sync_all()
1557    }
1558
1559    /// Push both backing files to the drive cache without a device barrier
1560    /// (#153).  Pair with one [`VariableColumn::barrier`] per checkpoint.
1561    pub fn sync_to_drive(&self) -> io::Result<()> {
1562        fsync_to_drive(&self.data_file)?;
1563        fsync_to_drive(&self.offsets_file)
1564    }
1565
1566    /// Issue the single device-cache barrier for a checkpoint (#153).  Barriers
1567    /// are device-wide, so one call on the data file covers the offsets file too.
1568    pub fn barrier(&self) -> io::Result<()> {
1569        device_barrier(&self.data_file)
1570    }
1571
1572    #[must_use]
1573    pub fn len(&self) -> usize {
1574        self.row_count
1575    }
1576
1577    #[must_use]
1578    pub fn is_empty(&self) -> bool {
1579        self.row_count == 0
1580    }
1581
1582    /// Refresh the in-memory counters from the on-disk file lengths (#84).
1583    ///
1584    /// Re-derives `row_count` from the offsets file (16 bytes/row) and
1585    /// `current_data_offset` from the data file, so a *peer* process's appended
1586    /// rows (Tier 3 multi-process writer path) become readable through this
1587    /// handle.  Paired with `FixedColumn::sync_from_disk` /
1588    /// `Tombstones::sync_from_disk`.  A no-op for the single-writer path.
1589    pub fn sync_from_disk(&mut self) -> io::Result<()> {
1590        self.row_count = self.offsets_file.metadata()?.len() as usize / 16;
1591        self.current_data_offset = self.data_file.metadata()?.len();
1592        Ok(())
1593    }
1594
1595    /// Truncate the column to hold exactly `rows` rows, discarding everything
1596    /// after that point.
1597    ///
1598    /// The data file is cut at the byte immediately after the last byte of row
1599    /// `rows - 1` (read from the offsets entry for that row).  The offsets file
1600    /// is cut to `rows * 16` bytes.  Both in-memory counters are updated so the
1601    /// next `append_string` lands at exactly row `rows`.
1602    ///
1603    /// # Errors
1604    ///
1605    /// Returns `Err(InvalidInput)` if `rows > self.len()`.  All other errors
1606    /// come from underlying I/O or `set_len` syscalls.
1607    pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1608        if rows > self.row_count {
1609            return Err(io::Error::new(
1610                io::ErrorKind::InvalidInput,
1611                "truncate_to_rows beyond current length",
1612            ));
1613        }
1614
1615        let data_len: u64 = if rows == 0 {
1616            0
1617        } else {
1618            // Positionally read the (offset, length) pair for row `rows - 1`.
1619            let offsets_pos = ((rows - 1) * 16) as u64;
1620            let mut offset_buf = [0u8; 8];
1621            let mut length_buf = [0u8; 8];
1622            self.offsets_file
1623                .read_exact_at(&mut offset_buf, offsets_pos)?;
1624            self.offsets_file
1625                .read_exact_at(&mut length_buf, offsets_pos + 8)?;
1626            let offset = u64::from_le_bytes(offset_buf);
1627            let length = u64::from_le_bytes(length_buf);
1628            offset + length
1629        };
1630
1631        self.offsets_file.set_len((rows * 16) as u64)?;
1632        self.data_file.set_len(data_len)?;
1633        self.current_data_offset = data_len;
1634        self.row_count = rows;
1635        Ok(())
1636    }
1637
1638    /// Open a read-only, positionally-reading view over this column's data +
1639    /// offsets files (#56 Direction B).  The returned [`VariableColumnReader`]
1640    /// shares both files via independent (`try_clone`d) descriptors, so a single
1641    /// `&mut self` writer can keep appending while many `&self` readers read
1642    /// concurrently without a lock.  See [`FixedColumnReader`] for the model.
1643    pub fn reader(&self) -> io::Result<VariableColumnReader> {
1644        Ok(VariableColumnReader {
1645            data_file: self.data_file.try_clone()?,
1646            offsets_file: self.offsets_file.try_clone()?,
1647        })
1648    }
1649}
1650
1651/// Tombstone bitmap for tracking deleted records.
1652///
1653/// # Durability
1654///
1655/// Append methods write to the OS page cache but do **not** call `fsync` per append.
1656/// Call [`flush`](Tombstones::flush) at commit boundaries to guarantee durability.
1657pub struct Tombstones {
1658    file: File,
1659    count: usize,
1660}
1661
1662impl Tombstones {
1663    pub fn new(path: PathBuf) -> io::Result<Self> {
1664        if let Some(parent) = path.parent() {
1665            fs::create_dir_all(parent)?;
1666        }
1667
1668        let file = OpenOptions::new()
1669            .read(true)
1670            .write(true)
1671            .create(true)
1672            .truncate(false)
1673            .open(&path)?;
1674
1675        let count = file.metadata()?.len() as usize;
1676
1677        Ok(Tombstones { file, count })
1678    }
1679
1680    pub fn append(&mut self, deleted: bool) -> io::Result<()> {
1681        self.file.seek(SeekFrom::End(0))?;
1682        self.file.write_all(&[if deleted { 1u8 } else { 0u8 }])?;
1683        self.count += 1;
1684        Ok(())
1685    }
1686
1687    pub fn is_deleted(&self, index: usize) -> io::Result<bool> {
1688        if index >= self.count {
1689            return Err(io::Error::new(
1690                io::ErrorKind::InvalidInput,
1691                "Index out of bounds",
1692            ));
1693        }
1694
1695        let mut buf = [0u8; 1];
1696        self.file.read_exact_at(&mut buf, index as u64)?;
1697        Ok(buf[0] != 0)
1698    }
1699
1700    /// Return the subset of `rows` that are **not** tombstoned, preserving order
1701    /// (#168 scan filter).  Reads the whole tombstone column **once** rather than
1702    /// a per-row [`is_deleted`](Self::is_deleted) syscall — the bulk liveness
1703    /// filter a column scan applies to its live-row selection.  A row index past
1704    /// the committed count is treated as not-live (dropped), matching
1705    /// `is_deleted(..).unwrap_or(true)`.
1706    pub fn live_indices(&self, rows: &[usize]) -> io::Result<Vec<usize>> {
1707        let mut bytes = vec![0u8; self.count];
1708        if !bytes.is_empty() {
1709            self.file.read_exact_at(&mut bytes, 0)?;
1710        }
1711        Ok(rows
1712            .iter()
1713            .copied()
1714            .filter(|&r| bytes.get(r) == Some(&0))
1715            .collect())
1716    }
1717
1718    /// Flush all pending writes to disk (fsync).
1719    ///
1720    /// After `flush()` returns `Ok(())`, all previous appends are guaranteed to
1721    /// survive a crash. Call at commit boundaries or before advancing the WAL checkpoint.
1722    pub fn flush(&mut self) -> io::Result<()> {
1723        self.file.sync_all()
1724    }
1725
1726    /// Push the tombstone column to the drive cache without a barrier (#153).
1727    pub fn sync_to_drive(&self) -> io::Result<()> {
1728        fsync_to_drive(&self.file)
1729    }
1730
1731    /// Issue the single device-cache barrier for a checkpoint (#153).
1732    pub fn barrier(&self) -> io::Result<()> {
1733        device_barrier(&self.file)
1734    }
1735
1736    #[must_use]
1737    pub fn len(&self) -> usize {
1738        self.count
1739    }
1740
1741    #[must_use]
1742    pub fn is_empty(&self) -> bool {
1743        self.count == 0
1744    }
1745
1746    /// Truncate the tombstone bitmap to hold exactly `rows` rows, discarding
1747    /// everything after that point.
1748    ///
1749    /// # Errors
1750    ///
1751    /// Returns `Err(InvalidInput)` if `rows > self.len()`.  All other errors
1752    /// come from the underlying `set_len` syscall.
1753    pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1754        if rows > self.count {
1755            return Err(io::Error::new(
1756                io::ErrorKind::InvalidInput,
1757                "truncate_to_rows beyond current length",
1758            ));
1759        }
1760        self.file.set_len(rows as u64)?;
1761        self.count = rows;
1762        Ok(())
1763    }
1764
1765    /// Re-read the on-disk tombstone count from the file metadata and update the
1766    /// cached `count`.
1767    ///
1768    /// Normally `count` is maintained in memory by `append`/`truncate_to_rows`, so
1769    /// this is a no-op for the single-writer path.  For the Tier 3 multi-process
1770    /// writer path (#84) a peer process may have appended tombstone bytes since this
1771    /// writer opened the file; calling `sync_from_disk` before `len()` lets the
1772    /// writer see the peer's committed rows without reopening the storage.
1773    ///
1774    /// # Errors
1775    ///
1776    /// Propagates any error from `file.metadata()`.
1777    pub fn sync_from_disk(&mut self) -> io::Result<()> {
1778        self.count = self.file.metadata()?.len() as usize;
1779        Ok(())
1780    }
1781
1782    /// Open a read-only, positionally-reading view over this tombstone file
1783    /// (#56 Direction B).  See [`FixedColumn::reader`] for the concurrency model.
1784    pub fn reader(&self) -> io::Result<TombstonesReader> {
1785        Ok(TombstonesReader {
1786            file: self.file.try_clone()?,
1787        })
1788    }
1789}
1790
1791/// Map a positional read that ran past end-of-file back to the same
1792/// out-of-bounds error the cached-count writer columns return (#56 Direction B).
1793///
1794/// A [`FixedColumnReader`] / [`VariableColumnReader`] / [`TombstonesReader`]
1795/// derives length live rather than caching a row count, so an index beyond the
1796/// committed prefix surfaces as `UnexpectedEof` from `read_exact_at`; normalize
1797/// it to `InvalidInput` for parity with the writer's explicit bound check.
1798fn map_out_of_bounds(e: io::Error) -> io::Error {
1799    if e.kind() == io::ErrorKind::UnexpectedEof {
1800        io::Error::new(io::ErrorKind::InvalidInput, "Index out of bounds")
1801    } else {
1802        e
1803    }
1804}
1805
1806/// Read-only, positional view over a [`FixedColumn`]'s backing file
1807/// (#56 Direction B — single writer, many concurrent readers).
1808///
1809/// Created by [`FixedColumn::reader`]; holds an independent file descriptor
1810/// (`try_clone`) to the **same** file as the writer.  A single `&mut self`
1811/// writer can keep appending while any number of `&self` readers positionally
1812/// read the committed prefix concurrently, with no lock:
1813///
1814/// - Reads use `read_exact_at` (positional `pread`) — they never touch a shared
1815///   file cursor, so they are safe against a concurrent seek-based append and
1816///   against each other across threads.
1817/// - The engine is append-only: bytes at an already-committed offset never move,
1818///   so a reader observing an offset below the writer's committed length reads
1819///   stable bytes (POSIX page-cache coherence makes the writer's not-yet-fsync'd
1820///   appends visible through this independent fd).
1821/// - Length is derived **live** on every access (never a cached count), so a
1822///   reader created before an append still sees rows the writer commits
1823///   afterward — once the caller's watermark admits them.
1824///
1825/// Callers clamp reads to a captured watermark (the row-count anchor); because
1826/// the anchor column is appended last per row, a row within the watermark has
1827/// all its columns fully written, so a reader never observes a torn row.
1828pub struct FixedColumnReader {
1829    file: File,
1830    value_size: usize,
1831}
1832
1833impl FixedColumnReader {
1834    #[must_use]
1835    pub fn len(&self) -> usize {
1836        self.file
1837            .metadata()
1838            .map(|m| m.len() as usize / self.value_size)
1839            .unwrap_or(0)
1840    }
1841
1842    #[must_use]
1843    pub fn is_empty(&self) -> bool {
1844        self.len() == 0
1845    }
1846
1847    pub fn read_u32(&self, index: usize) -> io::Result<u32> {
1848        let mut buf = [0u8; 4];
1849        self.file
1850            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1851            .map_err(map_out_of_bounds)?;
1852        Ok(u32::from_le_bytes(buf))
1853    }
1854
1855    pub fn read_u64(&self, index: usize) -> io::Result<u64> {
1856        let mut buf = [0u8; 8];
1857        self.file
1858            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1859            .map_err(map_out_of_bounds)?;
1860        Ok(u64::from_le_bytes(buf))
1861    }
1862
1863    pub fn read_i32(&self, index: usize) -> io::Result<i32> {
1864        let mut buf = [0u8; 4];
1865        self.file
1866            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1867            .map_err(map_out_of_bounds)?;
1868        Ok(i32::from_le_bytes(buf))
1869    }
1870
1871    pub fn read_i64(&self, index: usize) -> io::Result<i64> {
1872        let mut buf = [0u8; 8];
1873        self.file
1874            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1875            .map_err(map_out_of_bounds)?;
1876        Ok(i64::from_le_bytes(buf))
1877    }
1878
1879    pub fn read_f64(&self, index: usize) -> io::Result<f64> {
1880        let mut buf = [0u8; 8];
1881        self.file
1882            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1883            .map_err(map_out_of_bounds)?;
1884        Ok(f64::from_le_bytes(buf))
1885    }
1886
1887    pub fn read_bool(&self, index: usize) -> io::Result<bool> {
1888        let mut buf = [0u8; 1];
1889        self.file
1890            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1891            .map_err(map_out_of_bounds)?;
1892        Ok(buf[0] != 0)
1893    }
1894
1895    pub fn read_uuid(&self, index: usize) -> io::Result<[u8; 16]> {
1896        let mut buf = [0u8; 16];
1897        self.file
1898            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1899            .map_err(map_out_of_bounds)?;
1900        Ok(buf)
1901    }
1902
1903    pub fn read_timestamp(&self, index: usize) -> io::Result<i64> {
1904        let mut buf = [0u8; 8];
1905        self.file
1906            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1907            .map_err(map_out_of_bounds)?;
1908        Ok(i64::from_le_bytes(buf))
1909    }
1910
1911    pub fn read_bytes(&self, index: usize) -> io::Result<Vec<u8>> {
1912        let mut buf = vec![0u8; self.value_size];
1913        self.file
1914            .read_exact_at(&mut buf, (index * self.value_size) as u64)
1915            .map_err(map_out_of_bounds)?;
1916        Ok(buf)
1917    }
1918}
1919
1920/// Read-only, positional view over a [`VariableColumn`]'s data + offsets files
1921/// (#56 Direction B).  See [`FixedColumnReader`] for the concurrency model.
1922pub struct VariableColumnReader {
1923    data_file: File,
1924    offsets_file: File,
1925}
1926
1927impl VariableColumnReader {
1928    #[must_use]
1929    pub fn len(&self) -> usize {
1930        self.offsets_file
1931            .metadata()
1932            .map(|m| m.len() as usize / 16)
1933            .unwrap_or(0)
1934    }
1935
1936    #[must_use]
1937    pub fn is_empty(&self) -> bool {
1938        self.len() == 0
1939    }
1940
1941    pub fn read_string(&self, index: usize) -> io::Result<String> {
1942        let offsets_pos = (index * 16) as u64;
1943        let mut offset_buf = [0u8; 8];
1944        let mut length_buf = [0u8; 8];
1945        self.offsets_file
1946            .read_exact_at(&mut offset_buf, offsets_pos)
1947            .map_err(map_out_of_bounds)?;
1948        self.offsets_file
1949            .read_exact_at(&mut length_buf, offsets_pos + 8)
1950            .map_err(map_out_of_bounds)?;
1951
1952        let offset = u64::from_le_bytes(offset_buf);
1953        let length = u64::from_le_bytes(length_buf);
1954
1955        let mut data = vec![0u8; length as usize];
1956        self.data_file.read_exact_at(&mut data, offset)?;
1957
1958        String::from_utf8(data).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1959    }
1960}
1961
1962/// Read-only, positional view over a [`Tombstones`] file (#56 Direction B).
1963/// See [`FixedColumnReader`] for the concurrency model.
1964pub struct TombstonesReader {
1965    file: File,
1966}
1967
1968impl TombstonesReader {
1969    #[must_use]
1970    pub fn len(&self) -> usize {
1971        self.file.metadata().map(|m| m.len() as usize).unwrap_or(0)
1972    }
1973
1974    #[must_use]
1975    pub fn is_empty(&self) -> bool {
1976        self.len() == 0
1977    }
1978
1979    pub fn is_deleted(&self, index: usize) -> io::Result<bool> {
1980        let mut buf = [0u8; 1];
1981        self.file
1982            .read_exact_at(&mut buf, index as u64)
1983            .map_err(map_out_of_bounds)?;
1984        Ok(buf[0] != 0)
1985    }
1986}