coordinode-lsm-tree 7.1.0

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2025-present, fjall-rs
// Copyright (c) 2026-present, Dmitry Prudnikov

pub mod block;
pub(crate) mod block_index;
pub(crate) mod block_layout;
#[cfg(feature = "columnar")]
pub(crate) mod column_page;
pub mod column_type;
#[cfg(feature = "columnar")]
pub mod columnar;
#[cfg(feature = "columnar")]
pub mod columnar_cursor;
#[cfg(feature = "columnar")]
pub mod columnar_predicate;
pub mod data_block;
pub mod delete_bitmap;
pub(crate) mod file_pool;
pub mod filter;
#[cfg(feature = "columnar")]
pub(crate) mod group_carry;
mod id;
mod index_block;
mod inner;
#[cfg(feature = "std")]
pub(crate) use inner::PUNCH_ALIGN;
#[cfg(test)]
pub(crate) use inner::PUNCH_CHUNK;
pub(crate) mod iter;
#[cfg(feature = "zstd")]
pub(crate) mod lazy_block;
pub(crate) mod locator;
pub(crate) mod meta;
pub(crate) mod multi_writer;
pub(crate) mod probe_stats;
pub(crate) mod regions;
#[cfg(feature = "std")]
pub(crate) mod relocate;
#[cfg(feature = "columnar")]
pub(crate) mod row_group;
mod scanner;
pub(crate) mod seqno_bounds;
pub(crate) mod staged;
// Reached through the doc-hidden `table` module by the crate's own tools; it
// carries no stability promise, and its items change with the read path.
pub mod util;
pub mod writer;
pub(crate) mod zone_map;

// std-gated like the sibling test modules: the tests drive real files through
// `StdFs` and the std-only `restrict_bound` sidecar API, so a no-std test
// build must skip the whole module.
#[cfg(all(test, feature = "std"))]
#[allow(
    clippy::unwrap_used,
    clippy::indexing_slicing,
    clippy::useless_vec,
    clippy::needless_borrows_for_generic_args,
    reason = "test code"
)]
mod tests;

#[cfg(all(test, feature = "std", feature = "metrics"))]
#[expect(clippy::expect_used, reason = "test code")]
mod lookup_fd_tests;

pub use block::{Block, BlockOffset};
pub use data_block::DataBlock;
pub use id::{GlobalTableId, TableId};
pub use index_block::{BlockHandle, IndexBlock, KeyedBlockHandle};
pub use scanner::Scanner;
pub use writer::Writer;

use crate::{
    Checksum, CompressionType, InternalValue, SeqNo, TreeId, UserKey,
    cache::Cache,
    comparator::SharedComparator,
    descriptor_table::DescriptorTable,
    file_accessor::FileAccessor,
    fs::{Fs, FsFile, FsOpenOptions},
    range_tombstone::RangeTombstone,
    table::{
        block::{BlockType, ParsedItem},
        block_index::{BlockIndex, FullBlockIndex, TwoLevelBlockIndex, VolatileBlockIndex},
        filter::block::FilterBlock,
        regions::ParsedRegions,
        writer::LinkedFile,
    },
};
use alloc::sync::Arc;
#[cfg(not(feature = "std"))]
use alloc::{boxed::Box, vec::Vec};
use block_index::BlockIndexImpl;
use core::ops::{Bound, RangeBounds};
use inner::Inner;
use iter::Iter;

use crate::path::PathBuf;
use portable_atomic::AtomicU64;
use util::{LookupFd, ReadCharge};

#[cfg(feature = "metrics")]
use crate::metrics::Metrics;

pub type TableInner = Inner;

/// Plan produced by [`Table::plan_block_tasks`]: the SST's file handle, the
/// table-local read seqno, whether the blocks need the special load path
/// (Page-ECC / columnar), and per data block its handle plus the positions
/// (into the input key batch) of the keys that fall in it.
pub(crate) type BlockTaskPlan = (
    Arc<dyn crate::fs::FsFile>,
    SeqNo,
    bool,
    Vec<(BlockHandle, Vec<usize>)>,
);

/// How [`Table::recover_inner`] treats degraded sidecars and the metadata id
/// cross-check.
#[derive(Clone, Copy)]
pub(crate) enum RecoveryMode {
    /// Live-tree open: a corrupt delete-bitmap / unreadable zone map fails
    /// closed, and the caller's durable id (manifest entry / file name) is
    /// cross-checked against the meta payload (with MID-mirror fallback on a
    /// bad TAIL copy).
    Live,
    /// Salvage open: a corrupt delete-bitmap / missing zone map degrades
    /// instead of failing, so a damaged sidecar still opens. For an
    /// UNENCRYPTED source the id cross-check uses `expected_id`: `Some` when
    /// the caller knows the durable id out-of-band (repair — from the SST
    /// file name), so a forged TAIL id falls back to the intact MID mirror
    /// instead of poisoning the recovered copy's identity; `None` for a
    /// standalone recovery reader, where the source's own stored id IS the
    /// identity to recover under. An ENCRYPTED open always cross-checks the
    /// caller's id — the meta block's AAD binds it regardless.
    Salvage {
        /// The durable table id known out-of-band, or `None` when the
        /// source's stored id is authoritative.
        expected_id: Option<TableId>,
        /// Load the MID meta mirror FIRST (tail as fallback), inverting the
        /// default tail-first order. Set by the salvage arbitration when the
        /// two mirrors decode to DIVERGENT contents: neither copy can be
        /// proven genuine, so salvage attempts both orders and keeps the
        /// attempt that recovers more.
        prefer_mid_meta: bool,
    },
}

/// Everything [`Table::recover`] needs, with the context a caller does not care
/// about defaulted by [`RecoverParams::new`].
///
/// A params struct rather than positional arguments on purpose: the old
/// signature carried three integers and two booleans in a row, so a transposed
/// `tree_id`/`table_id` or `pin_filter`/`pin_index` compiled cleanly and
/// surfaced only as misbehavior at runtime. Named fields make every call state
/// what it passes.
pub struct RecoverParams {
    /// Where the SST lives.
    pub file_path: PathBuf,
    /// The table's whole-file checksum, from the manifest (or freshly computed
    /// by a repair scan).
    pub checksum: Checksum,
    /// Bulk-ingest sequence offset from the manifest; `0` for a table whose
    /// intrinsic seqnos are authoritative.
    pub global_seqno: SeqNo,
    /// L0 recency key from the manifest; `None` takes the one the table's
    /// file was written with. An ingested table's comes from its install,
    /// which happens after its file is written.
    pub recency: Option<TableId>,
    /// Owning tree, keying shared caches; `0` for a transient open that must
    /// not pollute them.
    pub tree_id: TreeId,
    /// The table's durable id (its file name / manifest entry).
    pub table_id: TableId,
    /// Block cache.
    pub cache: Arc<Cache>,
    /// Descriptor table for pooled file handles; `None` opens per read.
    pub descriptor_table: Option<Arc<DescriptorTable>>,
    /// Filesystem the file is reachable through.
    pub fs: Arc<dyn Fs>,
    /// Pin the filter blocks in memory on open.
    pub pin_filter: bool,
    /// Pin the index blocks in memory on open.
    pub pin_index: bool,
    /// At-rest encryption provider, matching how the table was written.
    pub encryption: Option<Arc<dyn crate::encryption::EncryptionProvider>>,
    /// Every dictionary the tree can decompress against. The table resolves
    /// the id it recorded against this set; supplying a set that does not hold
    /// that id fails the recovery, naming the id.
    #[cfg(zstd_any)]
    pub zstd_dictionaries: crate::compression::ZstdDictionaries,
    /// The tree's key ordering.
    pub comparator: SharedComparator,
    /// The tree's prefix extractor. A prefix scan consults the table's filter
    /// only when the table's filter indexes this extractor's prefixes; `None`
    /// never consults it.
    pub prefix_extractor: Option<Arc<dyn crate::prefix::PrefixExtractor>>,
    /// Metrics sink.
    #[cfg(feature = "metrics")]
    pub metrics: Arc<Metrics>,
}

impl RecoverParams {
    /// Params for recovering the table at `file_path`, with every contextual
    /// field at its neutral default: no ingest offset, tree id `0` (a transient
    /// open that must not pollute shared caches), no descriptor table, nothing
    /// pinned, no encryption, no dictionary. Callers set what differs.
    #[must_use]
    pub fn new(
        file_path: PathBuf,
        checksum: Checksum,
        table_id: TableId,
        fs: Arc<dyn Fs>,
        comparator: SharedComparator,
        cache: Arc<Cache>,
    ) -> Self {
        Self {
            file_path,
            checksum,
            global_seqno: 0,
            recency: None,
            tree_id: 0,
            table_id,
            cache,
            descriptor_table: None,
            fs,
            pin_filter: false,
            pin_index: false,
            encryption: None,
            #[cfg(zstd_any)]
            zstd_dictionaries: crate::compression::ZstdDictionaries::new(),
            comparator,
            prefix_extractor: None,
            #[cfg(feature = "metrics")]
            metrics: Arc::new(Metrics::default()),
        }
    }
}

/// Cached outcome of the heal's lazy hard-link probe/detach (see
/// [`Table::ensure_unshared_for_write`]): the probe and copy run at most
/// once per scan, and only when a write-back is actually needed.
#[cfg(feature = "page_ecc")]
enum UnshareState {
    /// No write attempted yet: the link count has not been probed.
    Unprobed,
    /// The handle is safe to write through (exclusive, or already detached).
    Ready,
    /// The unshare failed; every write is refused with this reason.
    Failed(alloc::string::String),
}

/// A disk segment (a.k.a. `Table`, `SSTable`, `SST`, `sorted string table`) that is located on disk
///
/// A table is an immutable list of key-value pairs, split into compressed blocks.
/// A reference to the block (`block handle`) is saved in the "block index".
///
/// Deleted entries are represented by tombstones.
///
/// The tree-wide machinery a freshly created table must be bound to before it
/// becomes reachable, passed to [`Table::bind_to_tree`].
///
/// Collected in one type on purpose: publication happens from several places
/// (flush, recovery, ingest, compaction, the tight-space slice loop), and
/// having each install sinks by hand is what let two of them silently drift
/// into publishing tables that could never schedule their own healing.
pub(crate) struct TableSinks<'a> {
    /// Defers cleanup while a checkpoint is capturing, so an in-place heal
    /// cannot race a hard-link.
    pub deletion_pause: &'a Arc<crate::deletion_pause::DeletionPause>,
    /// Where a confirmed-persistent ECC correction queues the table for a
    /// healing rewrite.
    pub heal_hints: &'a Arc<crate::heal_hints::HealHints>,
    /// How the tree's columnar reads fetch their pages.
    pub read_budget: crate::config::ReadBudget,
    /// Moves an obsolete table's `unlink` off the foreground path.
    #[cfg(feature = "std")]
    pub background_deleter: &'a Arc<crate::BackgroundDeleter>,
    /// Whether the tree counts the table's filter probes: it does when it
    /// allocates filter memory by probe load.
    pub track_filter_probes: bool,
}

/// Tables can be merged together to improve read performance and free unneeded disk space by removing outdated item versions.
#[doc(alias("sstable", "sst", "sorted string table"))]
#[derive(Clone)]
pub struct Table(
    Arc<Inner>,
    /// Tight-space restriction: when `Some(bound)`, this version's view of the
    /// table is clamped to keys `>= bound`. The on-disk data blocks below
    /// `bound` have been punched out ([`crate::fs::Fs::punch_hole`]) and their
    /// content lives in a freshly merged output table that supersedes them, so
    /// reads must not touch the punched prefix. Carried on the `Table` wrapper
    /// (not the shared `Arc<Inner>`) so an older snapshot keeps its own
    /// unrestricted view of the same physical SST. `None` on the common path.
    Option<UserKey>,
    /// Refreshed full-file checksum: when `Some`, an in-place heal changed the
    /// file's bytes AFTER it was recovered, and this digest supersedes the one
    /// captured at recovery. Carried on the wrapper (like the restriction) so
    /// the version diff sees the change and persists it to the manifest, while
    /// older snapshots keep the digest they were recovered under. `None` on
    /// the common path.
    Option<Checksum>,
);

impl core::ops::Deref for Table {
    type Target = Inner;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

#[cfg_attr(coverage_nightly, coverage(off))]
impl core::fmt::Debug for Table {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "Table:{}({:?})", self.id(), self.metadata.key_range)
    }
}

/// How an SST's rows are visible at a query snapshot, returned by
/// [`Table::seqno_visibility`]. Drives whether the tree-level columnar scan can
/// stream a segment verbatim ([`All`](Self::All)) or must apply a per-row seqno
/// mask ([`Partial`](Self::Partial)); [`None`](Self::None) segments are dropped.
/// The range estimators use the same classification to skip a table a read at
/// that snapshot would return nothing from.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub(crate) enum SeqnoVisibility {
    /// No row is visible at the snapshot (the SST postdates it).
    None,
    /// Every row is visible (the SST entirely predates the snapshot).
    All,
    /// The snapshot straddles the SST's seqno range; visibility is per-row.
    Partial,
}

/// How a batched read gets a Page-ECC or columnar table's data block, as
/// [`Table::batched_special_read`] decides.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum SpecialRead {
    /// `len` bytes of the table's file from `offset`, read with the batch's
    /// other blocks and handed to [`Table::decode_special_block`].
    Bytes { offset: u64, len: usize },
    /// Through the table's own load path, in a job.
    Load,
}

/// Which data blocks a key range boundary takes in [`Table::data_span`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum SpanEdge {
    /// Every block holding a key of the range, boundary blocks whole: a range
    /// inside one block covers that block rather than nothing.
    Whole,
    /// The blocks whose last key lies in the range. Ranges that do not
    /// overlap take disjoint blocks, so splitting a table's blocks between
    /// several ranges hands each block out once.
    ByLastKey,
}

/// The part of a table's data section a key range covers, in byte offsets
/// (see [`Table::data_span`]).
#[derive(Clone, Copy, Debug)]
pub(crate) struct DataSpan {
    /// Bytes of data blocks the range covers, within the live part.
    pub covered: u64,
    /// Where the live part starts: past the prefix a restricted view punched
    /// out, 0 otherwise.
    pub live_start: u64,
    /// The end of the data section.
    pub data_end: u64,
}

/// Result of a bloom filter check.
enum BloomResult {
    /// Bloom says key is definitely absent — skip point read.
    Skip,
    /// The key sorts past the last filter partition: absent by the partition
    /// index alone, with no filter answering, so no probe of one.
    PastPartitions,
    /// Point read should proceed.
    Proceed {
        /// Whether a filter was present, for metrics and probe accounting.
        has_filter: bool,
    },
}

/// Where the filter a key is checked against lives (see
/// [`Table::filter_source`]).
pub(crate) enum FilterSource<'a> {
    /// The table has no filter, or none it can consult.
    None,
    /// The table's whole filter, pinned in memory.
    Pinned(&'a FilterBlock),
    /// The filter block, or the filter partition holding the key, to read.
    Block(BlockHandle),
    /// The key sorts past the last filter partition.
    PastPartitions,
}

/// What a key check of a table's filters found (see
/// [`Table::key_filter_answer`]).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum KeyFilterAnswer {
    /// A filter answered absent.
    Absent,
    /// The key sorts past the last filter partition: absent by the partition
    /// index alone, with no filter answering.
    PastPartitions,
    /// The key may be present, or nothing could rule it out.
    MayContain,
}

impl BloomResult {
    fn should_skip(&self) -> bool {
        matches!(self, Self::Skip | Self::PastPartitions)
    }

    fn has_filter(&self) -> bool {
        matches!(self, Self::Proceed { has_filter: true })
    }

    /// What this answer adds to its table's probe counts: a probe when a
    /// filter answered, and a negative one when it answered absent.
    const fn probe_counts(&self) -> crate::table::probe_stats::ProbeCounts {
        let (probes, negatives) = match self {
            Self::Skip => (1, 1),
            Self::Proceed { has_filter: true } => (1, 0),
            Self::PastPartitions | Self::Proceed { has_filter: false } => (0, 0),
        };
        crate::table::probe_stats::ProbeCounts { probes, negatives }
    }
}

/// Re-applies a bulk-ingested table's base sequence number to a table-local
/// seqno, translating it back to the global coordinate that callers compare
/// across tables.
///
/// The sum never overflows on any reachable input: a row reaches this
/// translation only when it is visible at the query snapshot `Q`, which (by the
/// exclusive MVCC check `local < Q - global`) requires `local + global < Q`, and
/// `Q <= SeqNo::MAX`. The `checked_add` therefore always succeeds; an overflow
/// would mean the invariant was violated, so it aborts loudly in both debug and
/// release builds rather than wrapping to a subtly wrong seqno (the silent-
/// corruption class `saturating_add` shares). For a non-ingested table `global`
/// is `0` and this is the identity.
#[inline]
fn apply_global_seqno(local: SeqNo, global: SeqNo) -> SeqNo {
    local.checked_add(global).unwrap_or_else(|| {
        unreachable!(
            "apply_global_seqno: table-local seqno + global base overflowed SeqNo::MAX, \
             but a row is only translated here when visible (local + global < query snapshot)"
        )
    })
}

/// Result of [`Table::salvage_load_block`]: the decoded block plus, when it read
/// back cleanly, its raw on-disk bytes for a verbatim copy.
pub(crate) struct SalvageBlock {
    /// The decoded (decompressed / decrypted / ECC-healed) block: the source of
    /// the per-row entries the salvage walk accounts and, on the re-encode path,
    /// re-serializes.
    pub block: Block,
    /// `Some((raw_on_disk_bytes, header, inner_layout))` when the block read back
    /// cleanly (no ECC recovery): the walk byte-copies these verbatim. `None` when
    /// ECC recovery healed the block, so the faulty on-disk bytes must not be
    /// propagated and the caller re-encodes the healed payload instead.
    pub verbatim: Option<VerbatimCopy>,
    /// Whether ECC recovery had to heal the block to read it. Kept separate
    /// from `verbatim` (which is also `None` for verbatim-ineligible clean
    /// reads) so the walk's live progress counts genuine heals only.
    pub ecc_recovered: bool,
}

/// What one handle in a section names, for the walks that frame handles
/// against the bytes they point at.
#[cfg(feature = "std")]
#[derive(Clone, Copy)]
enum FrameUnit {
    /// One block: every handle in the index section.
    Block,
    /// One data unit: a block for a row-major table, a row group for a
    /// columnar one.
    DataUnit,
}

/// Result of [`Table::salvage_load_row_group`]: the decoded group plus, when
/// every block in it read back cleanly, the group's raw bytes.
#[cfg(all(feature = "columnar", feature = "std"))]
pub(crate) struct SalvageRowGroup {
    /// The group's verified blocks. Left undecoded so the walk can tell a
    /// group whose bytes did not read from one whose content does not decode:
    /// the two are dropped for different reasons and reported differently.
    pub group: crate::table::row_group::RowGroupBlocks,
    /// `Some((raw_group_bytes, uncompressed_length))` when every block of the
    /// group qualified for a verbatim copy; `None` otherwise, and the caller
    /// re-encodes the decoded group.
    pub verbatim: Option<(alloc::vec::Vec<u8>, u64)>,
    /// Whether ECC recovery healed any block of the group.
    pub ecc_recovered: bool,
}

/// Raw on-disk frame captured for a verbatim block copy:
/// `(raw_on_disk_bytes, header, inner_layout)`. See [`SalvageBlock::verbatim`].
pub(crate) type VerbatimCopy = (
    alloc::vec::Vec<u8>,
    crate::table::block::Header,
    alloc::vec::Vec<u32>,
);

/// Outcome of [`Table::conservative_restriction`] — the CONSERVATIVE
/// punch-geometry classification for a punched SST whose exact
/// `.restrict-bound` sidecar is not trustworthy.
#[cfg(feature = "std")]
pub(crate) enum DerivedRestriction {
    /// The zeroed blocks form a CLEAN prefix (a fully successful punch):
    /// restrict to this bound — the first readable block's end key — and no
    /// superseded key resurrects, at the cost of at most that one straddling
    /// block's live suffix.
    Bound(UserKey),
    /// Every data block reads as zeros: no live data survives the punch; the
    /// caller excludes the table.
    NoLiveData,
    /// A readable block sits BELOW a zeroed one — positive evidence of failed
    /// `punch_hole` calls, after which no geometry bound can separate
    /// intact-but-consumed blocks from live ones. The caller sets the table
    /// aside (resurrection mode derives greedily instead, accepting the
    /// re-exposure by contract).
    IrregularPunch,
}

/// Verdict of [`Table::punch_geometry`] — whether any zeroed
/// data-block run carries the physical hole that proves a tight-space
/// reclaim.
#[cfg(feature = "std")]
pub(crate) enum PunchProbe {
    /// A zeroed run carries a proven hole: the SST was punched.
    Punched,
    /// No zeroed data blocks, or every zeroed run is proven ALLOCATED —
    /// zeros are damage, not a reclaim. Also the verdict on a mount that
    /// cannot punch at all: a reclaim never ran there.
    Unpunched,
    /// Zeroed runs exist on a PUNCH-CAPABLE mount whose hole probe cannot
    /// answer (`None`): a lost-sidecar reclaim and damage are
    /// indistinguishable, so the caller must fail closed unless resurrection
    /// explicitly accepts the ambiguity.
    Unproven,
}

/// Which semantic cross-check a combined reconcile pass tripped on, so the
/// caller keeps its own per-gate wording instead of one generic message.
#[cfg(feature = "std")]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ReconcileGate {
    /// Index separators against the addressed blocks' decoded last keys.
    Separators,
    /// Per-KV footer digests.
    KvChecksums,
    /// Recorded seqno bounds against the decoded entries.
    SeqnoBounds,
    /// Declared entry count against the decoded one.
    BlockEntryCounts,
    /// Recorded zone map against the decoded statistics.
    ZoneMap,
    /// Recorded locator against the decoded newest-version blocks.
    Locator,
    /// Filter against the decoded keys (and their prefixes).
    Filter,
    /// In-block indexes and the global sort order.
    PointReadReachability,
    /// Recorded metadata bounds against the decoded contents.
    MetadataBounds,
    /// Recorded inner-block boundaries against the frame's actual zstd blocks.
    ///
    /// Only a zstd build can raise it: the writer emits the `block_layout`
    /// section exclusively for data blocks that split into two or more inner
    /// zstd blocks, so without zstd there are no such frames and no boundaries
    /// to disagree about. The section-level forgery (a present-but-EMPTY map,
    /// i.e. a relabelled `delete_bitmap`) is caught on every build, but by
    /// `verify_block_layout` and outside this enum.
    #[cfg_attr(
        not(feature = "zstd"),
        expect(
            dead_code,
            reason = "the per-frame gate that raises it needs a zstd decoder"
        )
    )]
    BlockLayout,
}

/// The recorded metadata a reconcile judges, plus the accumulators the block
/// walk fills for it: read and seeded once, then compared in `finish`.
#[cfg(feature = "std")]
pub(crate) struct MetaBoundsProbe {
    /// The disk-fresh meta whose bounds are on trial.
    meta: crate::table::meta::ParsedMeta,
    /// The recorded range tombstones, whose spans the key range must cover.
    tombstones: Option<Vec<crate::range_tombstone::RangeTombstone>>,
    /// `(start, seqno)` of the synthetic RT-only sentinel entry, excluded from
    /// the KV seqno maximum exactly once.
    sentinel: Option<(UserKey, SeqNo)>,
    /// Whether that exclusion has already happened.
    sentinel_excluded: bool,
    /// Whether this is a tight-space restricted view, which relaxes the
    /// item-count equality to a subset check.
    restricted: bool,
    /// Blocks the index lists, punched prefix included.
    block_count: u64,
    /// Whether the caller already authenticated this file against a matching
    /// manifest digest.
    bitmap_digest_authenticated: bool,
    /// Entries the live blocks decoded to.
    count: u64,
    /// First and last decoded user key over the live suffix.
    first_key: Option<UserKey>,
    last_key: Option<UserKey>,
    /// Lowest and highest decoded seqno over the live suffix.
    seqno_lo: Option<SeqNo>,
    seqno_hi: Option<SeqNo>,
}

/// The on-disk filter state one reconcile needs, so the probe reads the
/// section (and each partition) once no matter how many blocks it checks.
#[cfg(feature = "std")]
pub(crate) struct FilterProbe<'a> {
    /// The table being judged, for its comparator and id.
    table: &'a Table,
    /// The file the sections are read from, lent by the pass that opened it
    /// and borrowed across the walk for the partition reads.
    file: &'a dyn crate::fs::FsFile,
    /// Codec / encryption / ECC context every filter block decodes under.
    transform: crate::table::block::BlockTransform<'a>,
    /// The partition index, when the filter is partitioned.
    index: Option<IndexBlock>,
    /// The single filter block, when it is not.
    full: Option<crate::table::filter::block::FilterBlock>,
    /// Partitions already read, keyed by file offset: one read each.
    partitions: alloc::collections::BTreeMap<u64, crate::table::filter::block::FilterBlock>,
    /// The last key probed, so a key's older versions are not re-probed
    /// across a block boundary.
    prev_key: Option<UserKey>,
    /// The extractor whose prefixes a full filter must also report present.
    prefix_extractor: Option<alloc::sync::Arc<dyn crate::prefix::PrefixExtractor>>,
}

#[cfg(feature = "std")]
impl FilterProbe<'_> {
    /// Probes one decoded block's keys, whose hashes `key_hashes` holds in
    /// entry order, against the filter.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the filter reports an existing key
    /// (or its prefix) as definitely absent, or a partition is missing / empty
    /// for a key that exists.
    fn check_block(&mut self, block: &DecodedBlock, key_hashes: &[u64]) -> crate::Result<()> {
        Table::check_filter_block(self, block, key_hashes)
    }
}

/// One live data block, decoded ONCE for every cross-check gate that needs its
/// contents, from [`Table::for_each_live_block`].
///
/// Each gate used to walk the whole table itself, so a single reconcile decoded
/// every block seven to nine times and the decode dominates a repair's cost.
/// Materializing the block's row view, its columnar batch and its entries here
/// hands the SAME decode to all of them.
// Compiled under no_std alongside `verify_kv_checksums`, which walks with it
// and is itself dead there (the verify / scrub callers are std-gated).
#[cfg_attr(
    not(feature = "std"),
    expect(
        dead_code,
        reason = "gate-only decode; the verify/scrub consumers are std-gated"
    )
)]
pub(crate) struct DecodedBlock {
    /// Where the block lives, as the block index records it.
    pub(crate) handle: BlockHandle,
    /// The block exactly as it came off disk, per-KV footer INTACT. The row
    /// view below strips the footer, so the per-KV digest gate needs these
    /// bytes rather than the stripped ones.
    pub(crate) raw: Block,
    /// The same block one layer earlier: the payload as the writer compressed
    /// it, post-checksum and post-decrypt but pre-decompression. Carried from
    /// the SAME read that produced `raw`, so the gate that cross-checks the
    /// frame's inner-block boundaries costs no extra I/O. Equal to `raw.data`
    /// on an uncompressed table, where the two layers coincide.
    #[cfg_attr(
        not(feature = "zstd"),
        expect(
            dead_code,
            reason = "the only consumer is the block-layout boundary gate, which needs a zstd decoder"
        )
    )]
    pub(crate) frame: crate::Slice,
    /// The row-major view. `None` on a columnar table, whose rows are
    /// reconstructed from `batch` instead.
    pub(crate) row: Option<DataBlock>,
    /// The columnar batch this block decoded to, for the per-column statistics
    /// only a columnar table records. `None` on a row table.
    #[cfg(feature = "columnar")]
    pub(crate) batch: Option<crate::table::columnar::ColumnBatch>,
    /// The block's entries in block order, materialized once.
    pub(crate) entries: Vec<InternalValue>,
}

/// Everything one pass over the data blocks can say about a tight-space
/// reclaim, from [`Table::punch_geometry`].
///
/// Read ONCE and classified once: proving a block zeroed reads it in FULL,
/// and a reclaimed prefix can be hundreds of blocks — deriving the verdict and
/// the bound on separate passes read the same dead prefix twice and left their
/// agreement resting on the caller's ordering.
#[cfg(feature = "std")]
pub(crate) struct PunchGeometry {
    /// Whether the zeroed runs are backed by a physical hole.
    pub(crate) verdict: PunchProbe,
    /// Index and END key of the first readable block. The conservative bound
    /// is that key: at or above the true mid-block bound, so no superseded key
    /// resurrects. `None` when every block reads as zeros.
    pub(crate) first_readable: Option<(usize, UserKey)>,
    /// Index of the first readable block AFTER the last zeroed one — the
    /// greedy (resurrection) anchor, which keeps the whole readable region.
    pub(crate) after_last_zeroed: Option<usize>,
    /// A readable block sits BELOW a zeroed one: positive evidence that
    /// individual `punch_hole` calls failed mid-reclaim, after which no
    /// geometry bound separates intact-but-consumed blocks from live ones.
    pub(crate) irregular: bool,
}

impl Table {
    #[must_use]
    pub fn global_seqno(&self) -> SeqNo {
        self.0.global_seqno
    }

    /// The lowest and highest sequence numbers this table holds, in the tree's
    /// own seqno space, or `None` when they cannot be expressed there.
    ///
    /// The stored bounds are LOCAL to the table: a bulk ingest writes rows at
    /// local seqnos and carries the base in [`Self::global_seqno`], so the two
    /// have to be added before a bound means anything outside this table. Use
    /// it to compare the ages of two tables; use [`Self::seqno_visibility`] to
    /// ask what a given snapshot sees.
    ///
    /// The two halves of that sum come from different places, the bounds from
    /// the table's own metadata and the base from the manifest, so nothing in
    /// the type system says they still fit together. A table written normally
    /// always fits, since both halves were seqnos the tree issued; damaged
    /// metadata need not, and `None` says exactly that rather than wrapping
    /// into a plausible-looking bound. A caller comparing ages has to treat it
    /// as "cannot tell", never as an extreme.
    #[must_use]
    pub fn seqno_range(&self) -> Option<(SeqNo, SeqNo)> {
        let base = self.global_seqno();
        Some((
            self.metadata.seqnos.0.checked_add(base)?,
            self.metadata.seqnos.1.checked_add(base)?,
        ))
    }

    /// Classifies how this SST's rows are visible at query snapshot `seqno`,
    /// using the same exclusive MVCC rule as [`Self::point_read`]: a row is
    /// visible iff its effective seqno (`local + global_seqno`) is `< seqno`.
    ///
    /// Bulk-ingested columnar SSTs carry a uniform per-row seqno (every local
    /// seqno is `0`, sharing one `global_seqno`), so they classify as wholly
    /// [`All`](SeqnoVisibility::All) or wholly [`None`](SeqnoVisibility::None);
    /// only a flush-produced multi-seqno SST whose seqno range straddles the
    /// snapshot is [`Partial`](SeqnoVisibility::Partial), which the tree-level
    /// columnar scan resolves with a per-row seqno mask.
    pub(crate) fn seqno_visibility(&self, seqno: SeqNo) -> SeqnoVisibility {
        // Translate the query snapshot into this table's local seqno space; a
        // snapshot below the base predates every row.
        let Some(local_threshold) = seqno.checked_sub(self.global_seqno()) else {
            return SeqnoVisibility::None;
        };
        // seqnos are (min, max) local; visible rows satisfy `local < threshold`.
        if self.metadata.seqnos.0 >= local_threshold {
            return SeqnoVisibility::None;
        }
        if self.metadata.seqnos.1 < local_threshold {
            SeqnoVisibility::All
        } else {
            SeqnoVisibility::Partial
        }
    }

    /// On-disk bytes of the blob values this table references.
    ///
    /// # Errors
    ///
    /// When the table's `linked_blob_files` section cannot be read or parsed.
    pub fn referenced_blob_bytes(&self) -> crate::Result<u64> {
        Ok(self.blob_links()?.iter().map(|f| f.on_disk_bytes).sum())
    }

    /// The blob files this table references, with the key span each is
    /// referenced over: read from the `linked_blob_files` section on first use
    /// and kept. Empty for a table that references no blob file.
    ///
    /// # Errors
    ///
    /// When the section cannot be read or parsed; nothing is kept then, so a
    /// later call reads it again.
    pub fn blob_links(&self) -> crate::Result<&[LinkedFile]> {
        self.0
            .blob_links
            .get_or_try_init(|| {
                // The links are kept once read, so the descriptor is needed
                // this once only: it is taken without promoting or caching it,
                // which keeps a statistics call over every table from churning
                // the descriptors the workload is using.
                let links = self.read_blob_file_references(|| {
                    Ok(self
                        .file_accessor
                        .peek_or_open_table(&self.global_id(), &self.path)?)
                })?;
                Ok(links.unwrap_or_default().into_boxed_slice().into())
            })
            .map(|links| &**links)
    }

    pub fn list_blob_file_references(&self) -> crate::Result<Option<Vec<LinkedFile>>> {
        self.read_blob_file_references(|| {
            Ok(self
                .file_accessor
                .get_or_open_table(&self.global_id(), &self.path)?
                .0)
        })
    }

    /// [`Self::list_blob_file_references`] for verification: the descriptor is
    /// taken without promoting or caching it, so the check leaves no trace.
    #[cfg(feature = "std")]
    fn untraced_blob_file_references(&self) -> crate::Result<Option<Vec<LinkedFile>>> {
        self.read_blob_file_references(|| {
            Ok(self
                .file_accessor
                .peek_or_open_table(&self.global_id(), &self.path)?)
        })
    }

    /// The blob objects this table's cell rows own, as `(blob file, offset)`
    /// sorted ascending: read from the `owned_blob_objects` section, not kept.
    /// Empty for a table that owns none. What dropping the whole table
    /// releases, learned without reading its data.
    ///
    /// # Errors
    ///
    /// When the section cannot be read, fails its checks, or does not parse.
    pub(crate) fn owned_blob_objects(&self) -> crate::Result<Vec<(crate::vlog::BlobFileId, u64)>> {
        let Some(handle) = self.regions.owned_blob_objects else {
            return Ok(Vec::new());
        };
        // Taken without promoting or caching the descriptor: a drop reads this
        // once, for a table that is going.
        let fd = self
            .file_accessor
            .peek_or_open_table(&self.global_id(), &self.path)?;
        let transform = match self.encryption.as_deref() {
            Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
            None => crate::table::block::BlockTransform::PLAIN,
        };
        let transform = match self.metadata.ecc_params {
            Some(ecc) => transform.with_ecc(ecc),
            None => transform,
        };
        let block = Block::from_file(
            fd.as_ref(),
            handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type: BlockType::OwnedBlobObjects,
                dict_id: 0,
                window_log: 0,
            },
            &transform,
        )?;
        if block.header.block_type != BlockType::OwnedBlobObjects {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        crate::table::writer::parse_owned_blob_objects(&block.data)
    }

    /// Reads and parses the `linked_blob_files` section through the descriptor
    /// `open` yields, opened only when the section exists.
    fn read_blob_file_references(
        &self,
        open: impl FnOnce() -> crate::Result<Arc<dyn FsFile>>,
    ) -> crate::Result<Option<Vec<LinkedFile>>> {
        Ok(if let Some(handle) = &self.regions.linked_blob_files {
            let fd = open()?;

            // Read the exact region using pread-style helper
            let buf =
                crate::file::read_exact(fd.as_ref(), *handle.offset(), handle.size() as usize)?;

            Some(crate::table::writer::parse_linked_blob_files(&buf)?)
        } else {
            None
        })
    }

    /// Gets the global table ID.
    #[must_use]
    pub(crate) fn global_id(&self) -> GlobalTableId {
        (self.tree_id, self.id()).into()
    }

    #[must_use]
    pub fn filter_size(&self) -> u32 {
        self.regions.filter.map(|x| x.size()).unwrap_or_default()
    }

    /// The bytes of the sections that grow with the table's data, past its
    /// data blocks: every section but its metadata and the framing that holds
    /// the file together.
    #[cfg(feature = "std")]
    pub(crate) fn data_scaled_section_bytes(&self) -> u64 {
        let regions = &self.regions;
        [
            Some(regions.tli),
            regions.tli_tail,
            regions.index,
            regions.filter,
            regions.filter_tli,
            regions.range_tombstones,
            regions.block_layout,
            regions.locator,
            regions.seqno_bounds,
            regions.zone_map,
            regions.delete_bitmap,
            regions.owned_blob_objects,
            regions.linked_blob_files,
        ]
        .into_iter()
        .flatten()
        .map(|handle| u64::from(handle.size()))
        .sum()
    }

    #[must_use]
    pub fn pinned_filter_size(&self) -> usize {
        self.pinned_filter_block
            .as_ref()
            .map(FilterBlock::size)
            .unwrap_or_default()
    }

    /// Filter bytes held in memory now: the pinned filter, or the filter
    /// blocks resident in the block cache, counted at their on-disk size.
    /// Asks the cache without counting a hit, so a report does not keep the
    /// blocks it looks at resident.
    #[must_use]
    pub(crate) fn resident_filter_bytes(&self) -> u64 {
        // A pinned full filter is resident whole; its on-disk handle, not the
        // decoded payload, carries the framing the other figures count.
        if self.pinned_filter_block.is_some() {
            return u64::from(self.filter_size());
        }
        let resident = |handle: &BlockHandle| {
            if self.cache.has_block(self.global_id(), handle.offset()) {
                u64::from(handle.size())
            } else {
                0
            }
        };
        if let Some(filter_idx) = &self.pinned_filter_index {
            // A partitioned filter's partitions, each cached on its own.
            filter_idx
                .iter(self.comparator.clone())
                .map(|handle| resident(handle.materialize(filter_idx.as_slice()).as_ref()))
                .sum()
        } else {
            self.regions.filter.as_ref().map_or(0, resident)
        }
    }

    #[must_use]
    pub fn pinned_block_index_size(&self) -> usize {
        match &*self.block_index {
            BlockIndexImpl::Full(full_block_index) => full_block_index.inner().inner.size(),
            BlockIndexImpl::VolatileFull(_) | BlockIndexImpl::Closed => 0,
            BlockIndexImpl::TwoLevel(two_level_block_index) => {
                two_level_block_index.top_level_index.inner.size()
            }
        }
    }

    /// Gets the table ID.
    ///
    /// The table ID is unique for this tree, but not
    /// across multiple trees, use [`Table::global_id`] for that.
    #[must_use]
    pub fn id(&self) -> TableId {
        self.metadata.id
    }

    /// The table's L0 recency key, as the manifest records it: an id a flush
    /// takes when it starts, an ingested table's id taken when it is
    /// installed, a compaction output's highest INPUT recency. Higher = newer
    /// content; L0 is ordered by it because a table's own id is allocated at
    /// write start, or earlier for a pooled file, and says nothing about where
    /// its content belongs.
    #[must_use]
    pub(crate) fn l0_recency(&self) -> TableId {
        self.0.l0_recency
    }

    /// Records that the directory entry naming this table's file was durable
    /// before the table was written into it.
    pub(crate) fn mark_entry_durable(&self) {
        self.0
            .entry_durable
            .store(true, core::sync::atomic::Ordering::Relaxed);
    }

    /// Whether the directory entry naming this table's file was durable before
    /// the table was written into it, so the install that names it need not
    /// sync its folder.
    #[must_use]
    pub(crate) fn entry_durable(&self) -> bool {
        self.0
            .entry_durable
            .load(core::sync::atomic::Ordering::Relaxed)
    }

    /// This segment's positional delete-bitmap (rows deleted by position),
    /// loaded on open. Empty when the segment has no materialized deletes, in
    /// which case a scan applies no mask.
    #[must_use]
    pub fn delete_bitmap(&self) -> &crate::table::delete_bitmap::DeleteBitmap {
        self.delete_bitmap.as_ref()
    }

    /// Whether this segment was written WITH a positional delete bitmap (it
    /// carries a `delete_bitmap` section), independent of whether that bitmap is
    /// currently loaded. This stays `true` even when a salvage-mode open degraded
    /// a corrupt bitmap to empty, so the salvage walk can tell "no deletes ever"
    /// apart from "deletes whose bitmap was lost" — and must NOT byte-copy a block
    /// of the latter verbatim (which would resurrect positionally-deleted rows
    /// the recovered copy no longer masks).
    ///
    /// `pub(crate)` for the salvage walk ([`crate::salvage`]); only the columnar
    /// copy-through path consults it, so it is gated to that feature.
    #[cfg(feature = "columnar")]
    pub(crate) fn has_delete_bitmap_section(&self) -> bool {
        self.regions.delete_bitmap.is_some()
    }

    /// Whether the loaded delete-bitmap's CONTENTS match the meta-recorded
    /// `descriptor#delete_bitmap_hash` (and length). The section's own block
    /// checksum only proves the bytes are self-consistent; an equal-cardinality
    /// substitution (a different, checksum-valid bitmap) passes both that and the
    /// positional cross-check, yet masks the WRONG rows. Salvage has no original
    /// whole-file digest to compare against, so it MUST authenticate the contents
    /// before masking. A present section with a missing hash (a table written
    /// before the field) cannot be authenticated → `false` (fail closed). A table
    /// with no delete-bitmap section has nothing to authenticate → `true`.
    #[cfg(feature = "columnar")]
    pub(crate) fn delete_bitmap_authenticated(&self) -> bool {
        if !self.has_delete_bitmap_section() {
            return true;
        }
        match self.metadata.delete_bitmap_hash {
            Some(recorded) => {
                let bitmap = self.delete_bitmap();
                crate::hash::hash128(&bitmap.encode()) == recorded
                    && self.metadata.delete_bitmap_len == Some(bitmap.len())
            }
            None => false,
        }
    }

    /// Whether this segment carries a parallel `zone_map` section, i.e. it was
    /// written with the zone-map policy on and held at least one data block.
    /// The section powers predicate-based block-skip; absence means scans read
    /// every block. Read-transparent either way, so this is the only way to
    /// observe that a flush actually persisted zone maps.
    #[must_use]
    pub fn has_zone_map(&self) -> bool {
        self.regions.zone_map.is_some()
    }

    /// Whether this segment carries a parallel `seqno_bounds` section. Unlike
    /// the loaded map (best-effort at recover time — an unreadable section
    /// degrades it to empty), this reflects actual SECTION presence, so a
    /// source with rotted bounds still salvages into a copy WITH the section
    /// (the writer re-derives the ranges from the re-emitted entries).
    #[must_use]
    pub fn has_seqno_bounds(&self) -> bool {
        self.regions.seqno_bounds.is_some()
    }

    /// The fraction of this segment's rows masked by its positional
    /// delete-bitmap, as a percentage in `0..=100`, or `None` when the segment
    /// carries no delete-bitmap (nothing masked).
    ///
    /// Drives the density-based rewrite policy: a segment whose masked fraction
    /// has grown past the adaptive purge threshold is worth physically rewriting
    /// (dropping the masked rows and clearing the bitmap) rather than paying the
    /// merge-on-read mask cost on every scan.
    #[must_use]
    pub fn delete_density(&self) -> Option<u8> {
        let deleted = self.delete_bitmap().len();
        if deleted == 0 {
            return None;
        }
        let total = self.metadata.item_count.max(1);
        // Widen to u128 so `* 100` cannot overflow regardless of the (already
        // bounded) inputs; the quotient is clamped to the 0..=100 percentage range.
        let percent = (u128::from(deleted) * 100 / u128::from(total)).min(100);
        Some(u8::try_from(percent).unwrap_or(100))
    }

    /// Iterates every data-block handle in block-index (key) order; each item
    /// carries the block's last key. The salvage walk ([`crate::salvage`]) uses
    /// this to enumerate the blocks to recover one at a time; a corrupt index
    /// entry surfaces as an `Err` item rather than aborting the iteration.
    // std-only: the sole consumer is the std-gated salvage walk.
    #[cfg(feature = "std")]
    pub(crate) fn data_block_handles(&self) -> block_index::BlockIndexIterImpl {
        self.maintenance_index_walk()
    }

    /// Loads the columnar row group `handle` names and decodes the pages
    /// `want` selects, one batch per row page, each column in write order.
    ///
    /// The single place a columnar group becomes
    /// [`ColumnBatch`](crate::table::columnar::ColumnBatch)es; every read path
    /// that consumes one goes through here, so the page format is known to
    /// exactly one reader.
    ///
    /// Only the selected pages are read and decoded, after the directory
    /// ([`GroupRead::load`](crate::table::row_group::GroupRead::load)): a
    /// narrow projection over wide rows does not pay for the columns it
    /// skips, nor a read of a few rows for the row pages that do not hold
    /// them.
    ///
    /// `charge` applies to the read and to what decoding the pages copies out
    /// of them, which a counted read charges to the gather counter before the
    /// batch is judged: a group refused after a copy still made it.
    ///
    /// # Errors
    ///
    /// Any block's verification error, a malformed directory or page, or
    /// [`crate::Error::InvalidHeader`] for a zero-row group: no writer emits
    /// one.
    #[cfg(feature = "columnar")]
    pub(crate) fn load_row_group(
        &self,
        handle: &BlockHandle,
        want: &crate::table::row_group::PageWant<'_>,
        charge: ReadCharge,
    ) -> crate::Result<crate::table::row_group::RowPages> {
        let blocks = self
            .group_read(handle, charge, &LookupFd::default())
            .load(want)?;
        self.row_pages(&blocks, charge)
    }

    /// Every page of every row group, with what its values were encoded as:
    /// the per-page choice the writer made, laid out for a diagnosis of it.
    /// Reads each group whole and decodes no values. A row-major table has
    /// no pages and returns none.
    ///
    /// # Errors
    ///
    /// A block's verification error, or a malformed directory or page.
    #[cfg(all(feature = "columnar", feature = "std"))]
    #[doc(hidden)]
    pub fn column_page_encodings(&self) -> crate::Result<Vec<crate::inspect::PageEncoding>> {
        let mut out = Vec::new();
        if !self.metadata.columnar {
            return Ok(out);
        }
        for (group, handle) in (0u64..).zip(self.data_block_handles()) {
            let handle = handle?;
            let blocks = self
                .group_read(handle.as_ref(), ReadCharge::Untraced, &LookupFd::default())
                .load(&crate::table::row_group::PageWant::ALL)?;
            for page in blocks.page_encodings()? {
                out.push(crate::inspect::PageEncoding {
                    group,
                    column_id: page.entry.id.column_id,
                    row_page: page.entry.row_page,
                    rows: page.rows,
                    stored_len: page.entry.length,
                    expression: page.expression,
                    offsets_len: page.offsets_len,
                });
            }
        }
        Ok(out)
    }

    /// The context a read of the row group `handle` names needs, charged as
    /// `charge` says, the file taken through `fd`.
    #[cfg(feature = "columnar")]
    fn group_read<'a>(
        &'a self,
        handle: &'a BlockHandle,
        charge: ReadCharge,
        fd: &'a LookupFd,
    ) -> crate::table::row_group::GroupRead<'a> {
        crate::table::row_group::GroupRead {
            table_id: self.global_id(),
            path: &self.path,
            file_accessor: &self.file_accessor,
            cache: &self.cache,
            group: handle,
            compression: self.metadata.data_block_compression,
            encryption: self.encryption.as_deref(),
            ecc: self.metadata.ecc_params,
            #[cfg(zstd_any)]
            zstd_dict: self.zstd_dictionary.as_deref(),
            heal_hints: self.heal_hints.get().map(AsRef::as_ref),
            #[cfg(feature = "metrics")]
            metrics: &self.metrics,
            charge,
            budget: self.read_budget(),
            pace: None,
            fd,
        }
    }

    /// `blocks` decoded into row pages, what decoding copied charged as
    /// `charge` says.
    #[cfg(feature = "columnar")]
    #[cfg_attr(
        not(feature = "metrics"),
        expect(clippy::unused_self, reason = "the gather counter is behind `metrics`")
    )]
    fn row_pages(
        &self,
        blocks: &crate::table::row_group::RowGroupBlocks,
        charge: ReadCharge,
    ) -> crate::Result<crate::table::row_group::RowPages> {
        let mut copied = 0usize;
        let pages = blocks.to_row_pages(&mut copied);
        #[cfg(feature = "metrics")]
        if charge.is_counted() {
            self.metrics.record_gather(copied);
        }
        #[cfg(not(feature = "metrics"))]
        let _ = (copied, charge);
        pages
    }

    fn load_block(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
        compression: CompressionType,
        #[cfg(zstd_any)] zstd_dict: Option<&crate::compression::ZstdDictionary>,
        fd: &LookupFd,
    ) -> crate::Result<Block> {
        self.load_block_charged(
            handle,
            block_type,
            compression,
            #[cfg(zstd_any)]
            zstd_dict,
            ReadCharge::Foreground,
            None,
            fd,
        )
    }

    /// [`Self::load_block`] charged as `charge` says, for a read that is not a
    /// caller's, and told to `pace` when given.
    #[cfg_attr(
        zstd_any,
        expect(
            clippy::too_many_arguments,
            reason = "the block's read context: handle, role, codec, dictionary, charge, pacer and file"
        )
    )]
    fn load_block_charged(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
        compression: CompressionType,
        #[cfg(zstd_any)] zstd_dict: Option<&crate::compression::ZstdDictionary>,
        charge: ReadCharge,
        pace: Option<&dyn crate::table::util::ReadPacer>,
        fd: &LookupFd,
    ) -> crate::Result<Block> {
        crate::table::util::load_block_paced(
            self.global_id(),
            &self.path,
            &self.file_accessor,
            &self.cache,
            handle,
            block_type,
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            zstd_dict,
            self.heal_hints.get().map(AsRef::as_ref),
            #[cfg(feature = "metrics")]
            &self.metrics,
            charge,
            pace,
            fd,
        )
    }

    /// Loads a data-carrying block STRAIGHT FROM THE FILE, bypassing the
    /// block cache in both directions, for the semantic reconcile gates: a
    /// block read before an on-disk alteration leaves its pristine copy
    /// cached, and a gate served that stale original would judge bytes
    /// other than the ones the digest refresh is about to trust. Reuses a
    /// cached file descriptor without promoting it, opens one privately on a
    /// miss, and never consults or populates the block cache (the cold
    /// verification reads must not evict the live working set either).
    /// Decodes under the table's data-block codec context, so
    /// it fits every gate that walks `block_index` (Data or Columnar role).
    // Compiled under no_std alongside its `verify_kv_checksums` consumer,
    // which is itself dead there (the verify/scrub caller is std-gated).
    #[cfg_attr(
        not(feature = "std"),
        expect(
            dead_code,
            reason = "gate-only loader; the verify/scrub consumers are std-gated"
        )
    )]
    fn load_block_from_disk(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
    ) -> crate::Result<(Block, crate::Slice)> {
        let fd = self
            .file_accessor
            .peek_or_open_table(&self.global_id(), &self.path)?;
        let compression = self.compression_for_role(block_type);
        let transform = crate::table::util::build_block_transform(
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.dictionary_for_role(block_type),
        )?;
        // The two halves of ONE read: the frame as the writer compressed it,
        // and the block that frame decodes to. Gates that cross-check the
        // frame's inner structure (the block-layout boundaries) used to reach
        // for it with a second pread of the same bytes.
        let (header, frame, _status, _recovery) = Block::read_verified_payload(
            fd.as_ref(),
            *handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type,
                dict_id: compression.dict_id(),
                window_log: 0,
            },
            &transform,
            || {},
        )?;
        // Swap-defence role check, mirroring `load_block`. Before the
        // decompress: a block that is not what the index claims has no
        // business being handed to a codec.
        if header.block_type != block_type {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                header.block_type.into(),
            )));
        }
        let data = Block::decompress_payload(&header, frame.clone(), &transform, &mut 0)?;
        Ok((Block { header, data }, frame))
    }

    /// Frames the block starting at `offset` by reading its HEADER through an
    /// already-open `file`: the on-disk span is header + payload + parity
    /// trailer (SST blocks carry no `block_flags` byte, so the trailer is sized
    /// from the per-SST descriptor scheme). The writer emits blocks
    /// back-to-back, making the physical tiling ground truth: the salvage gap
    /// walk frames index-omitted bytes with this, and the TLI mirror gate
    /// compares each decoded handle against the frame its header derives. A
    /// header that fails to decode, or a span leaving `section_end`, means the
    /// bytes are not frameable as a block.
    ///
    /// Takes an open handle because every caller scans many offsets (the
    /// salvage resync loop steps one byte at a time, since block starts are
    /// not aligned), and one `open` per probe would dominate the walk.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] on an undecodable header or an
    /// out-of-section span; any I/O error from the read.
    #[cfg(feature = "std")]
    pub(crate) fn probe_block_handle_in(
        &self,
        file: &dyn crate::fs::FsFile,
        offset: u64,
        section_end: u64,
    ) -> crate::Result<BlockHandle> {
        use crate::coding::Decode;
        use crate::table::block::Header;

        // Positional read of the largest possible header (block_flags-bearing
        // types are one byte longer than the SST minimum); a short read only
        // matters if it cuts into the bytes `decode_from` actually consumes.
        let mut buf = [0u8; Header::MAX_LEN];
        let got = file.read_at(&mut buf, offset)?;
        let mut cursor = buf.get(..got).ok_or(crate::Error::InvalidHeader(
            "block header read out of bounds",
        ))?;
        let header = Header::decode_from(&mut cursor)?;
        let header_len = Header::header_len(header.block_type) as u64;
        let parity_len = self.metadata.ecc_params.map_or(0, |scheme| {
            u64::from(crate::table::block::expected_parity_len(
                header.data_length,
                scheme,
            ))
        });
        let total = header_len
            .checked_add(u64::from(header.data_length))
            .and_then(|t| t.checked_add(parity_len))
            .ok_or(crate::Error::InvalidHeader("block span overflows the file"))?;
        let end = offset
            .checked_add(total)
            .ok_or(crate::Error::InvalidHeader("block span overflows the file"))?;
        if end > section_end {
            return Err(crate::Error::InvalidHeader(
                "block extends past its section",
            ));
        }
        let size = u32::try_from(total)
            .map_err(|_| crate::Error::InvalidHeader("block span exceeds the block size limit"))?;
        Ok(BlockHandle::new(BlockOffset(offset), size))
    }

    /// Frames the DATA UNIT starting at `offset` — what one data index entry
    /// covers — from the bytes alone, as [`Self::probe_block_handle_in`] frames
    /// one block.
    ///
    /// A row-major table's unit is one block. A columnar table's is a row
    /// group, and its extent is not in the first block's header: that header
    /// is the directory's, which frames only itself. So the directory is read
    /// and the group's extent is its own length, every page it lists and the
    /// zone block it counts.
    /// Framing the directory alone would make a group look like a run of
    /// unrelated blocks to every walk that tiles the data section by frames.
    ///
    /// # Errors
    ///
    /// As [`Self::probe_block_handle_in`]; for a columnar table also when the
    /// block at `offset` is not a page directory, or the directory is
    /// unreadable or reaches past `section_end`.
    #[cfg(feature = "std")]
    pub(crate) fn probe_data_unit_in(
        &self,
        file: &dyn crate::fs::FsFile,
        offset: u64,
        section_end: u64,
    ) -> crate::Result<BlockHandle> {
        let first = self.probe_block_handle_in(file, offset, section_end)?;
        if !self.metadata.columnar {
            return Ok(first);
        }
        #[cfg(feature = "columnar")]
        {
            let directory_block = Block::from_file(
                file,
                first,
                crate::table::block::BlockIdentity {
                    table_id: self.id(),
                    block_type: BlockType::ColumnPageDirectory,
                    dict_id: 0,
                    window_log: 0,
                },
                &crate::table::util::build_block_transform(
                    CompressionType::None,
                    self.encryption.as_deref(),
                    self.metadata.ecc_params,
                    #[cfg(zstd_any)]
                    None,
                )?,
            )?;
            if directory_block.header.block_type != BlockType::ColumnPageDirectory {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    directory_block.header.block_type.into(),
                )));
            }
            let directory =
                crate::table::column_page::PageDirectory::decode(&directory_block.data)?;
            let size = directory
                .group_len(first.size())
                .ok_or(crate::Error::InvalidHeader("row group span overflows"))?;
            if offset
                .checked_add(u64::from(size))
                .is_none_or(|end| end > section_end)
            {
                return Err(crate::Error::InvalidHeader(
                    "row group extends past its section",
                ));
            }
            // A group found by its frame has no index entry to name it; the
            // tag its own directory carries is the only one there is, and the
            // pages' stamps are still checked against it when they decode.
            // A zero tag names no group, and every read then refuses it.
            let row_group = core::num::NonZeroU64::new(directory.group_tag()).and_then(|tag| {
                Some(crate::table::index_block::RowGroupRef {
                    tag,
                    directory_len: core::num::NonZeroU32::new(first.size())?,
                    head_zones_len: directory.pages_start(),
                })
            });
            Ok(BlockHandle::new(BlockOffset(offset), size).with_row_group(row_group))
        }
        #[cfg(not(feature = "columnar"))]
        {
            Err(crate::Error::FeatureUnsupported("columnar"))
        }
    }

    /// Loads (and, for columnar SSTs, reconstructs + delete-masks) a data block.
    /// Returns `Ok(None)` when a columnar block is wholly deleted by the
    /// positional mask, so the caller treats it as carrying no keys.
    ///
    /// `pub(crate)` so the repair tests can load one block of a table they
    /// damaged; the salvage walk reads through its own loader,
    /// [`Table::salvage_load_block`].
    ///
    /// The file is taken through `fd`, which the lookup's other block reads
    /// share.
    pub(crate) fn load_data_block(
        &self,
        handle: &BlockHandle,
        fd: &LookupFd,
    ) -> crate::Result<Option<DataBlock>> {
        self.load_data_block_paced(handle, ReadCharge::Foreground, None, fd)
    }

    /// [`Self::load_data_block`] for maintenance that sizes a rewrite of the
    /// table: not counted as a read, and told to `pace`, the rewrite's own,
    /// as the rewrite's reads are.
    #[cfg(feature = "std")]
    pub(crate) fn load_data_block_for_maintenance(
        &self,
        handle: &BlockHandle,
        pace: &dyn crate::table::util::ReadPacer,
    ) -> crate::Result<Option<DataBlock>> {
        self.load_data_block_paced(
            handle,
            ReadCharge::Maintenance,
            Some(pace),
            &LookupFd::default(),
        )
    }

    /// [`Self::load_data_block`] charged as `charge` says, for a read that is
    /// not a caller's.
    fn load_data_block_charged(
        &self,
        handle: &BlockHandle,
        charge: ReadCharge,
    ) -> crate::Result<Option<DataBlock>> {
        self.load_data_block_paced(handle, charge, None, &LookupFd::default())
    }

    /// [`Self::load_data_block_charged`], told to `pace` when given, the file
    /// taken through `fd`.
    fn load_data_block_paced(
        &self,
        handle: &BlockHandle,
        charge: ReadCharge,
        pace: Option<&dyn crate::table::util::ReadPacer>,
        fd: &LookupFd,
    ) -> crate::Result<Option<DataBlock>> {
        // Columnar SSTs store each data block as a PAX `ColumnBatch`; reconstruct
        // the row entries on load so every row read path works unchanged.
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            return self.load_columnar_data_block(handle, charge, pace, fd);
        }
        // `from_loaded` transparently strips the per-KV checksum footer when
        // this SST carries one. Footer presence is a per-SST property
        // (`kv_checksum_algo`), not a per-block header flag — data blocks omit
        // the block_flags byte — so the descriptor supplies it here.
        let has_kv_footer = self.metadata.kv_checksum_algo.is_some();
        self.load_block_charged(
            handle,
            BlockType::Data,
            self.metadata.data_block_compression,
            #[cfg(zstd_any)]
            self.zstd_dictionary.as_deref(),
            charge,
            pace,
            fd,
        )
        .and_then(|block| DataBlock::from_loaded(block, has_kv_footer))
        .map(Some)
        .map_err(|e| self.classify_excised(handle, e, charge))
    }

    /// Re-reports a failed block load as [`crate::Error::Excised`] when the
    /// block's bytes are physically absent — an all-zero extent, the signature
    /// of a hole punch — rather than damaged.
    ///
    /// Tight-space reclaim punches consumed extents in place, so a table can
    /// legitimately survive with intact blocks around a hole. A read that
    /// lands in the hole is a permanent loss of exactly those rows, and the
    /// distinction matters to the caller: rotted bytes may be healable and
    /// are worth retrying or scrubbing, an excised extent never is. The probe
    /// runs ONLY on the failure path, so a healthy read pays nothing for it,
    /// and it needs no recorded state — the zeros identify themselves, which
    /// is what lets an in-place excision survive any crash unrecorded.
    #[cfg(feature = "std")]
    fn classify_excised(
        &self,
        handle: &BlockHandle,
        err: crate::Error,
        charge: ReadCharge,
    ) -> crate::Error {
        // A transient / positioned-read failure is not a verdict about the
        // bytes: leave it exactly as it is so the caller can still retry.
        if matches!(err, crate::Error::Io(_)) {
            return err;
        }
        let Ok(file) = self.fs.open(&self.path, &FsOpenOptions::new().read(true)) else {
            return err;
        };
        // The probe's reads are this read path's too, so they are charged
        // like the load that failed.
        #[cfg(feature = "metrics")]
        let mut on_read = |len: u64| {
            if charge.is_counted() {
                crate::table::util::record_block_read(&self.metrics, BlockType::Data, len);
            }
        };
        #[cfg(not(feature = "metrics"))]
        let mut on_read = |_: u64| {
            let _ = charge;
        };
        match Self::block_is_zeroed_in(&*file, handle, &mut on_read) {
            Ok(true) => crate::Error::Excised {
                offset: handle.offset().0,
            },
            // Not zeroed, or the probe itself failed: the original verdict
            // stands — never let a probe failure mask the real error.
            Ok(false) | Err(_) => err,
        }
    }

    /// No-std builds have no `Fs` open on this path; the original error stands.
    #[cfg(not(feature = "std"))]
    const fn classify_excised(
        &self,
        _handle: &BlockHandle,
        err: crate::Error,
        _charge: ReadCharge,
    ) -> crate::Error {
        err
    }

    /// Loads a columnar data block and reconstructs it as a row-major
    /// [`DataBlock`]: decode the `ColumnBatch`, rebuild the entries, and
    /// re-encode them row-major in memory so the existing point-read / iterator
    /// machinery is reused verbatim. The native column-projection read path
    /// (decode only the referenced columns) is a later optimization.
    ///
    /// Returns `Ok(None)` when the positional delete-bitmap deletes every row of
    /// the block, so the caller treats it as carrying no keys.
    #[cfg(feature = "columnar")]
    fn load_columnar_data_block(
        &self,
        handle: &BlockHandle,
        charge: ReadCharge,
        pace: Option<&dyn crate::table::util::ReadPacer>,
        fd: &LookupFd,
    ) -> crate::Result<Option<DataBlock>> {
        let blocks = crate::table::row_group::GroupRead {
            pace,
            ..self.group_read(handle, charge, fd)
        }
        .load(&crate::table::row_group::PageWant::ALL)?;
        self.columnar_data_block_from(handle, &blocks, charge)
    }

    /// The row-major data block of the row group `handle` names, rebuilt from
    /// its loaded `blocks` and delete-masked: `None` when the mask removes
    /// every row.
    #[cfg(feature = "columnar")]
    fn columnar_data_block_from(
        &self,
        handle: &BlockHandle,
        blocks: &crate::table::row_group::RowGroupBlocks,
        charge: ReadCharge,
    ) -> crate::Result<Option<DataBlock>> {
        let batch = self.row_pages(blocks, charge)?.batches;
        let restart = self.metadata.data_block_restart_interval;
        // The segment has materialized deletes and this block has a recorded
        // start position: drop the deleted rows during reconstruction. The
        // start-row map is built at open from the zone map (every block), so
        // an unmapped block is unreachable; it falls through to the whole-block
        // reconstruction below rather than masking against the wrong positions.
        let mut values = 0usize;
        let rebuilt = if let Some(&start) = self
            .delete_block_starts
            .as_ref()
            .and_then(|starts| starts.get(&handle.offset().0))
        {
            DataBlock::from_column_batch_masked(
                batch,
                restart,
                &self.delete_bitmap,
                start,
                &mut values,
            )
        } else {
            // No materialized deletes (or, unreachably, an unmapped block):
            // reconstruct the whole block.
            DataBlock::from_column_batch(batch, restart, &mut values).map(Some)
        };
        // Two gathers, each charged at the size of what it built: the values
        // rebuilt from sub-columns (none when they are views), and the
        // row-major block encoded from the rows. The first is charged before
        // the result is judged: a block refused after it still did it.
        #[cfg(feature = "metrics")]
        if charge.is_counted() {
            self.metrics.record_gather(values);
        }
        #[cfg(not(feature = "metrics"))]
        let _ = (values, charge);
        let rebuilt = rebuilt?;
        #[cfg(feature = "metrics")]
        if let Some(rebuilt) = &rebuilt
            && charge.is_counted()
        {
            self.metrics.record_gather(rebuilt.inner.data.len());
        }
        Ok(rebuilt)
    }

    /// Loads a columnar data block as a delete-masked
    /// [`ColumnBatch`](crate::table::columnar::ColumnBatch), preserving its
    /// per-field value sub-columns (and per-row seqnos) instead of reconstructing
    /// rows. Salvage re-emits the result verbatim so a recovered columnar SST
    /// keeps its sub-columns and MVCC versions; `Ok(None)` when the positional
    /// delete-bitmap removes every row of the block.
    ///
    /// `pub(crate)` for the salvage walk ([`crate::salvage`]). Salvage is
    /// maintenance, so nothing here is charged to the gather counter.
    #[cfg(feature = "columnar")]
    pub(crate) fn load_columnar_block_masked(
        &self,
        handle: &BlockHandle,
    ) -> crate::Result<Option<crate::table::columnar::ColumnBatch>> {
        // `load_row_group` already refuses a zero-row group: a real writer
        // never emits one, and a caller counting it as recovered would
        // misreport an unrecovered group as salvaged.
        // Salvage re-emits the group through a writer that takes it whole and
        // cuts its own row pages, so the pages are joined here.
        let batch = self
            .load_row_group(
                handle,
                &crate::table::row_group::PageWant::ALL,
                ReadCharge::Maintenance,
            )?
            .into_batch()?;
        let Some(start) = self
            .delete_block_starts
            .as_ref()
            .and_then(|starts| starts.get(&handle.offset().0))
            .copied()
        else {
            // No materialized deletes: the whole block is live.
            return Ok(Some(batch));
        };
        // Drop positionally-deleted rows: this block's rows occupy global
        // positions `[start, start + row_count)` in write order. A corrupt zone
        // map can make `start` large enough that `start + i` overflows the u32
        // row-position space and wraps back to the start of the bitmap, masking
        // unrelated rows. Fail closed on overflow: the salvage walk drops and
        // re-emits this block as corrupt rather than applying deletes at wrong
        // positions.
        let keep: alloc::vec::Vec<bool> = (0..batch.row_count)
            .map(|i| {
                let pos = start.checked_add(i).ok_or(crate::Error::InvalidHeader(
                    "columnar delete position overflow",
                ))?;
                Ok(!self.delete_bitmap.contains(pos))
            })
            .collect::<crate::Result<_>>()?;
        let masked = crate::table::columnar_predicate::filter_batch(&batch, &keep)?;
        if masked.row_count == 0 {
            Ok(None)
        } else {
            Ok(Some(masked))
        }
    }

    /// Cross-checks the positional delete mask against the ACTUAL per-block
    /// row counts. `delete_block_starts` is derived from the zone map, and a
    /// zone map that decodes but carries wrong counts (a checksum-repatched
    /// tamper) shifts every later block's claimed start — the mask would then
    /// delete the WRONG rows, silently. Walks the data blocks in index order
    /// and requires each block's claimed start to equal the running sum of
    /// actual decoded row counts. An UNREADABLE block fails the verification
    /// outright: its actual count is unknowable, and trusting the zone map's
    /// claim for it would let a repatched count on exactly that block shift
    /// every later mask undetected. Trivially `true` when the segment has no
    /// materialized deletes.
    ///
    /// `pub(crate)` for the salvage walk ([`crate::salvage`]), which must not
    /// mask against unverified positions.
    ///
    /// # Errors
    ///
    /// Propagates an ENVIRONMENTAL failure from an index / block read (see
    /// [`crate::Error::is_environmental`]): a flaky device, a refused mount, a
    /// missing key or dictionary. `Ok(false)` is reserved for a STRUCTURAL
    /// failure (a reordered index, a count mismatch, an undecodable or zero-row
    /// block): folding a fixable-context fault into `false` would classify it
    /// as a persistent unpositionable mask, and — with the default
    /// `allow_delete_resurrection == false` — abort salvage, letting
    /// `repair_with_salvage` rebuild the manifest WITHOUT a table a retry (or
    /// the right key) could have recovered faithfully.
    #[cfg(feature = "columnar")]
    pub(crate) fn delete_positions_verified(&self) -> crate::Result<bool> {
        let Some(starts) = self.delete_block_starts.as_deref() else {
            // No materialized deletes: there is nothing to position.
            return Ok(true);
        };
        let mut cumulative: u32 = 0;
        // Anchor the walk to PHYSICAL block order. `delete_block_starts` is built
        // by walking this same index, so a forged TLI that REORDERS the handles
        // rebuilds the starts in that reordered sequence and self-validates
        // against them, yet the bitmap positions were assigned in the writer's
        // physical block order, so the salvage walk (which sorts blocks by
        // offset) would mask against the wrong starts. Requiring strictly
        // increasing offsets rejects the reorder: a genuine index is always in
        // offset order (the writer emits blocks back-to-back).
        let mut prev_offset: Option<u64> = None;
        for keyed in self.maintenance_index_walk() {
            let keyed = match keyed {
                Ok(keyed) => keyed,
                // Only an ENVIRONMENTAL read propagates: a retry, the right key,
                // or the right dictionary could verify the mask, and answering
                // `Ok(false)` would let the caller fail the salvage closed over
                // an intact table. A read that fails on the DATA makes every
                // later position unverifiable, so degrade to an unpositionable
                // mask (`Ok(false)`) and let the resurrection opt-in decide.
                Err(e) if e.is_environmental() => return Err(e),
                Err(_) => return Ok(false),
            };
            let offset = keyed.offset().0;
            if prev_offset.is_some_and(|prev| offset <= prev) {
                // Out-of-order (or duplicate) offset: the index was reordered, so
                // the physical positions cannot be trusted.
                return Ok(false);
            }
            prev_offset = Some(offset);
            if starts.get(&offset) != Some(&cumulative) {
                return Ok(false);
            }
            let handle = *keyed.as_ref();
            // FULLY decode the group rather than trusting the directory's row
            // count: a checksum-repatched tamper can keep that field intact
            // while breaking a page's column framing. The salvage walk would
            // drop such a group as undecodable — but its ACTUAL row count is
            // then just as unknowable as an unreadable group's, so accepting
            // the claimed count here would let the mask land on unproven
            // positions for every later group. Decoding checks every page
            // against that count, so a group that decodes has proved it.
            let pages = match self.load_row_group(
                &handle,
                &crate::table::row_group::PageWant::ALL,
                ReadCharge::Maintenance,
            ) {
                Ok(pages) => pages,
                // Only an ENVIRONMENTAL read propagates (see the index arm
                // above); a load or decode that fails on the DATA leaves the
                // group's actual count unknowable, so every later position is
                // unverifiable — degrade to an unpositionable mask
                // (`Ok(false)`) rather than trust the (potentially tampered)
                // zone-map claim for it, and let the resurrection opt-in decide.
                Err(e) if e.is_environmental() => return Err(e),
                Err(_) => return Ok(false),
            };
            // A ZERO-ROW batch is malformed input (a real writer never emits
            // an empty block) and the salvage walk DROPS it — so accepting it
            // here (a tampered zone map can claim 0 for exactly that block,
            // keeping the chain self-consistent) would verify positions the
            // bitmap was never built against for every later block. Reject
            // it like the rest of the salvage pipeline does.
            let advance = pages.row_count();
            if advance == 0 {
                return Ok(false);
            }
            // `wrapping_add` matches how the open path builds the starts map,
            // so the comparison chain stays consistent (the salvage read mask
            // separately rejects positions that would overflow).
            cumulative = cumulative.wrapping_add(advance);
        }
        Ok(true)
    }

    /// Salvage helper: load one data block recovery-aware and, when it reads back
    /// cleanly, also capture its raw on-disk bytes for a verbatim copy.
    ///
    /// Bypasses the block cache so the returned recovery status reflects THIS read
    /// of the medium (a cached block hides whether the on-disk bytes needed ECC
    /// repair). On a clean read ([`verbatim`](SalvageBlock::verbatim) is `Some`),
    /// the salvage walk byte-copies the raw bytes into the recovered SST instead of
    /// decoding + re-encoding the block; on an ECC-recovered read (`None`) the
    /// faulty on-disk bytes must not be propagated, so the caller re-encodes the
    /// healed payload in [`block`](SalvageBlock::block) instead.
    ///
    /// `pub(crate)` for the salvage walk ([`crate::salvage`]).
    pub(crate) fn salvage_load_block(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
    ) -> crate::Result<SalvageBlock> {
        let table_id = self.global_id();
        let (fd, _) = self
            .file_accessor
            .get_or_open_table(&table_id, &self.path)?;
        let compression = self.compression_for_role(block_type);
        let transform = crate::table::util::build_block_transform(
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.dictionary_for_role(block_type),
        )?;
        let (block, status, recovery) = crate::table::block::Block::from_file_with_recovery(
            fd.as_ref(),
            *handle,
            crate::table::block::BlockIdentity {
                table_id: table_id.table_id(),
                block_type,
                dict_id: compression.dict_id(),
                window_log: 0,
            },
            &transform,
        )?;
        // A wrong block type means a swapped / corrupt index entry pointed us at
        // the wrong bytes; surface it rather than salvage the wrong block.
        if block.header.block_type != block_type {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        // A table whose ECC descriptor this build cannot interpret still reads
        // cleanly (`EccStatus::Unrecognized`, `recovery.is_none()`), but its raw
        // bytes carry an opaque parity trailer the salvage writer's mirrored ECC
        // (`ecc_params = None`) does not account for. A verbatim copy of those
        // bytes would fail the writer's on-disk-size check and abort the whole
        // salvage, so force the re-encode path (which emits a trailer-free block
        // from the decoded payload) for such tables. The same applies to a
        // RECOGNIZED scheme on a build without `page_ecc`: the salvage writer
        // mirrors ECC as `None` there (it cannot emit parity), so raw bytes
        // with a trailer must be re-encoded trailer-free, not byte-copied.
        let ecc_verbatim_ok = cfg!(feature = "page_ecc") || self.metadata.ecc_params.is_none();
        // Clean read: capture the raw on-disk bytes (and inner layout) for a
        // verbatim copy. A second pread of a cold block costs far less than the
        // re-compression the copy avoids.
        //
        // `Err` from this function is reserved for the initial VERIFIED read:
        // by this point that read has already produced a recoverable decoded
        // block, so ANY failure of the re-read — a transient I/O error or a
        // corrupt header, same as a checksum / parity mismatch below — must
        // not drop the block; it just disqualifies the byte-copy and falls
        // back to re-encoding the verified payload (`verbatim = None`).
        let capture_verbatim = || -> Option<VerbatimCopy> {
            use crate::coding::Decode;
            let raw =
                crate::file::read_exact(fd.as_ref(), *handle.offset(), handle.size() as usize)
                    .ok()?;
            let header = crate::table::block::Header::decode_from(&mut &raw[..]).ok()?;
            let layout = self.inner_block_layout(handle.offset().0);
            // A recorded MULTI-INNER layout is the untrusted `block_layout`
            // section itself: a checksum-consistent forge of it routes an
            // otherwise-readable zstd SST through salvage, and copying the block
            // verbatim would re-emit the same unauthenticated inner boundaries,
            // so partial range reads keep omitting keys even though salvage
            // reports success. Disqualify verbatim for such blocks; the re-encode
            // path below rebuilds the frame from the verified decoded payload and
            // records a fresh, self-consistent layout. Single-inner blocks (the
            // common case, empty layout) are unaffected.
            if !layout.is_empty() {
                return None;
            }
            // The bytes COPIED are this second read, not the verified first
            // one, so validate this exact frame before marking it
            // verbatim-safe (a transient fault or concurrent mutation between
            // the reads must not persist unchecked bytes):
            // - the re-read header must equal the verified read's header;
            // - the re-read payload must hash to the header's stored checksum
            //   (the checksum covers the on-disk payload bytes uniformly —
            //   pre-decrypt, pre-decompress);
            // - for an ECC table, the parity trailer must match freshly
            //   computed parity (a clean payload checksum never validates the
            //   trailer — parity is only consulted on a mismatch — so bit rot
            //   confined to the trailer otherwise reads as a clean block).
            // Any mismatch falls back to the re-encode path, which emits the
            // VERIFIED first read's decoded payload with fresh framing.
            let header_len = crate::table::block::Header::header_len(header.block_type);
            // checked_add: a forged/rotted data_length can overflow the
            // payload-end sum on 32-bit targets; overflow = not verbatim-safe.
            let payload_checksum_ok = header_len
                .checked_add(header.data_length as usize)
                .and_then(|payload_end| raw.get(header_len..payload_end))
                .is_some_and(|payload| {
                    crate::hash::hash128(payload)
                        == header
                            .payload_checksum(crate::table::block::ChecksumAt::block(
                                table_id.table_id(),
                                block_type,
                                *handle.offset(),
                            ))
                            .into_u128()
                });
            (header == block.header
                && payload_checksum_ok
                && self.raw_block_parity_verifies(&raw, &header))
            .then(|| (raw.to_vec(), header, layout))
        };
        // The PER-BLOCK status must be Ok too: `EccStatus::Unrecognized` means
        // the frame carried trailing bytes the transform could not attribute
        // (e.g. an over-sized forged index handle leaking the next section's
        // bytes into the read) — the payload verified, but the raw frame is
        // longer than the header's on-disk size and a verbatim copy would be
        // rejected by the writer, dropping a recoverable block. Re-encode the
        // verified payload instead.
        let verbatim = if recovery.is_none()
            && status == crate::table::block::EccStatus::Ok
            && !self.metadata.ecc_unrecognized
            && ecc_verbatim_ok
        {
            capture_verbatim()
        } else {
            None
        };
        Ok(SalvageBlock {
            block,
            verbatim,
            ecc_recovered: recovery.is_some(),
        })
    }

    /// Salvage helper for a columnar table's entry: loads every block of the
    /// row group through [`Self::salvage_load_block`].
    ///
    /// The group may be byte-copied only when EVERY block in it qualified for
    /// a verbatim copy on its own. One ECC-healed page makes the whole group's
    /// raw bytes unsafe to propagate, because they are one unit on disk and
    /// one index entry in the copy; the caller then re-encodes the decoded
    /// batch instead. When they all qualify, their raw frames — adjacent by
    /// construction, as the extent check proved — ARE the group's bytes.
    ///
    /// `pub(crate)` for the salvage walk ([`crate::salvage`]).
    ///
    /// # Errors
    ///
    /// A block's verified read failing, or a directory that cannot be read or
    /// does not fill the group: without it the pages cannot be located, so
    /// the group is lost as a unit, exactly as a columnar block was.
    #[cfg(all(feature = "columnar", feature = "std"))]
    pub(crate) fn salvage_load_row_group(
        &self,
        group: &BlockHandle,
    ) -> crate::Result<SalvageRowGroup> {
        let mut blocks = self.data_unit_blocks(group)?.into_iter();
        let Some((directory_handle, directory_role)) = blocks.next() else {
            return Err(crate::Error::InvalidHeader(
                "columnar: row group has no directory",
            ));
        };
        let directory = self.salvage_load_block(&directory_handle, directory_role)?;
        let decoded = crate::table::column_page::PageDirectory::decode(&directory.block.data)?;

        let mut ecc_recovered = directory.ecc_recovered;
        let mut verbatim = directory
            .verbatim
            .map(|(raw, header, _)| (raw, u64::from(header.uncompressed_length)));
        let mut pages = alloc::vec::Vec::with_capacity(decoded.entries().len());
        // The zone blocks in the order they lie: the head one, then the rest.
        let listed: alloc::vec::Vec<crate::table::column_page::ZoneBlock> = decoded
            .head_zone_block()
            .into_iter()
            .chain(decoded.zone_blocks().iter().copied())
            .collect();
        let mut zone_blocks = listed.iter();
        for (handle, role) in blocks {
            let block = self.salvage_load_block(&handle, role)?;
            ecc_recovered |= block.ecc_recovered;
            // Every block of the group, the zone blocks included, goes into
            // the verbatim copy: the copy is the group whole or nothing.
            verbatim = match (verbatim, block.verbatim) {
                (Some((mut raw, uncompressed)), Some((block_raw, header, _))) => {
                    raw.extend_from_slice(&block_raw);
                    Some((raw, uncompressed + u64::from(header.uncompressed_length)))
                }
                _ => None,
            };
            if role == BlockType::ColumnZones {
                // Decoded against the column the directory files it under, so
                // a zone block that verifies as a block but not as that
                // column's zones fails the group here, not in a later read.
                let column_id =
                    zone_blocks
                        .next()
                        .map(|z| z.column_id)
                        .ok_or(crate::Error::InvalidHeader(
                            "columnar: a zone block the directory does not list",
                        ))?;
                decoded.decode_zone_block(column_id, &block.block.data)?;
            } else {
                pages.push(block.block);
            }
        }
        Ok(SalvageRowGroup {
            group: crate::table::row_group::RowGroupBlocks::whole(
                alloc::sync::Arc::new(decoded),
                pages,
            ),
            verbatim,
            ecc_recovered,
        })
    }

    /// Whether `raw`'s parity trailer matches freshly computed parity over its
    /// payload — the verbatim-copy eligibility check for a block of an
    /// ECC-carrying table (see [`Self::salvage_load_block`]). Trivially `true`
    /// for a table without a recognized ECC scheme; a build without `page_ecc`
    /// never reaches this for an ECC table (the caller's gate already routes
    /// those to the re-encode path).
    #[cfg_attr(
        not(feature = "page_ecc"),
        expect(
            clippy::unused_self,
            reason = "without page_ecc the caller's gate excludes ECC tables, so there is no parity to check"
        )
    )]
    fn raw_block_parity_verifies(&self, raw: &[u8], header: &crate::table::block::Header) -> bool {
        #[cfg(feature = "page_ecc")]
        {
            matches!(self.raw_block_parity_delta(raw, header), Ok(None))
        }
        #[cfg(not(feature = "page_ecc"))]
        {
            let _ = (raw, header);
            true
        }
    }

    /// Compares `raw`'s parity trailer against freshly computed parity over
    /// its payload. `Ok(None)` — the trailer matches (or the table carries no
    /// recognized ECC scheme); `Ok(Some(fresh))` — MISMATCH, `fresh` is the
    /// parity the trailer should hold (the in-place heal persists it);
    /// `Err(())` — the frame is inconsistent or the encoder rejected the
    /// shape, so the trailer is unverifiable.
    #[cfg(feature = "page_ecc")]
    fn raw_block_parity_delta(
        &self,
        raw: &[u8],
        header: &crate::table::block::Header,
    ) -> Result<Option<alloc::vec::Vec<u8>>, ()> {
        let Some(params) = self.metadata.ecc_params else {
            return Ok(None);
        };
        let header_len = crate::table::block::Header::header_len(header.block_type);
        // Checked: `data_length` comes from a re-read header, so a forged
        // value must fail as "unverifiable", never wrap (32-bit `usize`).
        let Some(payload_end) = header_len.checked_add(header.data_length as usize) else {
            return Err(());
        };
        // Treat any frame inconsistency as "unverifiable" rather than panicking.
        let (Some(payload), Some(trailer)) =
            (raw.get(header_len..payload_end), raw.get(payload_end..))
        else {
            return Err(());
        };
        let fresh = match params {
            crate::table::block::EccParams::Secded => crate::secded::encode_block_parity(payload),
            crate::table::block::EccParams::Shard { .. } => {
                let (ds, ps) = params.as_shards();
                match crate::ecc::encode_parity(payload, ds, ps) {
                    Ok(p) => p,
                    Err(_) => return Err(()),
                }
            }
        };
        // The heal writes `fresh` back AT the trailer's offset, so the frame
        // must hold EXACTLY that many trailer bytes: a shorter (or longer)
        // on-disk trailer means the frame is malformed, and "healing" it
        // would write past the frame's end into the next block's bytes,
        // breaking the size-preserving heal contract. Unverifiable, not
        // healable.
        if trailer.len() != fresh.len() {
            return Err(());
        }
        if trailer == fresh {
            Ok(None)
        } else {
            Ok(Some(fresh))
        }
    }

    /// The inner-zstd block layout (cumulative decompressed end offsets) for the
    /// data block at `offset`, or empty when the block has a single inner block
    /// (the common case) — and always, on a build without zstd, where data blocks
    /// never split. Salvage's verbatim copy passes this through so a multi-inner
    /// block keeps its layout at its new file offset (the offsets are
    /// decompressed-space and block-relative, so they stay valid after the move).
    #[cfg_attr(
        not(feature = "zstd"),
        expect(
            clippy::unused_self,
            reason = "the layout lookup is zstd-only; without zstd no data block splits, so the layout is always empty and `self` is unused"
        )
    )]
    fn inner_block_layout(&self, offset: u64) -> alloc::vec::Vec<u32> {
        #[cfg(feature = "zstd")]
        {
            self.block_layout
                .ends_for(offset)
                .map(<[u32]>::to_vec)
                .unwrap_or_default()
        }
        #[cfg(not(feature = "zstd"))]
        {
            let _ = offset;
            alloc::vec::Vec::new()
        }
    }

    /// Point-read counterpart to [`Self::load_columnar_data_block`]: rebuilds
    /// only `needle`'s rows (its MVCC versions, minus any masked by the
    /// positional delete-bitmap) into a tiny row block, or `Ok(None)` when the
    /// key is absent / wholly deleted. The caller runs the normal seqno-aware
    /// point read on the result.
    ///
    /// Only the key pages of the row pages whose key zone holds `needle` are
    /// read first, and a key they do not hold ends the read there: a miss
    /// never reads the group's other pages. On a hit only the row pages that
    /// hold the key are read, the directory and key pages coming from the
    /// cache.
    #[cfg(feature = "columnar")]
    fn load_columnar_point_block(
        &self,
        handle: &BlockHandle,
        needle: &[u8],
        fd: &LookupFd,
    ) -> crate::Result<Option<DataBlock>> {
        use crate::table::columnar::{COL_USER_KEY, TypeTag};
        use crate::table::row_group::{PageWant, RowPageSelect};

        // A key equal to the needle is the needle's bytes (the comparator
        // contract makes equality byte equality), so it lies within the
        // byte-wise zone of the row page holding it, whatever the key order.
        let group = self.group_read(handle, ReadCharge::Foreground, fd);
        let key_blocks = group.load(&PageWant::projected(
            &[COL_USER_KEY],
            RowPageSelect::Zone {
                column_id: COL_USER_KEY,
                lower: Some(needle),
                upper: Some(needle),
            },
        ))?;
        // The key pages as stored: the search reads the keys it compares and
        // decodes no page whole. What both steps hold decoded is the group's.
        let mut budget = crate::table::columnar::DecodeBudget::default();
        let key_pages = key_blocks.page_columns(|_| true, &mut budget)?;
        // The key's versions are one run of rows, sorted with the rest of the
        // group, so they sit on consecutive row pages: the first page whose
        // keys reach it through the page where the run ends. Every page of
        // the run is selected, since each holds the needle.
        let mut hit: Option<core::ops::Range<u16>> = None;
        // Each hit page's run of the needle's rows, so the second step reads
        // those rows without searching the keys again.
        let mut runs: Vec<core::ops::Range<u32>> = Vec::new();
        for page in key_pages {
            let (ordinal, row_count) = (page.ordinal, page.rows);
            let Some(key_col) = page
                .columns
                .into_iter()
                .next()
                .filter(|c| c.column_id == COL_USER_KEY && c.type_tag == TypeTag::Bytes)
            else {
                return Err(crate::Error::InvalidHeader(
                    "columnar: row group has no user-key column",
                ));
            };
            let keys = budget.rows(key_col.values, TypeTag::Bytes, row_count)?;
            let rows =
                crate::table::columnar::key_rows(row_count, needle, &self.comparator, |row| {
                    keys.get(TypeTag::Bytes, row_count, row)
                })?;
            if rows.is_empty() {
                // Every key of a page before the run is smaller than the
                // needle, so the search stops at `row_count`; a run that has
                // started, or a page past the needle, ends the search.
                if hit.is_some() || rows.start < row_count {
                    break;
                }
                continue;
            }
            let end = ordinal + 1;
            hit = Some(hit.map_or(ordinal..end, |h| h.start..end));
            let last = rows.end < row_count;
            runs.push(rows);
            if last {
                break;
            }
        }
        let Some(row_pages) = hit else {
            return Ok(None);
        };

        // The rest of the row's columns on those row pages, through the
        // directory and key pages the first step already has.
        let blocks = group.load_after(
            &key_blocks,
            &PageWant {
                columns: None,
                row_pages: RowPageSelect::Range(row_pages),
                whole: false,
            },
        )?;
        // The key search already placed the needle's rows, whose key is the
        // needle: the key pages are not read again.
        let pages = blocks.page_columns(|column_id| column_id != COL_USER_KEY, &mut budget)?;
        let first_row = pages.first().map_or(0, |page| page.start);
        let deletes = match self
            .delete_block_starts
            .as_ref()
            .and_then(|starts| starts.get(&handle.offset().0))
        {
            Some(&start) => Some((
                self.delete_bitmap.as_ref(),
                start
                    .checked_add(first_row)
                    .ok_or(crate::Error::InvalidHeader(
                        "columnar: row position exceeds u32::MAX",
                    ))?,
            )),
            None => None,
        };
        let mut rows = 0usize;
        let rebuilt = DataBlock::columnar_point_block(
            pages,
            &runs,
            needle,
            self.metadata.data_block_restart_interval,
            deletes,
            &mut rows,
            &mut budget,
        );
        // `rows` is the needle's keys and values copied out of the columns
        // when it is present (what decoding the pages copied was charged by
        // `load_row_group`); a miss or a refused group still did those copies,
        // so they are charged either way. The small block encoded from the
        // rows exists only on a hit.
        #[cfg(feature = "metrics")]
        self.metrics.record_gather(rows);
        #[cfg(not(feature = "metrics"))]
        let _ = rows;
        let rebuilt = rebuilt?;
        #[cfg(feature = "metrics")]
        if let Some(rebuilt) = &rebuilt {
            self.metrics.record_gather(rebuilt.inner.data.len());
        }
        Ok(rebuilt)
    }

    /// Loads the data block to point-read for `needle`: for a columnar SST the
    /// key-aware fast path that rebuilds only the matching key's rows; for a row
    /// SST the whole block. `Ok(None)` means the block carries no row for `needle`
    /// (columnar: absent / wholly deleted), so the caller moves on. The file is
    /// taken through `fd`, the lookup's.
    fn load_point_block(
        &self,
        handle: &BlockHandle,
        needle: &[u8],
        fd: &LookupFd,
    ) -> crate::Result<Option<DataBlock>> {
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            return self.load_columnar_point_block(handle, needle, fd);
        }
        let _ = needle;
        self.load_data_block(handle, fd)
    }

    /// Loads a columnar data block and decodes only the projected columns of
    /// the row pages `row_pages` selects, stepping over the rest without
    /// reading them. The returned batches, one per row page read, carry the
    /// requested columns for those rows. This is the projection read the
    /// vectorized scan uses, distinct from the whole-block reconstruction that
    /// the row read paths use. `whole` is [`PageWant::whole`].
    ///
    /// [`PageWant::whole`]: crate::table::row_group::PageWant::whole
    #[cfg(feature = "columnar")]
    fn load_columnar_block_projected(
        &self,
        handle: &BlockHandle,
        projection: &[u16],
        row_pages: crate::table::row_group::RowPageSelect<'_>,
        whole: bool,
    ) -> crate::Result<crate::table::row_group::RowPages> {
        self.load_row_group(
            handle,
            &crate::table::row_group::PageWant {
                columns: Some(projection),
                row_pages,
                whole,
            },
            ReadCharge::Foreground,
        )
    }

    /// Returns the (possibly compressed) file size.
    pub(crate) fn file_size(&self) -> u64 {
        self.metadata.file_size
    }

    /// The bytes this VIEW can contribute to a merge output: the whole file for
    /// a normal table, or `[punch_offset, end)` for a tight-space RESTRICTED
    /// view. Its punched prefix is superseded — the merge never reads it and
    /// never rewrites it — so charging a space gate the original `file_size`
    /// stalls a compaction whose real output fits the headroom.
    ///
    /// # Errors
    ///
    /// Propagates a restricted view's punch-offset lookup.
    #[cfg_attr(
        not(feature = "std"),
        allow(
            dead_code,
            reason = "merge-output sizing; its compaction consumer is std-gated, so unused under no_std"
        )
    )]
    pub(crate) fn live_file_size(&self) -> crate::Result<u64> {
        // The file's length: the recorded `file_size` leaves out the sections
        // written after the metadata, which a rewrite writes too.
        let size = self.file_len();
        // The punch offset is a data-block offset inside this same file, so the
        // subtraction cannot underflow; falling back to the whole size keeps a
        // space gate conservative if the two ever disagreed.
        Ok(size.checked_sub(self.punch_offset()?).unwrap_or(size))
    }

    /// The reads that consulted this table's data since it was written:
    /// point reads that passed its filter, and range scans that reached it.
    pub(crate) fn reads(&self) -> u64 {
        self.point_reads() + self.scans()
    }

    /// How hot the table is now: its [`Self::reads`] per thousand seconds
    /// since it began counting them, so a table read long ago does not
    /// outrank one read often since it was written.
    pub(crate) fn heat(&self) -> u64 {
        let now = crate::time::unix_timestamp().as_secs();
        // A clock stepped back, or no clock at all under `no_std`, reads as
        // the table's first second: its reads rank as they stand. Floored at
        // zero by design, since an age is never negative.
        let age = now.saturating_sub(self.counting_since_secs).max(1);
        let per_kilosecond = u128::from(self.reads()) * 1_000 / u128::from(age);
        // Below `reads() * 1000`, far within `u64` for any count of reads.
        u64::try_from(per_kilosecond).unwrap_or(u64::MAX)
    }

    /// The point reads that passed this table's filter since it was written.
    pub(crate) fn point_reads(&self) -> u64 {
        self.read_count.load(core::sync::atomic::Ordering::Relaxed)
    }

    /// The range scans that reached this table since it was written.
    pub(crate) fn scans(&self) -> u64 {
        self.scan_count.load(core::sync::atomic::Ordering::Relaxed)
    }

    /// Records a range scan reaching this table: one `Relaxed` bump per scan
    /// and table, beside the scan's own reads of the table.
    pub(crate) fn note_scan(&self) {
        self.scan_count
            .fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    }

    /// The bytes the file holds: what a whole read of it takes, and what
    /// writing it took.
    pub(crate) fn file_len(&self) -> u64 {
        self.file_len
    }

    /// The bytes of the data section: every data block or row group as it lies
    /// on disk. It opens the file, and the index follows it, or the top-level
    /// index where the index is not partitioned.
    pub(crate) fn data_section_len(&self) -> u64 {
        self.regions.index.unwrap_or(self.regions.tli).offset().0
    }

    /// The blocks one data index entry covers, each with the ROLE its writer
    /// sealed it under.
    ///
    /// A row-major table's entry is one [`BlockType::Data`] block and costs no
    /// read. A columnar table's entry is a row group: its
    /// [`BlockType::ColumnPageDirectory`] followed by its
    /// [`BlockType::ColumnPage`]s, found by reading the directory straight
    /// from disk, bypassing the cache — the walks that call this (scrub, heal,
    /// the reconcile gates) are judging the bytes on disk, and a cached
    /// directory is a statement about bytes that may since have changed.
    ///
    /// The roles are the swap-defence those walks check each block against,
    /// so they come from each block's POSITION in the group, never from the
    /// block's own header: a header is exactly what a misdirected block would
    /// carry.
    ///
    /// # Errors
    ///
    /// When the directory cannot be read or does not fill the group exactly.
    /// Without it the pages cannot be located, so the whole entry is reported
    /// rather than guessed at.
    #[cfg(feature = "std")]
    pub(crate) fn data_unit_blocks(
        &self,
        entry: &BlockHandle,
    ) -> crate::Result<alloc::vec::Vec<(BlockHandle, BlockType)>> {
        if !self.metadata.columnar {
            return Ok(alloc::vec![(*entry, BlockType::Data)]);
        }
        #[cfg(feature = "columnar")]
        {
            self.row_group_block_handles(entry)
        }
        #[cfg(not(feature = "columnar"))]
        {
            Err(crate::Error::FeatureUnsupported("columnar"))
        }
    }

    /// The handles of a row group's directory and pages, read from disk.
    /// See [`Self::data_unit_blocks`].
    #[cfg(all(feature = "std", feature = "columnar"))]
    fn row_group_block_handles(
        &self,
        group: &BlockHandle,
    ) -> crate::Result<alloc::vec::Vec<(BlockHandle, BlockType)>> {
        let (fd, _) = self
            .file_accessor
            .get_or_open_table(&self.global_id(), &self.path)?;
        let directory_len = crate::table::row_group::indexed_directory_len(group)?;
        let directory_handle = BlockHandle::new(group.offset(), directory_len);
        let directory_block = Block::from_file(
            fd.as_ref(),
            directory_handle,
            crate::table::block::BlockIdentity {
                table_id: self.id(),
                block_type: BlockType::ColumnPageDirectory,
                dict_id: 0,
                window_log: 0,
            },
            &crate::table::util::build_block_transform(
                CompressionType::None,
                self.encryption.as_deref(),
                self.metadata.ecc_params,
                #[cfg(zstd_any)]
                None,
            )?,
        )?;
        if directory_block.header.block_type != BlockType::ColumnPageDirectory {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                directory_block.header.block_type.into(),
            )));
        }
        crate::table::row_group::check_directory_len(
            directory_len,
            directory_block
                .header
                .on_disk_size_with(self.metadata.ecc_params),
        )?;
        let directory = crate::table::column_page::PageDirectory::decode(&directory_block.data)?;
        crate::table::row_group::check_group_extent(group, directory_len, &directory)?;
        crate::table::row_group::check_head_zones_len(group, &directory)?;
        // Verification, salvage and scrub take the group's blocks from here, so
        // another group's, in this one's place, is refused before it can be
        // certified or copied as this group's.
        crate::table::row_group::check_group_tag(group.group_tag(), &directory)?;

        // The blocks in the order they lie: the directory, the head zone
        // block, the pages, the other zone blocks.
        let mut blocks = alloc::vec::Vec::with_capacity(directory.entries().len() + 2);
        blocks.push((directory_handle, BlockType::ColumnPageDirectory));
        let after_directory = *group.offset() + u64::from(directory_len);
        if let Some(head) = directory.head_zone_block() {
            blocks.push((
                BlockHandle::new(
                    crate::table::block::BlockOffset(after_directory),
                    head.length,
                ),
                BlockType::ColumnZones,
            ));
        }
        let pages_at = after_directory + u64::from(directory.pages_start());
        for page in directory.entries() {
            let offset = pages_at + u64::from(page.offset);
            blocks.push((
                BlockHandle::new(crate::table::block::BlockOffset(offset), page.length),
                BlockType::ColumnPage,
            ));
        }
        let mut offset = pages_at + u64::from(directory.pages_len());
        for zone_block in directory.zone_blocks() {
            blocks.push((
                BlockHandle::new(crate::table::block::BlockOffset(offset), zone_block.length),
                BlockType::ColumnZones,
            ));
            offset += u64::from(zone_block.length);
        }
        Ok(blocks)
    }

    /// Patrol-scrubs every data block of this table: a cache-bypassing read that
    /// runs the Page-ECC verify+correct path, recording a heal hint (when
    /// `auto_heal` is on) on a confirmed-persistent correction.
    ///
    /// Returns a partial [`PatrolScrubReport`](crate::scrub::PatrolScrubReport)
    /// for this SST (`sst_files_scanned == 1`) so the caller can merge it across
    /// the tree. Always runs to completion: an uncorrectable / unreadable block
    /// is recorded (and logged), not silently skipped, and the next block is
    /// still scrubbed. A block-index walk failure stops this table early (later
    /// offsets are untrustworthy) but other tables still scrub.
    #[cfg(feature = "std")]
    pub(crate) fn scrub_data_blocks(&self) -> crate::scrub::PatrolScrubReport {
        use crate::scrub::{PatrolScrubReport, ScrubError};
        use crate::table::util::{BlockScrubOutcome, scrub_block};

        let mut report = PatrolScrubReport {
            sst_files_scanned: 1,
            ..PatrolScrubReport::default()
        };

        for entry in self.untraced_index_walk() {
            let keyed = match entry {
                Ok(h) => h,
                Err(e) => {
                    // A structural index error means later offsets can't be
                    // trusted — stop this table, record it, let others run.
                    log::error!(
                        "patrol scrub: block index of table {} at {} unreadable: {e:?}",
                        self.id(),
                        self.path.display(),
                    );
                    report.errors.push(ScrubError::BlockIndexUnreadable {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!("{e:?}"),
                    });
                    break;
                }
            };

            // Tight-space restriction: skip a block whose last key is below the
            // bound: it sits in the punched-out prefix a superseding output
            // table now owns, so scrubbing its reclaimed bytes would report
            // spurious corruption for a restricted view (see `Table::range`).
            if let Some(bound) = &self.1
                && self.comparator.compare(keyed.end_key(), bound) == core::cmp::Ordering::Less
            {
                continue;
            }
            let entry_handle = *keyed.as_ref();
            let blocks = match self.data_unit_blocks(&entry_handle) {
                Ok(blocks) => blocks,
                // A row group whose directory cannot be read has no known
                // pages: the entry is reported as one uncorrectable block at
                // the group's offset rather than skipped, so a scan never ends
                // clean over bytes it could not look at.
                Err(e) => {
                    report.blocks_scanned += 1;
                    self.record_uncorrectable(&mut report, keyed.offset().0, &e);
                    continue;
                }
            };

            for (handle, role) in blocks {
                report.blocks_scanned += 1;
                match scrub_block(
                    self.global_id(),
                    &self.path,
                    &self.file_accessor,
                    &handle,
                    role,
                    self.compression_for_role(role),
                    self.encryption.as_deref(),
                    self.metadata.ecc_params,
                    #[cfg(zstd_any)]
                    self.dictionary_for_role(role),
                    self.heal_hints.get().map(AsRef::as_ref),
                    #[cfg(feature = "metrics")]
                    &self.metrics,
                ) {
                    Ok(BlockScrubOutcome::Clean) => {}
                    Ok(BlockScrubOutcome::Corrected { scheduled }) => {
                        report.corrections_applied += 1;
                        if scheduled {
                            // heal_hints dedups per SST, so `scheduled` is true at
                            // most once per table — this counts distinct SSTs.
                            report.ssts_scheduled_for_rewrite += 1;
                        }
                    }
                    Err(e) => self.record_uncorrectable(&mut report, handle.offset().0, &e),
                }
            }
        }

        report
    }

    /// Records one block the patrol scrub could not verify or correct.
    #[cfg(feature = "std")]
    fn record_uncorrectable(
        &self,
        report: &mut crate::scrub::PatrolScrubReport,
        block_offset: u64,
        e: &crate::Error,
    ) {
        report.uncorrectable_blocks += 1;
        log::error!(
            "patrol scrub: uncorrectable block at offset {block_offset} in table {} at {}: {e:?}",
            self.id(),
            self.path.display(),
        );
        report
            .errors
            .push(crate::scrub::ScrubError::UncorrectableBlock {
                table_id: self.id(),
                path: self.path.to_path_buf(),
                block_offset,
                reason: alloc::format!("{e:?}"),
            });
    }

    /// The codec a data-carrying block of `role` was written under: a row
    /// group's directory and zone block are always plain, everything else
    /// uses the table's data codec.
    fn compression_for_role(&self, role: BlockType) -> CompressionType {
        if matches!(
            role,
            BlockType::ColumnPageDirectory | BlockType::ColumnZones
        ) {
            CompressionType::None
        } else {
            self.metadata.data_block_compression
        }
    }

    /// The zstd dictionary a data-carrying block of `role` needs, if any: none
    /// for a directory or a zone block, which are never compressed.
    #[cfg(zstd_any)]
    fn dictionary_for_role(&self, role: BlockType) -> Option<&crate::compression::ZstdDictionary> {
        if matches!(
            role,
            BlockType::ColumnPageDirectory | BlockType::ColumnZones
        ) {
            None
        } else {
            self.zstd_dictionary.as_deref()
        }
    }

    /// Ensures the heal's handle may be WRITTEN through: probes the link
    /// count on first use and detaches a multiply-linked inode onto a
    /// private copy via [`Self::unshare_for_heal`]. The outcome is cached in
    /// `state`, so the probe and copy run at most once per scan and only
    /// when a write is actually needed (a clean scan never detaches a
    /// checkpoint link). A failed link-count query is treated as shared
    /// (fail closed) — the copy path is safe either way.
    ///
    /// # Errors
    ///
    /// The unshare failure reason when the write must NOT happen (the inode
    /// may still be shared); repeated calls keep returning it.
    #[cfg(feature = "page_ecc")]
    fn ensure_unshared_for_write(
        &self,
        file: &mut Box<dyn crate::fs::FsFile>,
        state: &mut UnshareState,
        sync_mode: crate::fs::SyncMode,
    ) -> Result<(), alloc::string::String> {
        match state {
            UnshareState::Ready => Ok(()),
            UnshareState::Failed(reason) => Err(reason.clone()),
            UnshareState::Unprobed => {
                let shared = match file.hard_link_count() {
                    Ok(n) => n > 1,
                    Err(e) => {
                        log::warn!(
                            "in-place heal: link-count query failed for table {} at {}: {e}; \
                             assuming the inode is shared",
                            self.id(),
                            self.path.display(),
                        );
                        true
                    }
                };
                if shared {
                    // A pinned FD (no descriptor cache) is bound to its
                    // inode for the table's lifetime: after the unshare's
                    // copy + rename, every later read, scrub probe, and
                    // digest check would keep resolving the DEAD inode
                    // while the manifest points at the healed live path.
                    // Refuse the detach — the blocked write-backs surface
                    // as findings and every link stays byte-identical.
                    if !self.file_accessor.can_retarget() {
                        let reason = alloc::string::String::from(
                            "the inode is multiply linked and the pinned file \
                             descriptor cannot be retargeted at a detached copy; \
                             refusing the in-place write",
                        );
                        *state = UnshareState::Failed(reason.clone());
                        return Err(reason);
                    }
                    match self.unshare_for_heal(file.as_ref(), sync_mode) {
                        Ok(fresh) => *file = fresh,
                        Err(reason) => {
                            *state = UnshareState::Failed(reason.clone());
                            return Err(reason);
                        }
                    }
                }
                *state = UnshareState::Ready;
                Ok(())
            }
        }
    }

    /// Detaches this table's live path from a multiply-linked inode so an
    /// in-place heal can write without touching the other links (checkpoint
    /// snapshots): streams the file into a sibling `*.healtmp-{n}` copy, syncs
    /// it, and atomically renames it over the live path. The returned handle
    /// is the copy's (still valid after the rename), open read+write.
    ///
    /// The temp name carries a process-wide sequence number so two concurrent
    /// heal scans of the same table can never remove or rename each other's
    /// in-progress copy (cross-process exclusion comes from the directory
    /// lock). Every pre-rename failure removes the copy before returning —
    /// recovery refuses to open a tree whose `tables/` holds a file it cannot
    /// parse as a table id, so an abandoned artifact must never outlive the
    /// heal (recovery still sweeps `*.healtmp-*` left by a hard crash).
    #[cfg(feature = "page_ecc")]
    pub(crate) fn unshare_for_heal(
        &self,
        source: &dyn crate::fs::FsFile,
        sync_mode: crate::fs::SyncMode,
    ) -> Result<Box<dyn crate::fs::FsFile>, alloc::string::String> {
        use std::io::{Seek, SeekFrom, Write};

        static HEAL_TMP_SEQ: core::sync::atomic::AtomicU64 = core::sync::atomic::AtomicU64::new(0);

        let len = source
            .metadata()
            .map_err(|e| alloc::format!("metadata: {e}"))?
            .len;

        // A tight-space-restricted view has reclaimed the DATA blocks below its
        // frontier. The frontier lies inside the `data` section (index / filter /
        // meta sections all sit past the data region), and `Inner::drop` punches
        // each data block INDIVIDUALLY, top-down, stopping at the first failure —
        // so the prefix may be zeroed only partially. Reproduce the punched
        // extents as HOLES in the heal copy — probing each one, not assuming it —
        // instead of materializing the zeros (which would re-allocate the
        // reclaimed space, an ENOSPC risk on the near-full disk tight-space runs
        // on) or blindly zeroing the whole prefix (which would discard the
        // intact bytes an incomplete punch left behind). `punch` is `0` for a
        // normal (unrestricted) table, so its copy is byte-for-byte as before.
        let punch = self
            .punch_offset()
            .map_err(|e| alloc::format!("punch offset: {e}"))?;
        let sparse = punch > 0 && self.fs.capabilities(&self.path).punch_hole;
        let seq = HEAL_TMP_SEQ.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
        let tmp_path = self.path.with_extension(alloc::format!("healtmp-{seq}"));
        let mut tmp = self
            .fs
            .open(
                &tmp_path,
                &FsOpenOptions::new()
                    .read(true)
                    .write(true)
                    .create_new(true)
                    .write_origin(crate::fs::WriteOrigin::Repair),
            )
            .map_err(|e| alloc::format!("create heal copy: {e}"))?;

        // Any failure past this point must take the copy with it (see above).
        let mut copy = || -> Result<(), alloc::string::String> {
            // The reclaimed DATA-block extents below the frontier — exactly what
            // tight-space punched (via `Inner::drop`). The block index yields the
            // data-block handles, so the copied complement keeps everything the
            // punch never touches (the straddling block and every later section).
            //
            // Each candidate extent is PROBED for actual zeros rather than assumed
            // punched from the logical bound alone: a slice that committed but
            // failed its restriction-sidecar write deliberately leaves the input
            // UNPUNCHED (punching without the sidecar would force a lossy
            // conservative bound on a later manifest-loss repair), and the heal
            // copy must not introduce holes that state never had. An intact
            // sub-bound block reads non-zero (its header magic alone guarantees
            // it) and is copied verbatim; a genuinely punched extent reads as
            // zeros and stays a hole.
            let mut holes: alloc::vec::Vec<(u64, u64)> = alloc::vec::Vec::new();
            if sparse {
                let mut probe = alloc::vec::Vec::new();
                for handle in self.maintenance_index_walk() {
                    let handle = handle.map_err(|e| alloc::format!("block index iter: {e}"))?;
                    let block_off = handle.offset().0;
                    let block_len = u64::from(handle.size());
                    if block_off >= punch {
                        continue;
                    }
                    #[expect(
                        clippy::cast_possible_truncation,
                        reason = "a block's on-disk size is a u32, which fits usize"
                    )]
                    {
                        probe.resize(block_len as usize, 0u8);
                    }
                    let n = source
                        .read_at(&mut probe, block_off)
                        .map_err(|e| alloc::format!("probe block at {block_off}: {e}"))?;
                    if n < probe.len() {
                        return Err(alloc::format!(
                            "probe block at {block_off}: short read ({n} of {} bytes)",
                            probe.len(),
                        ));
                    }
                    if probe.iter().all(|&b| b == 0) {
                        holes.push((block_off, block_len));
                    }
                }
                holes.sort_unstable();
                // Adjacent holes are one extent: one punch call each below.
                holes.dedup_by(|next, run| {
                    let adjacent = run.0 + run.1 == next.0;
                    if adjacent {
                        run.1 += next.1;
                    }
                    adjacent
                });
                // Establish the full size so the un-written data-block extents stay
                // sparse holes.
                tmp.set_len(len)
                    .map_err(|e| alloc::format!("set heal copy length: {e}"))?;
            }

            // Live ranges to stream = the complement of the data-block holes across
            // `[0, len)`. With no holes (a normal table) this is the whole file.
            let mut live: alloc::vec::Vec<(u64, u64)> = alloc::vec::Vec::new();
            let mut cursor = 0u64;
            for &(h_off, h_len) in &holes {
                if h_off > cursor {
                    live.push((cursor, h_off));
                }
                cursor = cursor.max(h_off + h_len);
            }
            if cursor < len {
                live.push((cursor, len));
            }

            let mut buf = alloc::vec![0u8; 1 << 20];
            for &(start, end) in &live {
                tmp.seek(SeekFrom::Start(start))
                    .map_err(|e| alloc::format!("seek heal copy to {start}: {e}"))?;
                let mut off = start;
                while off < end {
                    #[expect(
                        clippy::cast_possible_truncation,
                        reason = "the u64 min() is taken first, so the value is bounded by buf.len()"
                    )]
                    let want = (end - off).min(buf.len() as u64) as usize;
                    let Some(chunk) = buf.get_mut(..want) else {
                        return Err(alloc::string::String::from("chunk within buffer"));
                    };
                    let n = source
                        .read_at(chunk, off)
                        .map_err(|e| alloc::format!("read source at {off}: {e}"))?;
                    if n < want {
                        // Fill-or-EOF contract: a short read here means the file
                        // shrank underneath us — abort rather than install a
                        // truncated copy.
                        return Err(alloc::format!(
                            "short read at {off}: got {n} of {want} bytes"
                        ));
                    }
                    tmp.write_all(chunk)
                        .map_err(|e| alloc::format!("write heal copy at {off}: {e}"))?;
                    off += want as u64;
                }
            }
            // Deallocate the data-block holes even where `set_len` zero-allocated, so
            // the reclaimed space is not silently re-consumed by the heal copy.
            for &(h_off, h_len) in &holes {
                self.fs
                    .punch_hole(&tmp_path, h_off, h_len)
                    .map_err(|e| alloc::format!("punch heal copy data block at {h_off}: {e}"))?;
            }
            // sync_all, not sync_data: the copy is a NEW file, its size must
            // be durable before the rename publishes it. Mode-aware: the
            // caller selected the tree's durability (Normal skips the macOS
            // F_FULLFSYNC hardware barrier, same as the flush path).
            tmp.sync_all_with(sync_mode)
                .map_err(|e| alloc::format!("sync heal copy: {e}"))?;
            // Replaces the live path on every platform, open handles included
            // — see the `Fs::rename` contract.
            self.fs
                .rename(&tmp_path, &self.path)
                .map_err(|e| alloc::format!("rename heal copy into place: {e}"))
        };
        if let Err(reason) = copy() {
            if let Err(e) = self.fs.remove_file(&tmp_path) {
                log::warn!(
                    "failed to remove abandoned heal copy {}: {e}",
                    tmp_path.display(),
                );
            }
            return Err(reason);
        }
        // The rename has replaced the live path, so the descriptor cache now
        // holds the OLD inode's fd: a later heal (or read) resolving through
        // it would scrub the detached inode while writes target the live one,
        // misreporting a live-only fault as an unexplained (uncorrectable)
        // mismatch. Drop the stale entry IMMEDIATELY — before the durability
        // sync below, whose failure must not leave the cache pinned to the
        // dead inode — so the next access reopens the live path.
        self.file_accessor.remove_for_table(&self.global_id());
        if let Some(parent) = self.path.parent() {
            self.fs
                .sync_directory_with(parent, sync_mode)
                .map_err(|e| alloc::format!("sync directory after rename: {e}"))?;
        }
        // The handle survives the rename (same inode, now the live path).
        Ok(tmp)
    }

    /// In-place ECC autoheal: like [`Self::scrub_data_blocks`], but PERSISTS each
    /// correction by writing the corrected block back at its existing offset
    /// (size-preserving) instead of scheduling a full-file healing rewrite.
    /// Healthy blocks are never rewritten, so the cost is O(damage), not O(file).
    ///
    /// Opens the SST read+write through the tree's `Fs` (bypassing the block
    /// cache, like scrub), and for each data block that fails its checksum but
    /// Page-ECC recovers it, writes back `header ++ recovered_data ++ recomputed
    /// parity` and `sync_data`s it before moving on, so a crash mid-heal leaves
    /// the block in its prior, still-RS-correctable state. Uncorrectable /
    /// unreadable blocks are recorded as findings and left for block salvage.
    ///
    /// HARD-LINK SAFE by unsharing: checkpoints hard-link SSTs, and a
    /// checkpoint's manifest records the digest of the bytes AT SNAPSHOT TIME,
    /// which the checkpoint (immutable by design) can never reconcile the way
    /// the live tree does. Writing through a shared inode would therefore
    /// desynchronize the snapshot from its own manifest whenever the recorded
    /// digest is not the original file's (a manifest rebuilt over rotted
    /// bytes). Right before the FIRST write-back (lazily — a clean scan of a
    /// linked healthy table performs zero writes and keeps the checkpoint's
    /// disk sharing), the link count is probed and a multiply-linked live
    /// path is detached onto a private copy (copy + atomic rename), which is
    /// then healed, leaving every other link byte-identical to what its
    /// manifest describes. Cached read-only descriptors may keep serving the
    /// old inode until they are reopened; its bytes are unchanged, so reads
    /// stay correct (ECC-corrected on the fly as before).
    ///
    /// Returns the scrub report plus an ATTRIBUTION flag: `true` when the
    /// file's digest was computed right before this pass's FIRST write and it
    /// matched the manifest digest — every byte the file now differs from
    /// the manifest state by is provably one of this pass's verified
    /// corrections. The digest reconciliation uses it to decide whether a
    /// post-heal mismatch may cover sections that cannot be semantically
    /// authenticated (deletion metadata). `false` whenever nothing was
    /// written, the pre-write digest could not be computed, or it already
    /// disagreed with the manifest.
    ///
    /// `pub(crate)` for [`crate::scrub::patrol_scrub`] (heal-in-place enabled).
    /// `sync_mode` is the tree's configured durability
    /// ([`Config::sync_mode`](crate::config::Config::sync_mode)): every
    /// write-back, the unshare copy, and the post-rename directory sync
    /// honor it, so a patrol with many corrections does not pay a macOS
    /// `F_FULLFSYNC` hardware barrier per block when the caller selected
    /// [`SyncMode::Normal`](crate::fs::SyncMode::Normal).
    ///
    /// `manifest_checksum` is the table's CURRENT manifest digest, read by
    /// the caller under the per-table heal lock: a concurrent patrol may
    /// have refreshed the manifest after this view was captured, and the
    /// attribution probe must compare against what the manifest says NOW.
    #[cfg(feature = "page_ecc")]
    pub(crate) fn heal_data_blocks_in_place(
        &self,
        sync_mode: crate::fs::SyncMode,
        manifest_checksum: Checksum,
    ) -> (crate::scrub::PatrolScrubReport, bool) {
        use crate::scrub::{PatrolScrubReport, ScrubError};
        use std::io::{Seek, SeekFrom, Write};

        let mut report = PatrolScrubReport {
            sst_files_scanned: 1,
            ..PatrolScrubReport::default()
        };
        // Whether any write-back was ATTEMPTED. A write_all that errors after a
        // partial write, or a full write whose sync then fails, may already have
        // changed the on-disk bytes even though `blocks_healed_in_place` stays 0,
        // so the marker (the only attribution for a later digest refresh) must be
        // KEPT in that case; it is removed only when no mutation ever began.
        let mut write_attempted = false;

        // NEITHER exclusion is taken here — both are held by the patrol
        // scrub across this scan AND the digest reconciliation that follows
        // it, because re-acquiring either inside would deadlock:
        // - the per-table `heal_lock` (a Mutex) serializes same-table heals
        //   for the whole scan-to-reconcile span, so one patrol cannot
        //   install a digest computed before another patrol's heal;
        // - the `DeletionPause` mutation window excludes a checkpoint's link
        //   pass for the same span, so a checkpoint cannot link healed bytes
        //   under a stale digest.

        // A single read+write handle for both the recovery read and the
        // write-back, opened directly (not via the read-only descriptor cache) so
        // the heal sees the medium and can mutate it.
        let mut file = match self.fs.open(
            &self.path,
            &FsOpenOptions::new()
                .read(true)
                .write(true)
                .write_origin(crate::fs::WriteOrigin::Repair),
        ) {
            Ok(f) => f,
            Err(e) => {
                // Cannot persist corrections (a read-only replica, restrictive
                // permissions) — but the table must still get its integrity
                // CHECKED. Record the failed open, then fall back to the
                // read-only scrub so corruption still surfaces instead of
                // returning a healthy-looking report with zero blocks scanned.
                report.errors.push(ScrubError::BlockIndexUnreadable {
                    table_id: self.id(),
                    path: self.path.to_path_buf(),
                    reason: alloc::format!("open read+write for heal: {e}"),
                });
                report.merge(self.scrub_data_blocks());
                // Both passes stamped this SST as scanned; it is one file.
                report.sst_files_scanned = 1;
                return (report, false);
            }
        };

        // A multiply-linked inode (a checkpoint shares it) must not be healed
        // through — but detaching costs a full-file copy and permanently
        // ends the checkpoint's disk sharing, so it happens LAZILY: the link
        // count is probed (and a shared inode detached onto a private copy)
        // only right before the FIRST write-back. A clean scan of a linked
        // healthy table therefore stays O(damage) = zero writes. The probe
        // stays honest under the caller's mutation window: a checkpoint
        // cannot link this SST anywhere inside the scan-to-write span.
        let mut unshare_state = UnshareState::Unprobed;

        let transform = match crate::table::util::build_block_transform(
            self.metadata.data_block_compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.zstd_dictionary.as_deref(),
        ) {
            Ok(t) => t,
            Err(e) => {
                report.errors.push(ScrubError::BlockIndexUnreadable {
                    table_id: self.id(),
                    path: self.path.to_path_buf(),
                    reason: alloc::format!("build transform for heal: {e:?}"),
                });
                return (report, false);
            }
        };

        // Attribution + crash-recovery marker, computed UP FRONT while the file
        // still holds its pre-heal bytes. The heal is deterministic, so the
        // digest of the file with every correction applied is known before any
        // write lands: bind THAT into the attestation (not just `pre ==
        // manifest`), so a marker a crash leaves behind can only ever
        // re-authorize the exact healed bytes, never an unrelated later forge.
        // A clean scan (no corrections) writes nothing. `pre_heal_matched`
        // still drives the returned attribution flag and the zero-heal marker
        // cleanup below; the per-block correction is recomputed identically in
        // the write loop (both call `heal_correction_for_block`).
        // A restricted view predicts (and later digests) only its live suffix;
        // its corrections all lie there, and the punched prefix is not hashed.
        // A transient failure resolving that bound must ABORT, not fall back to
        // offset 0: predicting (and attesting) over the WHOLE physical file while
        // the manifest and reconciliation hash only the suffix would, after a
        // crash mid-heal, leave a completed marker whose digest can never match
        // the suffix — permanently stranding the healed table.
        let heal_start = match self.restrict_lower_bound() {
            Some(bound) => match self.punch_offset_for(bound) {
                Ok(off) => off,
                Err(e) => {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!(
                            "could not resolve the restricted heal start; heal skipped to \
                             keep the table reconcilable: {e:?}"
                        ),
                    });
                    return (report, false);
                }
            },
            None => 0,
        };
        // Predict the post-heal digest AND the exact set of offsets the heal
        // will touch, streaming so a broadly damaged table does not materialize
        // every corrected frame at once. The write loop below applies ONLY these
        // offsets, so a fault appearing after this pass is never healed under a
        // digest that did not attest it.
        let (predicted_digest, predicted_offsets) =
            match self.predict_heal_digest_and_offsets(file.as_ref(), &transform, heal_start) {
                Ok(pair) => pair,
                Err(e) => {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!(
                            "could not predict the post-heal digest; heal skipped to keep the \
                             table reconcilable: {e:?}"
                        ),
                    });
                    return (report, false);
                }
            };
        // The pre-heal digest probe result: `None` when there is nothing to
        // heal; otherwise `Some(matched)` where `matched` says whether the
        // current bytes still match the manifest (the ATTRIBUTABLE path). A
        // probe FAILURE aborts before the first write: writing corrections with
        // no completed marker can permanently strand a table whose manifest
        // legitimately described the pre-heal bytes.
        let pre_heal_matched: Option<bool> = if predicted_offsets.is_empty() {
            None
        } else {
            let matched = match self.pre_heal_digest_matches(manifest_checksum) {
                Ok(matched) => matched,
                Err(e) => {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!(
                            "pre-heal digest probe failed; heal skipped to keep the \
                             table reconcilable: {e:?}"
                        ),
                    });
                    return (report, false);
                }
            };
            if matched {
                // ATTRIBUTABLE path: the heal is about to change bytes the
                // manifest digest still matches, so the crash-recovery marker
                // MUST be durable BEFORE the first mutation. If the post-heal
                // digest cannot be predicted, or the attestation cannot be
                // persisted, do NOT heal: a crash after a corrected block syncs
                // but before the in-process manifest refresh would leave healed
                // bytes under the stale digest with no marker, and fail-closed
                // reconciliation rejects that mismatch forever, permanently
                // stranding a table that was reconcilable a moment earlier.
                // Leaving the block corrupt keeps the table reconcilable; the
                // next patrol retries once the marker can be written. (A
                // non-crash run also reconciles directly, but the marker is the
                // ONLY thing that survives a crash, so its durability gates the
                // mutation.)
                if let Err(e) = crate::scrub::heal_attest::write(
                    &*self.fs,
                    &self.path,
                    self.encryption.as_deref(),
                    self.id(),
                    manifest_checksum,
                    Checksum::from_raw(predicted_digest),
                ) {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!(
                            "could not persist the heal attestation; heal skipped to keep the \
                             table reconcilable: {e}"
                        ),
                    });
                    return (report, false);
                }
                Some(true)
            } else {
                // NOT-matched pre-heal: the current bytes already differ from the
                // manifest digest. If the predicted heal RESTORES the manifest
                // digest (the common restorative case: a rotted file healing back to
                // exactly what the manifest describes), the write window STILL needs
                // a durable marker BEFORE the first mutation. A crash after syncing
                // SOME of several corrections leaves the file matching neither the
                // manifest nor the predicted digest; with no marker a checkpoint
                // hard-links those intermediate bytes under the stale manifest
                // digest, producing a permanently inconsistent checkpoint. The
                // marker records `(manifest, predicted)` (here equal), so a reconcile
                // trusts the file only once it hashes to the restored digest. (The
                // DIVERGING sub-case, predicted != manifest, is gated separately
                // below against an EXISTING completed marker via `attests_post`.)
                if Checksum::from_raw(predicted_digest) == manifest_checksum
                    && let Err(e) = crate::scrub::heal_attest::write(
                        &*self.fs,
                        &self.path,
                        self.encryption.as_deref(),
                        self.id(),
                        manifest_checksum,
                        Checksum::from_raw(predicted_digest),
                    )
                {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!(
                            "could not persist the restorative heal attestation; heal \
                             skipped to keep the table reconcilable: {e}"
                        ),
                    });
                    return (report, false);
                }
                Some(false)
            }
        };

        // A DIVERGING heal on a stale-manifest file must NOT proceed: when the
        // current bytes do not match the manifest AND the predicted post-heal
        // digest would not match it either, the file is drifting away from the
        // manifest (e.g. a prior heal crashed after writing its completed
        // attestation but before refreshing the manifest, then a fresh fault
        // appeared). Writing these corrections would move the bytes off any
        // existing attestation's `post` digest with no chaining marker, so the
        // reconcile that runs right after this returns could not attribute the
        // result and would strip the marker — leaving future scrubs and
        // checkpoints unable to reconcile the table. Leave it untouched (fail
        // closed): the reconcile still reconciles an existing marker against the
        // manifest, and a later patrol heals the fault once the bytes line up.
        //
        // A not-matched file whose predicted heal RESTORES the manifest digest
        // (a plain rotted file healing back to what the manifest describes), or
        // restores a digest an existing COMPLETED marker already attests (a fresh
        // fault on the just-healed bytes, which that marker still reconciles), is
        // NOT diverging, so it proceeds. `None` (nothing to heal) is unaffected.
        if pre_heal_matched == Some(false)
            && Checksum::from_raw(predicted_digest) != manifest_checksum
        {
            use crate::scrub::heal_attest::AttestResult;
            match crate::scrub::heal_attest::attests_post(
                &*self.fs,
                &self.path,
                self.encryption.as_deref(),
                self.id(),
                Checksum::from_raw(predicted_digest),
            ) {
                // An existing COMPLETED marker already attests the predicted post:
                // the heal restores an attested digest, not a divergence — proceed.
                AttestResult::Attests => {}
                // No attesting marker: healing would drift the file off any
                // marker's post with no chaining attribution, so the reconcile
                // could not attribute it and would strip the marker. Fail closed.
                AttestResult::Absent => return (report, false),
                // The attestation probe hit a TRANSIENT read. Collapsing that to
                // "does not attest" (the old behavior) would skip the heal, leaving
                // the file diverged from a marker that MAY attest the predicted
                // post; the reconcile then rereads the now-readable marker, finds
                // it no longer matches the current bytes, and deletes it — stranding
                // the table. Record a finding so the report is non-clean (a
                // checkpoint's `reconcile_pending_heals` then aborts instead of
                // removing) and skip; the next patrol retries once the probe reads
                // cleanly and the marker's verdict is conclusive.
                AttestResult::Inconclusive => {
                    report.errors.push(ScrubError::ChecksumRefreshFailed {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: "heal attestation probe was inconclusive (transient read); heal \
                                 skipped to preserve the existing marker for the next patrol"
                            .to_string(),
                    });
                    return (report, false);
                }
            }
        }

        for entry in self.maintenance_index_walk() {
            let keyed = match entry {
                Ok(h) => h,
                Err(e) => {
                    // A structural index error means later offsets can't be
                    // trusted — stop this table, record it.
                    report.errors.push(ScrubError::BlockIndexUnreadable {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        reason: alloc::format!("{e:?}"),
                    });
                    break;
                }
            };
            // Tight-space restriction: a block whose last key is below the bound
            // sits in the punched-out (reclaimed) prefix that a superseding
            // output table now owns. Its bytes are gone, so reading it reports a
            // spurious uncorrectable error that would suppress the digest refresh
            // for a real correction in the LIVE suffix. Skip it: the read path
            // clamps scans the same way (see `Table::range`).
            if let Some(bound) = &self.1
                && self.comparator.compare(keyed.end_key(), bound) == core::cmp::Ordering::Less
            {
                continue;
            }
            let entry_handle = *keyed.as_ref();
            let blocks = match self.data_unit_blocks(&entry_handle) {
                Ok(blocks) => blocks,
                // A row group whose directory cannot be read has no locatable
                // pages: report the entry as one uncorrectable block rather
                // than end the pass clean over bytes it could not look at.
                Err(e) => {
                    report.blocks_scanned += 1;
                    report.uncorrectable_blocks += 1;
                    report.errors.push(ScrubError::UncorrectableBlock {
                        table_id: self.id(),
                        path: self.path.to_path_buf(),
                        block_offset: keyed.offset().0,
                        reason: alloc::format!("{e:?}"),
                    });
                    continue;
                }
            };
            for (handle, role) in blocks {
                let block_offset = handle.offset().0;
                report.blocks_scanned += 1;

                // Verify the block through the SAME full read the scrub path uses
                // (checksum + decode + ECC recovery), not just a bare frame check.
                // This detects a checksum-clean-but-undecodable block (e.g. a corrupt
                // `uncompressed_length`) and a corrupt block in a non-ECC segment,
                // reporting it as uncorrectable instead of silently clean. `heal_hints
                // = None`: this path persists the correction IN PLACE, so it must not
                // also queue a full-file healing rewrite. The metric is recorded inside
                // `scrub_block`.
                let outcome = crate::table::util::scrub_block(
                    self.global_id(),
                    &self.path,
                    &self.file_accessor,
                    &handle,
                    role,
                    self.compression_for_role(role),
                    self.encryption.as_deref(),
                    self.metadata.ecc_params,
                    #[cfg(zstd_any)]
                    self.dictionary_for_role(role),
                    None,
                    #[cfg(feature = "metrics")]
                    &self.metrics,
                );
                match outcome {
                    // Verified clean: nothing to persist.
                    // Verified clean — but a clean PAYLOAD checksum never
                    // validates the parity trailer (parity is only consulted on a
                    // mismatch), so rot confined to the trailer would silently
                    // leave dead ECC on disk: a later payload fault in this block
                    // could no longer be recovered. This pass holds the read+write
                    // handle and the payload is untouched, so a size-preserving
                    // trailer rebuild is exactly the heal it exists to perform.
                    Ok(crate::table::util::BlockScrubOutcome::Clean) => {
                        let raw = match crate::file::read_exact(
                            file.as_ref(),
                            block_offset,
                            handle.size() as usize,
                        ) {
                            Ok(raw) => raw,
                            Err(e) => {
                                report.uncorrectable_blocks += 1;
                                report.errors.push(ScrubError::UncorrectableBlock {
                                    table_id: self.id(),
                                    path: self.path.to_path_buf(),
                                    block_offset,
                                    reason: alloc::format!(
                                        "in-place heal: parity re-read failed: {e:?}"
                                    ),
                                });
                                continue;
                            }
                        };
                        use crate::coding::Decode;
                        let Ok(raw_header) =
                            crate::table::block::Header::decode_from(&mut &raw[..])
                        else {
                            // The scrub just read this frame cleanly; a header that
                            // no longer decodes is an inconsistency worth surfacing.
                            report.uncorrectable_blocks += 1;
                            report.errors.push(ScrubError::UncorrectableBlock {
                                table_id: self.id(),
                                path: self.path.to_path_buf(),
                                block_offset,
                                reason: alloc::string::String::from(
                                    "in-place heal: block scrubbed clean but its header no \
                                 longer decodes",
                                ),
                            });
                            continue;
                        };
                        // The bytes examined below are this SECOND read, not the
                        // frame the scrub just verified: a transient fault or
                        // fresh rot between the reads would otherwise feed the
                        // parity comparison an unverified payload, and the
                        // rebuild arm would PERSIST parity computed over those
                        // corrupt bytes — turning a recoverable block into one
                        // whose ECC agrees with the corruption. Verify the
                        // re-read header's ROLE and its payload against the
                        // header checksum first; a mismatch is surfaced, never
                        // acted on.
                        if raw_header.block_type != role {
                            report.uncorrectable_blocks += 1;
                            report.errors.push(ScrubError::UncorrectableBlock {
                                table_id: self.id(),
                                path: self.path.to_path_buf(),
                                block_offset,
                                reason: alloc::string::String::from(
                                    "in-place heal: block scrubbed clean but its re-read \
                                 header carries a different block role",
                                ),
                            });
                            continue;
                        }
                        let header_len =
                            crate::table::block::Header::header_len(raw_header.block_type);
                        // checked_add: a forged/rotted data_length can overflow
                        // the payload-end sum on 32-bit targets; overflow is an
                        // uncorrectable finding, not a panic.
                        let payload_ok = header_len
                            .checked_add(raw_header.data_length as usize)
                            .and_then(|payload_end| raw.get(header_len..payload_end))
                            .is_some_and(|payload| {
                                crate::hash::hash128(payload)
                                    == raw_header
                                        .payload_checksum(crate::table::block::ChecksumAt::block(
                                            self.id(),
                                            role,
                                            block_offset,
                                        ))
                                        .into_u128()
                            });
                        if !payload_ok {
                            report.uncorrectable_blocks += 1;
                            report.errors.push(ScrubError::UncorrectableBlock {
                                table_id: self.id(),
                                path: self.path.to_path_buf(),
                                block_offset,
                                reason: alloc::string::String::from(
                                    "in-place heal: block scrubbed clean but its re-read \
                                 payload does not match its checksum",
                                ),
                            });
                            continue;
                        }
                        match self.raw_block_parity_delta(&raw, &raw_header) {
                            // Trailer matches (or no ECC): nothing to persist.
                            Ok(None) => {}
                            // Trailer rot: persist the freshly computed parity at
                            // its on-disk position (header + payload unchanged).
                            Ok(Some(fresh)) => {
                                let trailer_offset = block_offset
                                    + crate::table::block::Header::header_len(raw_header.block_type)
                                        as u64
                                    + u64::from(raw_header.data_length);
                                // Apply ONLY corrections the prediction pass attested.
                                // A trailer rebuild that appears now but was not
                                // predicted (fresh rot between the two reads) is left
                                // as-is: healing it would put bytes on disk the
                                // marker's digest never covered, and a later
                                // checkpoint would snapshot them under the stale
                                // digest. It stays RS-correctable for the next patrol.
                                if !predicted_offsets.contains(&trailer_offset) {
                                    continue;
                                }
                                // Attribution + the crash-recovery marker were
                                // captured UP FRONT (before this loop), so nothing is
                                // done here. First write: make sure no checkpoint link
                                // shares the inode (lazy detach).
                                if let Err(reason) = self.ensure_unshared_for_write(
                                    &mut file,
                                    &mut unshare_state,
                                    sync_mode,
                                ) {
                                    report.uncorrectable_blocks += 1;
                                    report.errors.push(ScrubError::UncorrectableBlock {
                                        table_id: self.id(),
                                        path: self.path.to_path_buf(),
                                        block_offset,
                                        reason: alloc::format!(
                                            "unshare hard-linked SST for heal: {reason}"
                                        ),
                                    });
                                    continue;
                                }
                                let write_back = file
                                    .seek(SeekFrom::Start(trailer_offset))
                                    .and_then(|_| file.write_all(&fresh));
                                // The write_all may have written some bytes even if it
                                // then errored; mark the file as possibly mutated so a
                                // later failure does not drop the attestation.
                                write_attempted = true;
                                let durable = match write_back {
                                    Ok(()) => file
                                        .sync_data_with(sync_mode)
                                        .map_err(|e| alloc::format!("sync: {e}")),
                                    Err(e) => Err(alloc::format!("write: {e}")),
                                };
                                if let Err(reason) = durable {
                                    report.uncorrectable_blocks += 1;
                                    report.errors.push(ScrubError::UncorrectableBlock {
                                        table_id: self.id(),
                                        path: self.path.to_path_buf(),
                                        block_offset,
                                        reason: alloc::format!("in-place parity rebuild {reason}"),
                                    });
                                    continue;
                                }
                                report.blocks_healed_in_place += 1;
                            }
                            Err(()) => {
                                report.uncorrectable_blocks += 1;
                                report.errors.push(ScrubError::UncorrectableBlock {
                                    table_id: self.id(),
                                    path: self.path.to_path_buf(),
                                    block_offset,
                                    reason: alloc::string::String::from(
                                        "in-place heal: parity trailer unverifiable on a \
                                     checksum-clean block",
                                    ),
                                });
                            }
                        }
                    }
                    // Recovered from parity: persist the corrected frame in place.
                    Ok(crate::table::util::BlockScrubOutcome::Corrected { .. }) => {
                        // Apply ONLY corrections the prediction pass attested. A block
                        // that recovers now but was not in the predicted set (a fault
                        // that appeared after the prediction) is left corrupt: writing
                        // it would heal bytes the marker's digest never covered, so a
                        // later checkpoint could snapshot them under the stale digest.
                        // It stays RS-correctable, so the next patrol retries.
                        if !predicted_offsets.contains(&block_offset) {
                            continue;
                        }
                        let frame = match crate::table::block::Block::heal_frame(
                            file.as_ref(),
                            handle,
                            self.id(),
                            &transform,
                        ) {
                            Ok(Some((frame, _kind))) => frame,
                            // The scrub read corrected a fault but the confirming
                            // re-read is already clean: a TRANSIENT fault the first
                            // read hit and the re-read did not. This mirrors the
                            // schedule path (`maybe_record_persistent_heal`), which
                            // treats a clean confirmation re-read as transient and
                            // does not act — there is nothing on disk to persist.
                            Ok(None) => {
                                log::debug!(
                                    "in-place heal: transient correction on block at offset \
                                 {block_offset} in table {} at {}; re-read clean, nothing to \
                                 persist",
                                    self.id(),
                                    self.path.display(),
                                );
                                continue;
                            }
                            // A real read/decode error on the re-read: surface it
                            // rather than silently skip the write-back.
                            Err(e) => {
                                report.uncorrectable_blocks += 1;
                                report.errors.push(ScrubError::UncorrectableBlock {
                                    table_id: self.id(),
                                    path: self.path.to_path_buf(),
                                    block_offset,
                                    reason: alloc::format!(
                                        "in-place heal: block scrubbed as corrected but the heal \
                                     re-read failed: {e:?}"
                                    ),
                                });
                                continue;
                            }
                        };
                        // Attribution + the crash-recovery marker were captured UP
                        // FRONT (before this loop). First write: make sure no
                        // checkpoint link shares the inode (lazy detach).
                        if let Err(reason) =
                            self.ensure_unshared_for_write(&mut file, &mut unshare_state, sync_mode)
                        {
                            report.uncorrectable_blocks += 1;
                            report.errors.push(ScrubError::UncorrectableBlock {
                                table_id: self.id(),
                                path: self.path.to_path_buf(),
                                block_offset,
                                reason: alloc::format!(
                                    "unshare hard-linked SST for heal: {reason}"
                                ),
                            });
                            continue;
                        }
                        // Seek + write (std::io) and sync (crate::io) carry different
                        // error types, so each is handled separately; both render to
                        // text for the finding. `sync_data` (not `sync_all`): the file
                        // size is unchanged, so only the data needs flushing, and it
                        // must land before the next block so a crash leaves the block
                        // in its prior, still-RS-correctable state.
                        let write_back = file
                            .seek(SeekFrom::Start(block_offset))
                            .and_then(|_| file.write_all(&frame));
                        // The write_all may have written some bytes even if it then
                        // errored (a partial write); mark the file as possibly mutated
                        // so a later failure does not drop the attestation.
                        //
                        // Retaining the attestation across a failed sync is what lets
                        // a later patrol attribute these bytes — but those bytes are
                        // NOT durable yet, and that patrol may read them straight from
                        // the page cache and find the table clean. Recording their
                        // digest then would let a power loss discard the healed block
                        // while the manifest keeps the post-heal digest. The
                        // reconciliation therefore syncs the SST itself before
                        // refreshing (and refuses the refresh when that sync fails);
                        // see `crate::scrub`'s marker-based reconcile.
                        write_attempted = true;
                        let durable = match write_back {
                            Ok(()) => file
                                .sync_data_with(sync_mode)
                                .map_err(|e| alloc::format!("sync: {e}")),
                            Err(e) => Err(alloc::format!("write: {e}")),
                        };
                        if let Err(reason) = durable {
                            report.uncorrectable_blocks += 1;
                            log::error!(
                                "in-place heal: write-back failed for block at offset \
                             {block_offset} in table {} at {}: {reason}",
                                self.id(),
                                self.path.display(),
                            );
                            report.errors.push(ScrubError::UncorrectableBlock {
                                table_id: self.id(),
                                path: self.path.to_path_buf(),
                                block_offset,
                                reason: alloc::format!("in-place heal {reason}"),
                            });
                            continue;
                        }
                        report.corrections_applied += 1;
                        report.blocks_healed_in_place += 1;
                    }
                    Err(e) => {
                        report.uncorrectable_blocks += 1;
                        log::error!(
                            "in-place heal: uncorrectable block at offset {block_offset} in table \
                         {} at {}: {e:?}",
                            self.id(),
                            self.path.display(),
                        );
                        report.errors.push(ScrubError::UncorrectableBlock {
                            table_id: self.id(),
                            path: self.path.to_path_buf(),
                            block_offset,
                            reason: alloc::format!("{e:?}"),
                        });
                    }
                }
            }
        }

        // The in-progress marker is written speculatively before the first
        // block write; if NO block was actually healed (every candidate turned
        // out uncorrectable) AND no write was ever attempted, the file is
        // unchanged and the marker attests to a heal that never happened. Remove
        // it so it cannot later authorize an unrelated digest mismatch (its
        // `pre == manifest` binding does not expire on its own). But when a
        // write WAS attempted and then failed (a partial write, or a full write
        // whose sync failed), the on-disk bytes may already differ from the
        // manifest digest: KEEP the marker so a later patrol can still attribute
        // and refresh the altered table rather than stranding it.
        let healed = pre_heal_matched == Some(true);
        if healed && report.blocks_healed_in_place == 0 && !write_attempted {
            crate::scrub::heal_attest::remove(&*self.fs, &self.path);
        }

        (report, healed)
    }

    /// The correction the in-place heal would apply to one data block, computed
    /// WITHOUT writing. [`Self::predict_heal_digest_and_offsets`] calls this to
    /// PREDICT the post-heal digest and the offsets to touch; the write loop in
    /// [`Self::heal_data_blocks_in_place`] performs the same decision inline and
    /// applies it. The heal is deterministic (RS recovery / parity rebuild over
    /// the same pre-heal bytes), so the prediction and the later application
    /// are byte-identical. This MIRRORS the write loop's arms; a drift only
    /// weakens crash recovery (a predicted digest that no longer matches the
    /// applied bytes fails the marker CLOSED, never authorizing wrong bytes),
    /// it is never a correctness hazard.
    ///
    /// # Errors
    ///
    /// Propagates a TRANSIENT read failure (the confirming block / frame re-read)
    /// rather than mapping it to "no correction": a swallowed read would omit the
    /// block from the prediction's offset set, and the write loop's gate would then
    /// skip a correction it re-discovers, reporting a clean pass over known damage.
    #[cfg(feature = "page_ecc")]
    fn heal_correction_for_block(
        &self,
        file: &dyn crate::fs::FsFile,
        handle: BlockHandle,
        role: BlockType,
        transform: &crate::table::block::BlockTransform<'_>,
    ) -> crate::Result<Option<(u64, alloc::vec::Vec<u8>)>> {
        use crate::coding::Decode;
        let block_offset = handle.offset().0;
        let outcome = crate::table::util::scrub_block(
            self.global_id(),
            &self.path,
            &self.file_accessor,
            &handle,
            role,
            self.compression_for_role(role),
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.dictionary_for_role(role),
            None,
            #[cfg(feature = "metrics")]
            &self.metrics,
        );
        match outcome {
            Ok(crate::table::util::BlockScrubOutcome::Clean) => {
                // A clean-payload block still needs a parity-trailer rebuild if its
                // trailer rotted. The confirming re-read PROPAGATES on a transient
                // failure (see the doc), but a decode / structural inconsistency
                // leaves the bytes unchanged (`Ok(None)`), matching the write loop's
                // report-and-skip.
                let raw = crate::file::read_exact(file, block_offset, handle.size() as usize)?;
                let Ok(raw_header) = crate::table::block::Header::decode_from(&mut &raw[..]) else {
                    return Ok(None);
                };
                if raw_header.block_type != role {
                    return Ok(None);
                }
                let header_len = crate::table::block::Header::header_len(raw_header.block_type);
                let payload_ok = header_len
                    .checked_add(raw_header.data_length as usize)
                    .and_then(|payload_end| raw.get(header_len..payload_end))
                    .is_some_and(|payload| {
                        crate::hash::hash128(payload)
                            == raw_header
                                .payload_checksum(crate::table::block::ChecksumAt::block(
                                    self.id(),
                                    role,
                                    block_offset,
                                ))
                                .into_u128()
                    });
                if !payload_ok {
                    return Ok(None);
                }
                match self.raw_block_parity_delta(&raw, &raw_header) {
                    Ok(Some(fresh)) => {
                        let trailer_offset = block_offset
                            + crate::table::block::Header::header_len(raw_header.block_type) as u64
                            + u64::from(raw_header.data_length);
                        Ok(Some((trailer_offset, fresh)))
                    }
                    // Trailer matches (no ECC / already fresh) or is
                    // unverifiable: nothing to persist.
                    Ok(None) | Err(()) => Ok(None),
                }
            }
            Ok(crate::table::util::BlockScrubOutcome::Corrected { .. }) => {
                match crate::table::block::Block::heal_frame(file, handle, self.id(), transform) {
                    Ok(Some((frame, _kind))) => Ok(Some((block_offset, frame))),
                    // A confirming re-read that is now clean: a transient fault the
                    // first read hit and this one did not, so nothing to persist.
                    Ok(None) => Ok(None),
                    // A real read / decode error on the confirming read PROPAGATES:
                    // mapping it to "no correction" would let the write loop's gate
                    // skip a correction it re-discovers and report a clean pass.
                    Err(e) => Err(e),
                }
            }
            // A TRANSIENT read (Io) during this prediction PROPAGATES: swallowing
            // it drops the block from the predicted offset set, so the write pass
            // would skip a correction it re-discovers on an ECC-correctable block
            // and report a clean pass over the fault still on disk. An
            // UNCORRECTABLE / structural failure leaves the bytes as they are (the
            // scrub already recorded the finding and the write pass re-surfaces
            // it), so there is no correction to predict.
            Err(e @ crate::Error::Io(_)) => Err(e),
            Err(_) => Ok(None),
        }
    }

    /// Read-only pass predicting the post-heal whole-file digest AND the set of
    /// write offsets the heal will touch, WITHOUT materializing every corrected
    /// frame. The predicted digest is streamed: each correction (see
    /// [`Self::heal_correction_for_block`]) is spliced into a running hash and
    /// then DROPPED, so a broadly damaged multi-gigabyte table costs only one
    /// correction frame of heap at a time instead of the whole repaired file.
    ///
    /// The returned offset set is what the write loop gates on: it applies ONLY
    /// corrections whose offset was predicted here, so a fault that appears
    /// AFTER this pass (transient rot, a byte flipped between the two reads) is
    /// left unwritten rather than healed under a digest that never attested it.
    ///
    /// The streamed digest is byte-identical to
    /// [`crate::repair::compute_table_checksum_with_overrides`] fed the same
    /// corrections: the file is hashed from `heal_start` to EOF with each
    /// size-preserving correction substituted at its offset. Corrections are
    /// non-overlapping and strictly increasing (block index order; one
    /// correction per block, within that block), so a single forward pass with a
    /// discard-the-replaced-bytes cursor reproduces exactly that byte stream.
    /// Skips a restricted view's punched prefix exactly as the write loop does.
    ///
    /// # Errors
    ///
    /// Any I/O error opening or streaming the file.
    #[cfg(feature = "page_ecc")]
    fn predict_heal_digest_and_offsets(
        &self,
        file: &dyn crate::fs::FsFile,
        transform: &crate::table::block::BlockTransform<'_>,
        heal_start: u64,
    ) -> crate::Result<(u128, crate::HashSet<u64>)> {
        use std::io::{Read, Seek, SeekFrom};

        let mut hasher = xxhash_rust::xxh3::Xxh3Default::new();
        let mut offsets = crate::HashSet::default();
        // A dedicated sequential reader for the digest stream: it walks forward
        // from `heal_start` while `file` still serves the per-block scrub reads.
        let mut rdr = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        rdr.seek(SeekFrom::Start(heal_start))?;
        let mut buf = alloc::vec![0u8; 256 * 1024];
        // Absolute file position the sequential reader has consumed up to.
        let mut pos = heal_start;

        // Reads exactly `count` bytes from `rdr`, hashing them when `hash` is set
        // and discarding them (the region a correction replaces) otherwise.
        let consume = |rdr: &mut alloc::boxed::Box<dyn crate::fs::FsFile>,
                       hasher: &mut xxhash_rust::xxh3::Xxh3Default,
                       buf: &mut [u8],
                       mut count: u64,
                       hash: bool|
         -> crate::Result<()> {
            while count > 0 {
                let want = usize::try_from(count.min(buf.len() as u64)).unwrap_or(buf.len());
                let Some(window) = buf.get_mut(..want) else {
                    break;
                };
                rdr.read_exact(window)?;
                if hash {
                    hasher.update(window);
                }
                count -= want as u64;
            }
            Ok(())
        };

        for entry in self.maintenance_index_walk() {
            // Propagate a transient index-read failure rather than `break`: a
            // truncated prediction would return a digest and an offset set that
            // omit every later block, and the write loop's `predicted_offsets`
            // guard would then silently skip any correctable fault it finds there,
            // reporting a clean heal while leaving known damage on disk. Aborting
            // makes the patrol report the failed pass and retry.
            let keyed = entry?;
            if let Some(bound) = &self.1
                && self.comparator.compare(keyed.end_key(), bound) == core::cmp::Ordering::Less
            {
                continue;
            }
            // An unreadable row-group directory aborts the prediction for the
            // same reason an index-read failure does: its pages would silently
            // drop out of the predicted offset set.
            let blocks = self.data_unit_blocks(keyed.as_ref())?;
            for (handle, role) in blocks {
                let Some((write_offset, bytes)) =
                    self.heal_correction_for_block(file, handle, role, transform)?
                else {
                    continue;
                };
                // Corrections are strictly increasing and non-overlapping, so a
                // regression means the block index is damaged (or restamped) — and
                // it must ABORT for the same reason the index-read failure above
                // does: stopping here would return a digest and an offset set that
                // omit every later block, and the write loop's `predicted_offsets`
                // guard would then silently skip any correctable fault it finds
                // there, reporting a clean heal over known damage.
                let Some(gap) = write_offset.checked_sub(pos) else {
                    return Err(crate::Error::InvalidHeader(
                        "block index yields a heal correction below the position already consumed",
                    ));
                };
                consume(&mut rdr, &mut hasher, &mut buf, gap, true)?;
                hasher.update(&bytes);
                let replaced = bytes.len() as u64;
                consume(&mut rdr, &mut hasher, &mut buf, replaced, false)?;
                pos = write_offset + replaced;
                offsets.insert(write_offset);
                // `bytes` is dropped here: only its offset is retained.
            }
        }

        // Hash the untouched tail from the last correction to EOF.
        loop {
            let n = rdr.read(&mut buf)?;
            if n == 0 {
                break;
            }
            let Some(window) = buf.get(..n) else { break };
            hasher.update(window);
        }

        Ok((hasher.digest128(), offsets))
    }

    /// Whether the file's CURRENT digest equals `manifest_checksum` — the
    /// attribution probe [`Self::heal_data_blocks_in_place`] takes right
    /// before its first write-back. The caller supplies the CURRENT
    /// manifest digest (read under the per-table heal lock), not this
    /// view's snapshot: a concurrent patrol may have refreshed the manifest
    /// after this view was captured, and comparing against the stale
    /// snapshot would mark a legitimate heal unattributable.
    ///
    /// # Errors
    ///
    /// A failed digest read PROPAGATES rather than grading `false`: the caller
    /// must abort the heal on a probe failure, because proceeding would write
    /// corrections with no completed attestation, and if the manifest
    /// legitimately described the pre-heal bytes the healed digest would then be
    /// permanently unreconcilable.
    #[cfg(feature = "page_ecc")]
    fn pre_heal_digest_matches(&self, manifest_checksum: Checksum) -> crate::Result<bool> {
        // Restriction-aware: a restricted view's manifest digest covers only its
        // live suffix, so probe the same region.
        Ok(self.live_region_checksum()? == manifest_checksum)
    }

    /// Whether the ON-DISK file carries deletion metadata the digest
    /// reconciliation cannot semantically authenticate: a `range_tombstones`
    /// or `delete_bitmap` section. These are AUTHORITATIVE — nothing in-file
    /// can re-derive which rows or ranges were genuinely deleted — so unlike
    /// the derived sections (zone map, seqno bounds, locator, filter) a
    /// re-stamped payload has no cross-check. Read from the file's TOC, not
    /// the recover-time regions, for the same distrust-of-memory reason as
    /// the other gates.
    ///
    /// # Errors
    ///
    /// Any I/O / decode error from reading the SFA trailer.
    #[cfg(feature = "std")]
    pub(crate) fn has_deletion_metadata(&self) -> crate::Result<bool> {
        let mut file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        let trailer = crate::sfa::Reader::from_reader(&mut file)?;
        let regions = regions::ParsedRegions::parse_from_toc(trailer.toc())?;
        Ok(regions.range_tombstones.is_some() || regions.delete_bitmap.is_some())
    }

    /// Scrub: verifies the per-KV checksum footer of every data block in this
    /// table, decoding each block and recomputing each entry's logical-content
    /// digest.
    ///
    /// Footer presence is a per-SST property read from the descriptor
    /// (`metadata.kv_checksum_algo`), not a per-block header flag — SST data
    /// blocks omit the `block_flags` byte. When the descriptor reports no
    /// footers the whole scrub is a no-op; otherwise every data block is
    /// verified under the descriptor's algorithm. This is the paranoid /
    /// offline integrity path — the live read path does NOT verify per-entry
    /// digests (the block-level checksum already covers the on-disk bytes).
    /// Stops and returns on the first detected mismatch.
    ///
    /// # Errors
    ///
    /// - [`crate::Error::ChecksumMismatch`] if any entry's recomputed digest
    ///   disagrees with the stored value (corruption of the entry bytes or
    ///   the stored digest).
    /// - Any I/O / decode error encountered while loading a block.
    #[cfg_attr(
        not(feature = "std"),
        allow(
            dead_code,
            reason = "core+alloc per-KV scrub over the table; the verify/scrub consumer is std-gated, so unused under no_std"
        )
    )]
    pub(crate) fn verify_kv_checksums(&self) -> crate::Result<()> {
        // Footer presence is a per-SST property recorded in the descriptor
        // (`kv_checksum_algo`); data blocks omit the block_flags byte, so the
        // descriptor is the authoritative source. When it reports no footers,
        // there is nothing to scrub.
        let Some(expected_algo) = self.metadata.kv_checksum_algo else {
            return Ok(());
        };

        // Descriptor declares this SST footer-bearing, and an SST is
        // homogeneous — every data block carries a footer under `expected_algo`.
        // A restricted view's punched prefix blocks are dead and read as zeros,
        // so the walk skips them (only the live suffix is footer-verified).
        self.for_each_live_block(|block| Self::check_block_kv_checksums(expected_algo, block))
    }

    /// The per-block half of [`Self::verify_kv_checksums`], so the combined
    /// reconcile pass runs it on the shared decode.
    ///
    /// Reads the footer off the RAW block (footer intact: the row view strips
    /// it) and judges the entries the walk ALREADY materialized from that same
    /// block. The bytes are disk-fresh, so a pristine copy cached before an
    /// on-disk re-stamp cannot stand in for a file whose stale footer no longer
    /// matches its altered value bytes.
    ///
    /// Fed from `block.entries` rather than through `verify_kv_checked`, which
    /// decodes and materializes the block for itself: on a footer-bearing table
    /// that would decode every block twice, and the read count would not show
    /// it — the second decode reads no additional bytes off the disk. Taking no
    /// comparator is what keeps it that way: decoding a data block needs one,
    /// so this cannot re-decode even by mistake.
    #[cfg_attr(
        not(feature = "std"),
        expect(
            dead_code,
            reason = "per-KV gate half; the verify/scrub consumers are std-gated"
        )
    )]
    fn check_block_kv_checksums(
        expected_algo: crate::runtime_config::types::ChecksumAlgorithm,
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        let mut probe = crate::table::data_block::KvDigestProbe::open(
            &block.raw.data,
            block.raw.header,
            Some(expected_algo),
        )?;
        for item in &block.entries {
            probe.observe(item)?;
        }
        probe.finish()
    }

    /// Cross-checks the recorded `linked_blob_files` section against the
    /// COMPLETE accounting derived from this table's indirection entries
    /// (per blob id: reference count, logical bytes, on-disk bytes). The
    /// section carries NO per-section checksum, so structurally valid rot —
    /// a flipped id byte OR a flipped counter byte — is invisible to the
    /// out-of-band walk; the entries themselves are the only integrity
    /// source, and the counters feed fragmentation math (a forged total can
    /// make a blob file look dead while another table still references it).
    /// Duplicate records for one id are rejected too. A no-op (`Ok`) for
    /// tables without the section.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the recorded records disagree
    /// with the derived ones; any I/O / decode error from the full scan.
    #[cfg(feature = "std")]
    pub(crate) fn verify_blob_links(&self) -> crate::Result<()> {
        use crate::coding::Decode;
        use alloc::collections::BTreeMap;

        // A restricted view's punched prefix is unscannable, so its derived
        // accounting can only cover the LIVE SUFFIX; the recorded section
        // aggregates the WHOLE table. An EXACT match is therefore impossible, but
        // skipping the check entirely lets a same-size bit flip in the
        // (checksum-less) section drop or forge a blob id the readable suffix
        // still addresses, after which blob GC can retire a file the suffix points
        // into. So a restricted view runs a CONTAINMENT check instead (see the
        // final comparison below): every id/count the suffix derives must be
        // COVERED BY the recorded aggregate. (This is orthogonal to the
        // heal-attribution the unrestricted exact check also provides: an in-place
        // heal rewrites DATA blocks only, never `linked_blob_files`.)
        let restricted = self.restrict_lower_bound().is_some();

        // Derive the indirection accounting FIRST, even when the section is
        // absent: a table that still carries `ValueHandle` indirections but
        // advertises no `linked_blob_files` section must NOT pass. Blob GC
        // consults `list_blob_file_references()` to decide whether other tables
        // reference a blob, so an accepted table with hidden indirections lets
        // GC rewrite / drop a blob file this table still points into.
        // (len, bytes, on_disk_bytes, first key, last key) per blob id,
        // accumulated exactly the way the writer folds them from indirections:
        // the scan yields keys in order, so the first key seen is the first
        // and the latest the last.
        let mut derived: BTreeMap<crate::vlog::BlobFileId, (usize, u64, u64, UserKey, UserKey)> =
            BTreeMap::new();
        // The objects the cell rows own, as the `owned_blob_objects` section
        // lists them.
        let mut derived_owned: Vec<(crate::vlog::BlobFileId, u64)> = Vec::new();
        {
            // An owned reference adds to its file's counts, a borrowed one
            // (a cell-row reference whose owner is another version) only
            // links the file, as the writer registers them.
            let mut add =
                |ind: &crate::blob_tree::handle::BlobIndirection, owned: bool, key: &UserKey| {
                    let slot = derived
                        .entry(ind.vhandle.blob_file_id)
                        .or_insert_with(|| (0, 0, 0, key.clone(), key.clone()));
                    if owned {
                        slot.0 += 1;
                        slot.1 += u64::from(ind.size);
                        slot.2 += u64::from(ind.vhandle.on_disk_size);
                    }
                    slot.4.clone_from(key);
                };
            let mut accumulate = |kv: InternalValue| -> crate::Result<()> {
                if kv.key.value_type == crate::ValueType::Indirection {
                    let mut cursor = &kv.value[..];
                    let ind = crate::blob_tree::handle::BlobIndirection::decode_from(&mut cursor)?;
                    add(&ind, true, &kv.key.user_key);
                } else if kv.key.value_type == crate::ValueType::CellRow {
                    for (ind, owned) in crate::blob_tree::field_row::row_refs(&kv.value)? {
                        add(&ind, owned, &kv.key.user_key);
                        if owned {
                            derived_owned.push((ind.vhandle.blob_file_id, ind.vhandle.offset));
                        }
                    }
                }
                Ok(())
            };
            // A restricted view's `[0, punch)` prefix is hole-punched and reads as
            // zeros: `range` raises its lower bound to the restriction so it never
            // loads a punched block, whereas `scan` walks every physical block from
            // offset 0 (and would fail decoding a zeroed one). Derive from the live
            // region accordingly; the restricted derive covers only the live suffix.
            // Like `scan`, the walk is verification: uncounted, and it leaves
            // the workload's block cache as it found it.
            if restricted {
                for kv in self.range_iter(..).untraced() {
                    accumulate(kv?)?;
                }
            } else {
                for kv in self.scan()? {
                    accumulate(kv?)?;
                }
            }
        }
        // The owned objects a drop of this table releases: a list that leaves
        // one out would let a reference to it be written back after the drop,
        // a row holding what the accounting already charged.
        self.verify_owned_blob_objects(derived_owned, restricted)?;
        let Some(recorded) = self.untraced_blob_file_references()? else {
            // No section is valid ONLY for a table with no indirections; a
            // non-empty derived map with no recorded section is a dropped /
            // renamed section hiding live blob references.
            if !derived.is_empty() {
                return Err(crate::Error::InvalidHeader(
                    "table carries indirection entries but no linked_blob_files section",
                ));
            }
            return Ok(());
        };
        // The writer OMITS the linked_blob_files section when there are no blob
        // references, so a PRESENT but empty (zero-count) section is a forgery,
        // not a legitimate no-op: e.g. a delete_bitmap replaced by a four-byte
        // zero-count linked_blob_files. Both `derived` and `recorded_map` would
        // then be empty and the equality check below would pass, keeping the
        // table after its deletion metadata vanished. Reject it here.
        if recorded.is_empty() {
            return Err(crate::Error::InvalidHeader(
                "linked_blob_files section is present but records no blob references",
            ));
        }
        let mut recorded_map: BTreeMap<
            crate::vlog::BlobFileId,
            (usize, u64, u64, UserKey, UserKey),
        > = BTreeMap::new();
        for link in recorded {
            if recorded_map
                .insert(
                    link.blob_file_id,
                    (
                        link.len,
                        link.bytes,
                        link.on_disk_bytes,
                        link.first_key,
                        link.last_key,
                    ),
                )
                .is_some()
            {
                return Err(crate::Error::InvalidHeader(
                    "linked_blob_files carries duplicate records for one blob id",
                ));
            }
        }
        if restricted {
            // Containment: the recorded aggregate covers the WHOLE table, so each
            // id the live suffix references must appear with a count/byte total at
            // least as large as the suffix's own. A suffix-referenced id missing
            // from the section, or recorded below the suffix's derived total,
            // means the section dropped or under-counted a live reference — reject
            // so blob GC cannot retire a file the suffix still addresses.
            // The recorded key span covers the whole table's references, so it
            // must enclose the span the suffix derives.
            let cmp = self.comparator.as_ref();
            for (id, derived_counts) in &derived {
                match recorded_map.get(id) {
                    Some(rec)
                        if rec.0 >= derived_counts.0
                            && rec.1 >= derived_counts.1
                            && rec.2 >= derived_counts.2
                            && cmp.compare(&rec.3, &derived_counts.3)
                                != core::cmp::Ordering::Greater
                            && cmp.compare(&rec.4, &derived_counts.4)
                                != core::cmp::Ordering::Less => {}
                    _ => {
                        return Err(crate::Error::InvalidHeader(
                            "linked_blob_files omits or under-counts a blob id the \
                             restricted suffix still references",
                        ));
                    }
                }
            }
            return Ok(());
        }
        if derived != recorded_map {
            return Err(crate::Error::InvalidHeader(
                "linked_blob_files disagrees with the table's indirection entries",
            ));
        }
        Ok(())
    }

    /// Cross-checks the `owned_blob_objects` section against `derived`, the
    /// objects the scanned cell rows own: equal for a whole table, containing
    /// them for a `restricted` view, whose punched prefix cannot be scanned.
    /// The writer omits the section when the table owns nothing, so a present
    /// but empty one is a forgery.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the section disagrees, and any
    /// error reading it.
    #[cfg(feature = "std")]
    fn verify_owned_blob_objects(
        &self,
        mut derived: Vec<(crate::vlog::BlobFileId, u64)>,
        restricted: bool,
    ) -> crate::Result<()> {
        let recorded = self.owned_blob_objects()?;
        if self.regions.owned_blob_objects.is_some() && recorded.is_empty() {
            return Err(crate::Error::InvalidHeader(
                "owned_blob_objects section is present but lists no object",
            ));
        }
        derived.sort_unstable();
        derived.dedup();
        let agrees = if restricted {
            derived
                .iter()
                .all(|object| recorded.binary_search(object).is_ok())
        } else {
            derived == recorded
        };
        if !agrees {
            return Err(crate::Error::InvalidHeader(
                "owned_blob_objects disagrees with the objects the table's cell rows own",
            ));
        }
        Ok(())
    }

    /// Compares the two DECODED TLI mirrors (head `tli` vs `tli_tail`) and
    /// validates the decoded handle list against the PHYSICAL section
    /// layout. Each copy is independently checksum- (and parity-)consistent,
    /// so a forged tail that encodes a DIFFERENT handle list passes every
    /// byte-level check — and BOTH mirrors forged to the SAME list pass the
    /// equality comparison too, since two forged copies prove nothing about
    /// the data blocks. The writer emits blocks strictly back-to-back, so
    /// the decoded handles must exactly TILE their section: in full-index
    /// mode the handles tile the `data` section; in partitioned mode the TLI
    /// handles tile the `index` section and the partitions' concatenated
    /// data handles tile the `data` section. An omitted, redirected, or
    /// duplicated handle leaves a gap or an overlap.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the decoded mirrors differ or
    /// the handle list does not tile the physical sections; any I/O / decode
    /// error while loading either copy (an unreadable mirror is equally
    /// untrustworthy for the callers' restamp / keep decisions).
    #[cfg(feature = "std")]
    pub(crate) fn verify_tli_mirrors(&self) -> crate::Result<()> {
        self.verify_tli_mirrors_inner(true)
    }

    /// Whether the index STRUCTURE alone authenticates its offsets as original
    /// block boundaries: the mirrors agree, the binary-index pointers verify,
    /// the partition separators are consistent, and the handles TILE their
    /// section. This is the block-boundary provenance the salvage walk needs to
    /// trust an indexed offset without re-reading each (possibly corrupt) data
    /// block — [`verify_tli_mirrors`](Self::verify_tli_mirrors) additionally
    /// frames and decodes every data block, which a bit-rotted-but-index-intact
    /// table (the salvage case) would fail spuriously.
    ///
    /// # Errors
    ///
    /// Propagates only a TRANSIENT [`crate::Error::Io`] from opening / reading
    /// the index mirrors: folding a flaky read into `false` would make the
    /// salvage walk fall back to physical-chain provenance and surrender every
    /// block past the first header break, dropping otherwise healthy keys the
    /// intact TLI could have anchored on retry. `Ok(false)` covers a STRUCTURAL
    /// authentication failure (mirrors disagree, pointers do not verify, handles
    /// do not tile) AND a PERSISTENT read failure of one mirror: both mean the
    /// index cannot be trusted here, so the walk should fall back to the readable
    /// data section rather than abort and recover nothing.
    #[cfg(feature = "std")]
    pub(crate) fn tli_structure_authenticated(&self) -> crate::Result<bool> {
        match self.verify_tli_mirrors_inner(false) {
            Ok(()) => Ok(true),
            // Only an ENVIRONMENTAL read propagates (so the salvage walk aborts
            // for a retry, or for the right key, rather than surrendering an
            // intact index to a fixable fault — `false` costs every indexed
            // block past the first header break). A failure on the DATA (a
            // bad-sector `UnexpectedEof` on one mirror while the other and the
            // data section stay readable) is untrusted input, not a reason to
            // abort: fold it into `false` so the walk falls back to
            // physical-chain provenance and still recovers the readable blocks.
            Err(e) if e.is_environmental() => Err(e),
            Err(_) => Ok(false),
        }
    }

    /// Shared body. `frame_blocks` additionally frames and decodes each
    /// addressed DATA block (the full integrity check the scrub reconcile
    /// wants); with it `false` only the index structure is authenticated, for
    /// the salvage walk that runs over corrupt data blocks by design.
    #[cfg(feature = "std")]
    fn verify_tli_mirrors_inner(&self, frame_blocks: bool) -> crate::Result<()> {
        use crate::table::block::ParsedItem as _;

        let mut file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        let trailer = crate::sfa::Reader::from_reader(&mut file)?;
        let regions = regions::ParsedRegions::parse_from_toc(trailer.toc())?;
        let head = Self::read_tli_at(
            &*file,
            regions.tli,
            self.metadata.id,
            self.metadata.index_block_compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
        )?;
        if let Some(tail_handle) = regions.tli_tail {
            let tail = Self::read_tli_at(
                &*file,
                tail_handle,
                self.metadata.id,
                self.metadata.index_block_compression,
                self.encryption.as_deref(),
                self.metadata.ecc_params,
            )?;
            if head.as_slice() != tail.as_slice() {
                return Err(crate::Error::InvalidHeader(
                    "tli_tail decodes to a different handle list than the head tli",
                ));
            }
        }

        // Structural coverage: the decoded handles must tile their section.
        let data_section = trailer
            .toc()
            .section(b"data")
            .ok_or(crate::Error::InvalidHeader("data section missing"))?;
        head.try_iter(self.comparator.clone())?;
        // The sequential walk below never reads the BINARY INDEX pointers,
        // so a pointer redirected to another restart head passes mirror
        // equality, tiling, and every separator check — yet the seek path
        // trusts it after reopen. Authenticate the pointers against the
        // sequentially derived restart heads.
        head.verify_binary_index()?;
        let keyed: alloc::vec::Vec<KeyedBlockHandle> = head
            .iter(self.comparator.clone())
            .map(|i| i.materialize(head.as_slice()))
            .collect();
        let handles: alloc::vec::Vec<BlockHandle> = keyed.iter().map(|k| *k.as_ref()).collect();
        if let Some(index_handle) = regions.index {
            // Partitioned: the TLI addresses index partitions inside the
            // `index` section; the partitions address the data blocks.
            let index_section = trailer
                .toc()
                .section(b"index")
                .ok_or(crate::Error::InvalidHeader("index section missing"))?;
            let _ = index_handle;
            if !Self::frames_tile_section(&handles, index_section.pos(), index_section.len()) {
                return Err(crate::Error::InvalidHeader(
                    "tli handles do not tile the index section",
                ));
            }
            self.verify_handles_frame_blocks(
                &handles,
                index_section.pos(),
                index_section.len(),
                FrameUnit::Block,
            )?;
            let mut data_handles = alloc::vec::Vec::new();
            for top in &keyed {
                let part = Self::read_tli_at(
                    &*file,
                    *top.as_ref(),
                    self.metadata.id,
                    self.metadata.index_block_compression,
                    self.encryption.as_deref(),
                    self.metadata.ecc_params,
                )?;
                part.try_iter(self.comparator.clone())?;
                // Same pointer authentication as the TLI above: a partition
                // seek trusts its binary index too.
                part.verify_binary_index()?;
                let part_keyed: alloc::vec::Vec<KeyedBlockHandle> = part
                    .iter(self.comparator.clone())
                    .map(|i| i.materialize(part.as_slice()))
                    .collect();
                // The TLI's top-level SEPARATOR for this partition must equal the
                // partition's LAST data-block separator. `frames_tile_section`
                // and the per-block separator checks ignore the top-level keys,
                // so a re-stamped partition boundary (in both mirrors) passes
                // them all — yet `TwoLevelBlockIndex::forward_reader` seeks by the
                // top-level separator and would route reads to the wrong
                // partition, skipping the keys the real partition holds.
                let Some(part_last) = part_keyed.last() else {
                    return Err(crate::Error::InvalidHeader(
                        "tli addresses an index partition that decodes to zero entries",
                    ));
                };
                if self
                    .comparator
                    .compare(top.end_key().as_ref(), part_last.end_key().as_ref())
                    != core::cmp::Ordering::Equal
                {
                    return Err(crate::Error::InvalidHeader(
                        "tli separator disagrees with its partition's last separator",
                    ));
                }
                data_handles.extend(part_keyed.iter().map(|k| *k.as_ref()));
            }
            if !Self::frames_tile_section(&data_handles, data_section.pos(), data_section.len()) {
                return Err(crate::Error::InvalidHeader(
                    "index partitions' data handles do not tile the data section",
                ));
            }
            if frame_blocks {
                self.verify_handles_frame_blocks(
                    &data_handles,
                    data_section.pos(),
                    data_section.len(),
                    FrameUnit::DataUnit,
                )?;
            }
        } else {
            if !Self::frames_tile_section(&handles, data_section.pos(), data_section.len()) {
                return Err(crate::Error::InvalidHeader(
                    "tli data handles do not tile the data section",
                ));
            }
            if frame_blocks {
                self.verify_handles_frame_blocks(
                    &handles,
                    data_section.pos(),
                    data_section.len(),
                    FrameUnit::DataUnit,
                )?;
            }
        }
        Ok(())
    }

    /// Requires every handle's SIZE to equal the physical frame its block's
    /// on-disk header derives (header + payload + parity). The cumulative
    /// tiling check cannot tell ONE handle spanning several back-to-back
    /// blocks from the real per-block layout: the spanned frame still
    /// decodes its FIRST payload (the tail reads as an unrecognized trailer
    /// on a non-ECC block), so the separator cross-check passes too — yet
    /// every later physical block is unreachable through the index and
    /// reads silently miss its keys.
    ///
    /// `unit` says what one handle names in this section: a block for the
    /// index section, a data unit for the data section. A columnar table's
    /// data unit is a row group — several blocks under one handle by design —
    /// so its frame is the group's, and the protection still holds: a forged
    /// handle spanning two groups disagrees with the frame of one.
    #[cfg(feature = "std")]
    fn verify_handles_frame_blocks(
        &self,
        handles: &[BlockHandle],
        pos: u64,
        len: u64,
        unit: FrameUnit,
    ) -> crate::Result<()> {
        // checked, not saturating: a re-stamped TOC could overflow `pos + len`,
        // and a saturated `u64::MAX` bound would then accept a forged oversized
        // handle instead of rejecting the corrupt section.
        let section_end = pos
            .checked_add(len)
            .ok_or(crate::Error::InvalidHeader("data section length overflows"))?;
        // A restricted view's punched prefix blocks read as zeros, so their
        // physical frame can no longer be probed. They tile the section by
        // length (punch preserves file size) but are dead, so skip framing
        // them. Index-section handles sit above the (data-section) punch
        // offset and are never skipped.
        let punch = self.punch_offset()?;
        let file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        for handle in handles {
            if handle.offset().0 < punch {
                continue;
            }
            let probed = match unit {
                FrameUnit::Block => {
                    self.probe_block_handle_in(&*file, handle.offset().0, section_end)?
                }
                FrameUnit::DataUnit => {
                    self.probe_data_unit_in(&*file, handle.offset().0, section_end)?
                }
            };
            if probed.size() != handle.size() {
                return Err(crate::Error::InvalidHeader(
                    "an index handle's size disagrees with its block's physical frame",
                ));
            }
        }
        Ok(())
    }

    /// Whether `handles`, in order, exactly tile `[pos, pos + len)`: the
    /// first starts at `pos`, each next starts where the previous ended, and
    /// the last ends at `pos + len`. The writer emits blocks back-to-back,
    /// so any omitted, redirected, or duplicated handle breaks the tiling.
    #[cfg(feature = "std")]
    fn frames_tile_section(handles: &[BlockHandle], pos: u64, len: u64) -> bool {
        let mut at = pos;
        for handle in handles {
            if handle.offset().0 != at {
                return false;
            }
            at = match at.checked_add(u64::from(handle.size())) {
                Some(v) => v,
                None => return false,
            };
        }
        pos.checked_add(len) == Some(at)
    }

    /// Reads the disk-fresh leaf SEPARATORS: each live data block's offset
    /// mapped to the `end_key` the on-disk index records for it. `None` for a
    /// table whose index carries no entries at all.
    ///
    /// Tail-first with head fallback, mirroring recovery ([`Self::read_tli`]):
    /// the next open trusts that copy, so it is the one the separators must be
    /// judged from. Mirror EQUALITY is not this reader's job —
    /// [`Self::verify_tli_mirrors`] establishes it, along with the section
    /// tiling, the binary-index pointers and (when partitioned) the top-level
    /// partition boundaries.
    ///
    /// Blocks below the punch offset are left out: a restricted view's punched
    /// prefix decodes to zeros, so those separators are dead and the walk skips
    /// their blocks too.
    ///
    /// # Errors
    ///
    /// Propagates the index reads, and rejects an index partition that decodes
    /// to zero entries.
    #[cfg(feature = "std")]
    fn read_tli_separators(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
    ) -> crate::Result<crate::HashMap<u64, UserKey>> {
        let punch = self.punch_offset()?;
        let head = Self::read_tli(
            regions,
            file,
            self.metadata.id,
            self.metadata.index_block_compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
        )?;
        let mut separators = crate::HashMap::default();
        let mut collect = |idx: &IndexBlock| -> crate::Result<()> {
            for keyed in idx.iter(self.comparator.clone()) {
                let keyed = keyed.materialize(idx.as_slice());
                if keyed.offset().0 < punch {
                    continue;
                }
                separators.insert(keyed.offset().0, keyed.end_key().clone());
            }
            Ok(())
        };
        if regions.index.is_some() {
            // Partitioned: the top level addresses index partitions, and the
            // partitions address the data blocks whose separators are wanted.
            let tops: Vec<BlockHandle> = head
                .iter(self.comparator.clone())
                .map(|i| *i.materialize(head.as_slice()).as_ref())
                .collect();
            for top in tops {
                let part = Self::read_tli_at(
                    file,
                    top,
                    self.metadata.id,
                    self.metadata.index_block_compression,
                    self.encryption.as_deref(),
                    self.metadata.ecc_params,
                )?;
                collect(&part)?;
            }
        } else {
            collect(&head)?;
        }
        Ok(separators)
    }

    /// Confirms a data block's decoded LAST key equals the separator the
    /// on-disk index records for it. A forged separator re-stamped to another
    /// still-sorted value passes the mirror comparison and the section tiling
    /// (both ignore the keys), yet the index binary search then routes keys in
    /// `(forged_separator, real_last_key]` to the wrong block and `point_read`
    /// misses them after reopen.
    ///
    /// Judged on the walk's decode, and paired BOTH ways: a live block the
    /// index does not address is as much corruption as an addressed block whose
    /// contents disagree, and only the pairing catches the first.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the block has no separator, decodes
    /// to zero entries, or disagrees with its separator.
    #[cfg(feature = "std")]
    fn check_block_separator(
        &self,
        separators: &crate::HashMap<u64, UserKey>,
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        let Some(separator) = separators.get(&block.handle.offset().0) else {
            return Err(crate::Error::InvalidHeader(
                "a live data block carries no tli separator",
            ));
        };
        let Some(last) = block.entries.last() else {
            return Err(crate::Error::InvalidHeader(
                "tli separator addresses a data block that decodes to zero entries",
            ));
        };
        if self
            .comparator
            .compare(separator.as_ref(), last.key.user_key.as_ref())
            != core::cmp::Ordering::Equal
        {
            return Err(crate::Error::InvalidHeader(
                "tli separator does not match the addressed block's decoded last key",
            ));
        }
        Ok(())
    }

    /// Runs the whole semantic cross-check family on ONE disk-fresh decode per
    /// live data block.
    ///
    /// Each gate used to walk the table itself, so a reconcile decoded every
    /// block seven to nine times and every gate added another full pass. Here
    /// the sections are read once, the blocks are decoded once, and each
    /// block feeds every per-block check before the next block is read.
    ///
    /// The gates run in the order the callers' own chains use, so a table with
    /// a single defect reports the same gate — and the same message — as
    /// before. `Err` names the gate that tripped, so a caller can keep its own
    /// per-gate wording.
    ///
    /// # Errors
    ///
    /// The failing gate and its error. Section reads and block decodes surface
    /// as the error of the gate that needed them.
    #[cfg(feature = "std")]
    pub(crate) fn verify_reconcile_gates(
        &self,
        prefix_extractor: Option<&alloc::sync::Arc<dyn crate::prefix::PrefixExtractor>>,
        bitmap_digest_authenticated: bool,
    ) -> Result<(), (ReconcileGate, crate::Error)> {
        use ReconcileGate as G;
        let tag = |gate: G| move |e: crate::Error| (gate, e);

        // Sections first: every gate that has one reads it before the walk, so
        // a forged section fails without decoding a single block.
        let kv_algo = self.metadata.kv_checksum_algo;
        // One open and one TOC parse for the whole pass: every section below is
        // read from the SAME on-disk image, so the gates cannot disagree about
        // which bytes they are judging.
        //
        // The sections stay live for the whole walk, where the gate-by-gate
        // shape held one at a time. That is a peak of their SUM rather than
        // their max, bounded by what an open table already pins permanently
        // (`Inner` holds the seqno bounds, zone map, locator and filter
        // simultaneously for its whole lifetime), so the increment is one extra
        // copy of resident data for the duration of one table's pass. Dropping
        // any of them mid-walk is not available: every one is consulted on
        // EVERY block, so releasing early means walking again per section,
        // which is the cost this pass exists to remove.
        let (file, regions) = self.open_sections().map_err(tag(G::SeqnoBounds))?;
        let separators = self
            .read_tli_separators(&*file, &regions)
            .map_err(tag(G::Separators))?;
        let seqno_bounds = self
            .read_seqno_bounds_section(&*file, &regions)
            .map_err(tag(G::SeqnoBounds))?;
        let zone_map = self
            .read_zone_map_section(&*file, &regions)
            .map_err(tag(G::ZoneMap))?;
        let zone_map = match zone_map {
            // A PRESENT-but-empty map on a table with data blocks is a forgery;
            // the standalone gate rejects it before its walk, so do it here.
            Some(map) if map.is_empty() => {
                if self.untraced_index_walk().next().is_some() {
                    return Err((
                        G::ZoneMap,
                        crate::Error::InvalidHeader(
                            "zone_map section is present but empty on a table with data blocks",
                        ),
                    ));
                }
                None
            }
            other => other,
        };
        let locator = self
            .read_locator_section(&*file, &regions)
            .map_err(tag(G::Locator))?;
        let mut filter = self
            .filter_probe(&*file, &regions, prefix_extractor)
            .map_err(tag(G::Filter))?;
        let mut meta = self
            .meta_bounds_probe(&*file, &regions, bitmap_digest_authenticated)
            .map_err(tag(G::MetadataBounds))?;
        // The per-frame half of the block-layout check. The section-level half
        // (present-but-empty, which is a relabelled delete_bitmap dropping the
        // deletion metadata) stays in `verify_block_layout`, where it runs on
        // EVERY build; this half needs a zstd decoder and the frame the walk
        // already has.
        #[cfg(feature = "zstd")]
        let block_layout = self
            .read_block_layout_section(&*file, &regions)
            .map_err(tag(G::BlockLayout))?
            .filter(|map| !map.is_empty());

        // Per-block state the gates carry across the walk.
        let mut separators_checked = 0usize;
        let mut seqno_checked = 0usize;
        let mut zone_checked = 0usize;
        #[cfg(feature = "zstd")]
        let mut layout_checked = 0usize;
        let mut locator_seen: crate::HashSet<Vec<u8>> = crate::HashSet::default();
        let mut prev_internal: Option<(UserKey, SeqNo)> = None;
        // The hash of each entry's key of the block being checked, taken once a
        // key for the locator and filter gates, which both probe by it.
        let mut entry_hashes: Vec<u64> = Vec::new();

        // The walk's closure returns the plain engine error, so the gate that
        // produced it is recorded here and paired with it after the walk.
        let mut failed: Option<ReconcileGate> = None;
        let walk = self.for_each_live_block(|block| {
            // First, as the standalone separator pass ran before every other
            // gate in both callers' chains.
            if let Err(e) = self.check_block_separator(&separators, block) {
                failed = Some(G::Separators);
                return Err(e);
            }
            let Some(next) = separators_checked.checked_add(1) else {
                failed = Some(G::Separators);
                return Err(crate::Error::InvalidHeader("tli separators"));
            };
            separators_checked = next;
            if let Some(algo) = kv_algo
                && let Err(e) = Self::check_block_kv_checksums(algo, block)
            {
                failed = Some(G::KvChecksums);
                return Err(e);
            }
            if let Some(map) = &seqno_bounds {
                if let Err(e) = Self::check_block_seqno_bounds(map, block) {
                    failed = Some(G::SeqnoBounds);
                    return Err(e);
                }
                let Some(next) = seqno_checked.checked_add(1) else {
                    failed = Some(G::SeqnoBounds);
                    return Err(crate::Error::InvalidHeader("seqno_bounds"));
                };
                seqno_checked = next;
            }
            if let Err(e) = Self::check_block_entry_count(block) {
                failed = Some(G::BlockEntryCounts);
                return Err(e);
            }
            if let Some(map) = &zone_map {
                if let Err(e) = Self::check_block_zone_entry(map, block) {
                    failed = Some(G::ZoneMap);
                    return Err(e);
                }
                let Some(next) = zone_checked.checked_add(1) else {
                    failed = Some(G::ZoneMap);
                    return Err(crate::Error::InvalidHeader("zone_map"));
                };
                zone_checked = next;
            }
            if locator.is_some() || filter.is_some() {
                entry_hashes.clear();
                let mut previous: Option<(&[u8], u64)> = None;
                for entry in &block.entries {
                    let key: &[u8] = &entry.key.user_key;
                    // A key's versions are adjacent and share its hash.
                    let hash = match previous {
                        Some((previous, hash))
                            if crate::comparator::same_user_key(previous, key) =>
                        {
                            hash
                        }
                        _ => crate::hash::hash64(key),
                    };
                    entry_hashes.push(hash);
                    previous = Some((key, hash));
                }
            }
            if let Some(locator) = &locator
                && let Err(e) =
                    self.check_block_locator(locator, &mut locator_seen, block, &entry_hashes)
            {
                failed = Some(G::Locator);
                return Err(e);
            }
            if let Some(probe) = &mut filter
                && let Err(e) = probe.check_block(block, &entry_hashes)
            {
                failed = Some(G::Filter);
                return Err(e);
            }
            if let Err(e) = self.check_block_reachability(&mut prev_internal, block) {
                failed = Some(G::PointReadReachability);
                return Err(e);
            }
            if let Err(e) = Self::observe_meta_bounds(&mut meta, block) {
                failed = Some(G::MetadataBounds);
                return Err(e);
            }
            #[cfg(feature = "zstd")]
            if let Some(map) = &block_layout {
                match Self::check_block_layout_entry(map, block) {
                    Err(e) => {
                        failed = Some(G::BlockLayout);
                        return Err(e);
                    }
                    // Blocks absent from the map are single-inner-block frames
                    // the writer had nothing to record for.
                    Ok(false) => {}
                    Ok(true) => {
                        let Some(next) = layout_checked.checked_add(1) else {
                            failed = Some(G::BlockLayout);
                            return Err(crate::Error::InvalidHeader("block_layout"));
                        };
                        layout_checked = next;
                    }
                }
            }
            Ok(())
        });
        if let Err(e) = walk {
            // An untagged failure came from the walk itself (an index read, a
            // block read, a decode), which is the entry-count gate's own job.
            return Err((failed.unwrap_or(G::BlockEntryCounts), e));
        }

        // Finalizers: the counts the per-block checks accumulated.
        //
        // The separator pairing closes the other direction: the per-block half
        // rejects a live block the index does not address, this rejects a live
        // separator no walked block claimed. The standalone pass could express
        // neither — it walked the index side alone.
        if separators_checked != separators.len() {
            return Err((
                G::Separators,
                crate::Error::InvalidHeader(
                    "the index carries separators for blocks it does not hold",
                ),
            ));
        }
        let punch = self.punch_offset().map_err(tag(G::SeqnoBounds))?;
        if let Some(map) = &seqno_bounds
            && seqno_checked != map.live_len(punch)
        {
            return Err((
                G::SeqnoBounds,
                crate::Error::InvalidHeader(
                    "seqno_bounds carries entries for blocks the index does not hold",
                ),
            ));
        }
        if let Some(map) = &zone_map
            && zone_checked != map.live_len(punch)
        {
            return Err((
                G::ZoneMap,
                crate::Error::InvalidHeader(
                    "zone_map carries entries for blocks the index does not hold",
                ),
            ));
        }
        // Every recorded LIVE entry matched a walked block (offsets are unique
        // on both sides), so equal counts mean the map records ONLY this
        // table's blocks. A restricted view compares against the live entries:
        // its punched prefix keeps its own, legitimately, because the map is
        // not rewritten on reopen.
        #[cfg(feature = "zstd")]
        if let Some(map) = &block_layout
            && layout_checked != map.live_len(punch)
        {
            return Err((
                G::BlockLayout,
                crate::Error::InvalidHeader(
                    "block_layout carries entries for blocks the index does not hold",
                ),
            ));
        }
        self.finish_meta_bounds(meta)
            .map_err(tag(G::MetadataBounds))
    }

    /// Opens the file and parses its TOC: the pair every reconcile section read
    /// works from. Done ONCE per pass and lent to each reader, so a reconcile
    /// costs one open and one TOC parse instead of one per section, and every
    /// gate judges the SAME on-disk image rather than up to five successive
    /// ones.
    ///
    /// # Errors
    ///
    /// Propagates the file open, the SFA trailer read and the TOC parse.
    #[cfg(feature = "std")]
    fn open_sections(
        &self,
    ) -> crate::Result<(
        alloc::boxed::Box<dyn crate::fs::FsFile>,
        regions::ParsedRegions,
    )> {
        let mut file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        let trailer = crate::sfa::Reader::from_reader(&mut file)?;
        let regions = regions::ParsedRegions::parse_from_toc(trailer.toc())?;
        Ok((file, regions))
    }

    /// Reads the `seqno_bounds` section FROM DISK, or `None` when the table
    /// has none.
    ///
    /// Disk-fresh on purpose: the in-memory map was loaded at recover time, so
    /// an on-disk re-stamp after the open — the very forge this gate exists
    /// for — would be invisible to it. Unlike the best-effort recover load, an
    /// unreadable section is an error here: the callers are deciding whether to
    /// trust the file's bytes.
    ///
    /// # Errors
    ///
    /// Propagates the section decode, and rejects a block that does not carry
    /// the seqno-bounds role.
    #[cfg(feature = "std")]
    fn read_seqno_bounds_section(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
    ) -> crate::Result<Option<crate::table::seqno_bounds::SeqnoBoundsMap>> {
        let Some(sb_handle) = regions.seqno_bounds else {
            return Ok(None);
        };
        let block = Block::from_file(
            file,
            sb_handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type: BlockType::SeqnoBounds,
                dict_id: 0,
                window_log: 0,
            },
            &self.section_transform(),
        )?;
        if block.header.block_type != BlockType::SeqnoBounds {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        Ok(Some(crate::table::seqno_bounds::SeqnoBoundsMap::decode(
            &block.data,
        )?))
    }

    /// The encryption / ECC context the uncompressed side sections decode
    /// under. Every reconcile section read builds the same one.
    #[cfg(feature = "std")]
    fn section_transform(&self) -> crate::table::block::BlockTransform<'_> {
        let t = match self.encryption.as_deref() {
            Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
            None => crate::table::block::BlockTransform::PLAIN,
        };
        if let Some(ecc) = self.metadata.ecc_params {
            t.with_ecc(ecc)
        } else {
            t
        }
    }

    /// The recorded per-block seqno range must equal the one the block's
    /// decoded entries span.
    #[cfg(feature = "std")]
    fn check_block_seqno_bounds(
        recorded_map: &crate::table::seqno_bounds::SeqnoBoundsMap,
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        let Some(recorded) = recorded_map.bounds_for(block.handle.offset().0) else {
            return Err(crate::Error::InvalidHeader(
                "seqno_bounds is missing a data block's entry",
            ));
        };
        let mut seqnos = block.entries.iter().map(|e| e.key.seqno);
        let Some(first) = seqnos.next() else {
            return Err(crate::Error::InvalidHeader(
                "data block decodes to zero entries",
            ));
        };
        let derived = seqnos.fold((first, first), |(lo, hi), s| (lo.min(s), hi.max(s)));
        if derived != recorded {
            return Err(crate::Error::InvalidHeader(
                "seqno_bounds disagrees with the block's decoded entries",
            ));
        }
        Ok(())
    }

    /// Checks a block's declared entry count against the DECODED one. The
    /// out-of-band walk verifies only the outer frame, and `verify_kv_checksums`
    /// is a no-op for a footer-less SST, so a checksum- and parity-consistent
    /// block with a valid prefix followed by a malformed entry is otherwise
    /// graded clean: the entry decoder turns a mid-stream parse failure into an
    /// ordinary end of iteration, so a later scan silently omits the malformed
    /// tail. Decoding to fewer (or more) entries than the trailer declares is
    /// corruption. Covers both row-major and columnar blocks.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the block decodes to a different
    /// entry count than its trailer declares.
    #[cfg(feature = "std")]
    fn check_block_entry_count(block: &DecodedBlock) -> crate::Result<()> {
        #[cfg(feature = "columnar")]
        if let Some(batch) = &block.batch {
            // The entries were fully materialized by the walk, so a malformed
            // batch already failed there rather than truncating silently.
            if block.entries.len() != batch.row_count as usize {
                return Err(crate::Error::InvalidHeader(
                    "columnar block decodes to fewer rows than its batch declares",
                ));
            }
            return Ok(());
        }
        let Some(row) = &block.row else {
            return Ok(());
        };
        if block.entries.len() != row.len() {
            return Err(crate::Error::InvalidHeader(
                "data block decodes to fewer entries than its trailer declares",
            ));
        }
        Ok(())
    }

    /// Reads the `zone_map` section FROM DISK, or `None` when the table has
    /// none. Disk-fresh for the same reason as the seqno bounds: the in-memory
    /// map is best-effort at recover time, so an on-disk re-stamp after the
    /// open is invisible to it.
    ///
    /// # Errors
    ///
    /// Propagates the section decode, and rejects a block that does not carry
    /// the zone-map role.
    #[cfg(feature = "std")]
    fn read_zone_map_section(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
    ) -> crate::Result<Option<crate::table::zone_map::ZoneMap>> {
        let Some(zm_handle) = regions.zone_map else {
            return Ok(None);
        };
        let block = Block::from_file(
            file,
            zm_handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type: BlockType::ZoneMap,
                dict_id: 0,
                window_log: 0,
            },
            &self.section_transform(),
        )?;
        if block.header.block_type != BlockType::ZoneMap {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        Ok(Some(crate::table::zone_map::ZoneMap::decode(&block.data)?))
    }

    /// Reads the `block_layout` section FROM DISK, or `None` when the table
    /// has none.
    ///
    /// Disk-fresh for the same reason every other reconcile section is: the
    /// in-memory copy was loaded at recover time and would not show an on-disk
    /// re-stamp made after the open.
    ///
    /// The encryption-aware transform is not optional here. On an encrypted
    /// table the section is AEAD-sealed and its AAD binds the block type, so a
    /// `delete_bitmap` relabelled into a `block_layout` fails to open — which
    /// is precisely the forgery the emptiness check downstream exists to
    /// catch.
    ///
    /// # Errors
    ///
    /// Propagates the section decode, and rejects a block that does not carry
    /// the block-layout role.
    #[cfg(all(feature = "std", feature = "zstd"))]
    fn read_block_layout_section(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
    ) -> crate::Result<Option<crate::table::block_layout::BlockLayoutMap>> {
        let Some(bl_handle) = regions.block_layout else {
            return Ok(None);
        };
        let block = Block::from_file(
            file,
            bl_handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type: BlockType::BlockLayout,
                dict_id: 0,
                window_log: 0,
            },
            &self.section_transform(),
        )?;
        if block.header.block_type != BlockType::BlockLayout {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        Ok(Some(crate::table::block_layout::BlockLayoutMap::decode(
            &block.data,
        )?))
    }

    /// The recorded zone-map entry must match the one the block's decoded
    /// contents produce. A columnar block records
    /// one entry per stored column, re-derived by the SAME function the writer
    /// used, so any divergence (a re-stamped range, an added / dropped column,
    /// a flipped id) is a forgery; a row block records a single synthetic
    /// whole-block key range.
    /// Every boundary the map records for this block must be exactly where the
    /// frame's k-th inner zstd block ends, and the last one must EXHAUST the
    /// frame: an unrecorded inner block past the final boundary would hide
    /// data the partial-read path never decompresses.
    ///
    /// Decodes one inner block per recorded end, carrying the resume state and
    /// the accumulated window forward, so `n` boundaries cost `n` inner-block
    /// decodes. The stepwise-from-zero shape this replaces re-decoded the
    /// prefix `[0, k)` for every `k`, i.e. `n(n+1)/2`.
    ///
    /// A zstd reset / decode failure on a checksum-clean frame is DETERMINISTIC
    /// codec corruption (a forge that kept the block checksum but broke the
    /// inner framing), not transient I/O: it maps to the structural error so
    /// the repair gate routes the table through salvage, which re-encodes the
    /// block, instead of aborting for a retry that can never succeed.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the boundaries are not strictly
    /// increasing, disagree with the frame's inner blocks, or leave the frame
    /// unfinished.
    #[cfg(all(feature = "std", feature = "zstd"))]
    fn check_block_layout_entry(
        recorded_map: &crate::table::block_layout::BlockLayoutMap,
        block: &DecodedBlock,
    ) -> crate::Result<bool> {
        const ERR: crate::Error =
            crate::Error::InvalidHeader("block_layout disagrees with the frames' inner blocks");

        let Some(ends) = recorded_map.ends_for(block.handle.offset().0) else {
            return Ok(false);
        };
        if !ends.iter().zip(ends.iter().skip(1)).all(|(a, b)| a < b) {
            return Err(ERR);
        }
        if ends.last() != Some(&block.raw.header.uncompressed_length) {
            return Err(ERR);
        }

        let mut src = std::io::Cursor::new(block.frame.as_ref());
        let mut decoder = structured_zstd::decoding::FrameDecoder::new();
        // The resume window: every inner block decoded so far. zstd
        // back-references reach into it, so it is the decoder's input as much
        // as the compressed bytes are.
        let mut window: Vec<u8> = Vec::new();
        let mut resume: Option<structured_zstd::decoding::ResumeState> = None;
        let mut compressed_cursor = 0u64;

        for (idx, &end) in ends.iter().enumerate() {
            #[expect(
                clippy::cast_possible_truncation,
                reason = "inner-block index is bounded by ends.len(), well within u32"
            )]
            let end_block = (idx + 1) as u32;
            // `reset` re-parses the frame header from the start; a resume then
            // repositions the source to the inner block it left off at.
            src.set_position(0);
            decoder.reset(&mut src).map_err(|_| ERR)?;
            let pd = if let Some(state) = resume.as_ref() {
                src.set_position(compressed_cursor);
                decoder
                    .decode_blocks_partial(
                        &mut src,
                        state.block_index(),
                        end_block,
                        Some(structured_zstd::decoding::ResumeInput {
                            window_prime: &window,
                            state,
                        }),
                        true,
                    )
                    .map_err(|_| ERR)?
            } else {
                decoder
                    .decode_blocks_partial(&mut src, 0, end_block, None, true)
                    .map_err(|_| ERR)?
            };
            if pd.stopped_at.is_some() || pd.start_block + pd.blocks_decoded != end_block {
                return Err(ERR);
            }
            // A fresh decode emits `[0, end_block)`; a resume emits only the
            // new tail, contiguous with what the window already holds — so the
            // window is reset for the former and appended to for the latter,
            // and the cursor advances rather than restarting.
            if resume.is_some() {
                compressed_cursor += decoder.bytes_read_from_source();
            } else {
                compressed_cursor = decoder.bytes_read_from_source();
                window.clear();
            }
            window.extend_from_slice(&pd.data);
            if window.len() != end as usize {
                return Err(ERR);
            }
            // The final recorded end must exhaust the frame.
            if idx + 1 == ends.len() && !pd.frame_finished {
                return Err(ERR);
            }
            resume = pd.resume_state;
        }
        Ok(true)
    }

    #[cfg(feature = "std")]
    fn check_block_zone_entry(
        recorded_map: &crate::table::zone_map::ZoneMap,
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        let Some(recorded) = recorded_map.columns_for(block.handle.offset().0) else {
            return Err(crate::Error::InvalidHeader(
                "zone_map is missing a data block's entry",
            ));
        };
        #[cfg(feature = "columnar")]
        if let Some(batch) = &block.batch {
            if batch.row_count == 0 {
                return Err(crate::Error::InvalidHeader(
                    "columnar data block decodes to zero rows",
                ));
            }
            if recorded != batch.zone_stats().as_slice() {
                return Err(crate::Error::InvalidHeader(
                    "zone_map disagrees with the columnar block's per-column statistics",
                ));
            }
            return Ok(());
        }
        Self::verify_row_block_zone_entry(recorded, block)
    }

    /// Cross-checks a ROW data block's recorded zone-map entry: it must be
    /// exactly one synthetic whole-block column (`column_id == 0`, zero type /
    /// codec / null fields) whose `min` / `max` / `row_count` equal the block's
    /// decoded key range and row count.
    ///
    /// Authenticates the column's IDENTITY, not just its key bounds. A
    /// re-stamped map that keeps the checked min / max / `row_count` but changes
    /// the id to a consumer value-column id would let
    /// [`ColumnRangePredicate::can_skip_block`](crate::table::columnar_predicate::ColumnRangePredicate::can_skip_block)
    /// read those key bounds as value-column statistics and skip blocks holding
    /// matching rows. Split out of [`Self::check_block_zone_entry`] so the
    /// columnar path can authenticate its per-column entry instead.
    #[cfg(feature = "std")]
    fn verify_row_block_zone_entry(
        recorded: &[crate::table::zone_map::ColumnStats],
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        let [col] = recorded else {
            return Err(crate::Error::InvalidHeader(
                "zone_map block does not carry exactly one synthetic column",
            ));
        };
        if col.column_id != 0 || col.type_tag != 0 || col.codec_id != 0 || col.null_count != 0 {
            return Err(crate::Error::InvalidHeader(
                "zone_map synthetic column identity disagrees with the \
                 writer's whole-block column (id / type / codec / null)",
            ));
        }
        let (Some(first), Some(last)) = (block.entries.first(), block.entries.last()) else {
            return Err(crate::Error::InvalidHeader(
                "row data block decodes to zero entries",
            ));
        };
        if col.min != first.key.user_key.as_ref()
            || col.max != last.key.user_key.as_ref()
            || col.row_count as usize != block.entries.len()
        {
            return Err(crate::Error::InvalidHeader(
                "zone_map disagrees with the block's decoded key range or row count",
            ));
        }
        Ok(())
    }

    /// The sidecar write [`Self::write_restrict_sidecar`] makes, for
    /// [`crate::restrict_bound::write_many`] to publish with the other tables a
    /// slice restricts, under the same ordering.
    #[cfg(feature = "std")]
    pub(crate) fn restrict_sidecar_write<'a>(
        &'a self,
        bound: &'a [u8],
    ) -> crate::restrict_bound::SidecarWrite<'a> {
        crate::restrict_bound::SidecarWrite {
            fs: &*self.fs,
            table_path: &self.path,
            encryption: self.encryption.as_deref(),
            table_id: self.metadata.id,
            bound,
        }
    }

    /// Publishes this table's tight-space restriction lower bound to its
    /// `.restrict-bound` sidecar, so manifest repair recovers the exact bound
    /// WITHOUT the SST itself being mutated (which would invalidate the whole-file
    /// checksum the manifest still holds for it). MUST be called STRICTLY AFTER the
    /// slice's version install commits and BEFORE the prefix is hole-punched: the
    /// post-commit ordering makes a sidecar on disk always denote a committed
    /// restriction (so repair honors it without a commit protocol), and writing it
    /// before the punch gives every punched input a recoverable exact bound. The
    /// atomic `temp + rename` write leaves the sidecar fully present or absent
    /// across a crash, beside an untouched SST.
    ///
    /// # Errors
    ///
    /// Propagates encryption / filesystem failures from the atomic sidecar write.
    #[cfg(feature = "std")]
    pub(crate) fn write_restrict_sidecar(
        &self,
        bound: &[u8],
        sync_mode: crate::fs::SyncMode,
    ) -> crate::Result<()> {
        crate::restrict_bound::write(
            &*self.fs,
            &self.path,
            self.encryption.as_deref(),
            self.metadata.id,
            bound,
            sync_mode,
        )
    }

    /// Reads one data block's RAW on-disk bytes through `file` and reports
    /// whether they are all zero — the signature of a hole-punched (reclaimed)
    /// block. A short all-zero prefix alone is NOT proof (a corrupt block could
    /// begin with zeros), so a zero opening window falls through to a full-extent
    /// read; a nonzero window proves the block intact without reading the rest
    /// (a real block's header and first entry bytes are never all zero).
    ///
    /// `on_read` is told the length of each read before it is issued, so a
    /// read path can charge the probe to its byte counters.
    ///
    /// # Errors
    ///
    /// Propagates the positioned read failure.
    #[cfg(feature = "std")]
    fn block_is_zeroed_in(
        file: &dyn crate::fs::FsFile,
        block_handle: &BlockHandle,
        on_read: &mut dyn FnMut(u64),
    ) -> crate::Result<bool> {
        const WINDOW: usize = 64;
        let size = block_handle.size() as usize;
        let window = size.min(WINDOW);
        on_read(window as u64);
        let head = crate::file::read_exact(file, block_handle.offset().0, window)?;
        if head.iter().any(|&b| b != 0) {
            return Ok(false);
        }
        if size <= window {
            return Ok(true);
        }
        on_read(size as u64);
        let bytes = crate::file::read_exact(file, block_handle.offset().0, size)?;
        Ok(bytes.iter().all(|&b| b == 0))
    }

    /// Whether ANY of this table's data blocks is hole-punched (reads as zeros)
    /// AND the file carries the physical hole to prove it.
    ///
    /// This is the punch test for the case where the sidecar bound itself could
    /// not be read: a punched data block means the SST genuinely lost data to a
    /// reclaim (bound lost → derive one from the geometry), while a fully intact
    /// data section means an unpunched file. EVERY block is inspected, not just
    /// the first: the punch-on-drop reclaim continues past an individual
    /// `punch_hole` failure, so a partially-punched SST can keep its first block
    /// intact while later prefix blocks are zeroed — a first-block-only probe
    /// would misread that file as unpunched and recover it unrestricted, routing
    /// later reads into the zeroed blocks.
    ///
    /// Zeros alone are NOT the evidence, because corruption that destroys the
    /// leading data block leaves the same read-as-zeros shape a completed punch
    /// does, and reading it as a reclaim would drop that block plus the
    /// sub-bound rows of the first readable one while reporting the table
    /// recovered. A punch physically deallocates, so the zeroed region must
    /// carry an actual hole. The probe is run-local on purpose: consecutive
    /// zeroed blocks coalesce into one run (bounded by readable blocks, so the
    /// hole is attributed to the zeros and not to the file at large — a
    /// file-wide allocation total attributes nothing, and on a filesystem with
    /// transparent compression an ordinary, fully-written file already reports
    /// fewer physical bytes than its length), and the run is asked whether it
    /// CONTAINS a hole rather than whether it wholly IS one: the reclaim
    /// punches at unaligned extents (the prefix ends mid-page, and a block
    /// edge between two calls need not fall on a page of this filesystem), and the
    /// filesystem deallocates only the wholly-contained pages while
    /// zero-filling the edges, so a whole-extent probe would reject genuine
    /// punches.
    ///
    /// A backend that cannot answer the hole probe (`None`) leaves the punch
    /// UNPROVEN, which is a distinct verdict from "unpunched": on a mount
    /// that CAN punch, zeroed runs the probe cannot attribute are
    /// indistinguishable from a lost-sidecar reclaim, and reading them as
    /// "no punch" would publish the table unrestricted — resurrecting the
    /// boundary block's rows below the committed restriction. On a mount
    /// that cannot punch at all, zeros were never a reclaim and stay
    /// classified as damage.
    ///
    /// # Errors
    ///
    /// Propagates the open, block-index, positioned-read or hole-probe failure.
    #[cfg(feature = "std")]
    pub(crate) fn punch_geometry(&self) -> crate::Result<PunchGeometry> {
        let file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        // [start, end) of the current run of consecutive zeroed blocks.
        let mut run: Option<(u64, u64)> = None;
        let mut unattributed = false;
        let mut punched = false;
        let mut probe = |start: u64, end: u64| -> crate::Result<bool> {
            let answer = self
                .fs
                .extent_contains_hole(&self.path, start, end - start)?;
            if answer.is_none() {
                unattributed = true;
            }
            Ok(answer == Some(true))
        };
        // The geometry every classifier used to re-derive on its own pass.
        let mut first_readable: Option<(usize, UserKey)> = None;
        let mut after_last_zeroed: Option<usize> = None;
        let mut irregular = false;
        for (i, handle) in self.maintenance_index_walk().enumerate() {
            let handle = handle?;
            let block = *handle.as_ref();
            // A recovery walk over the file's geometry, not a read a caller
            // asked for, so it charges nothing to the read counters.
            if Self::block_is_zeroed_in(&*file, &block, &mut |_| {})? {
                // A readable block BELOW a zeroed one is positive evidence of
                // a punch that failed mid-reclaim.
                if first_readable.is_some() {
                    irregular = true;
                }
                // The greedy (resurrection) anchor only counts blocks that
                // follow the LAST zeroed one, so a zeroed block resets it.
                after_last_zeroed = None;
                let start = block.offset().0;
                let end = start + u64::from(block.size());
                run = Some(match run {
                    Some((run_start, _)) => (run_start, end),
                    None => (start, end),
                });
                continue;
            }
            if first_readable.is_none() {
                first_readable = Some((i, handle.end_key().clone()));
            }
            if after_last_zeroed.is_none() {
                after_last_zeroed = Some(i);
            }
            if let Some((start, end)) = run.take()
                && probe(start, end)?
            {
                punched = true;
            }
        }
        if let Some((start, end)) = run
            && probe(start, end)?
        {
            punched = true;
        }
        let verdict = if punched {
            PunchProbe::Punched
        } else if unattributed && self.fs.capabilities(&self.path).punch_hole {
            PunchProbe::Unproven
        } else {
            PunchProbe::Unpunched
        };
        Ok(PunchGeometry {
            verdict,
            first_readable,
            after_last_zeroed,
            irregular,
        })
    }

    /// The conservative restriction bound derived from the PHYSICAL punch alone,
    /// for a punched SST whose exact `.restrict-bound` sidecar is not trustworthy
    /// (lost / corrupt / unbacked) and whose manifest restriction is also gone.
    ///
    /// Walks the data blocks in key order and classifies the punch geometry.
    ///
    /// A CLEAN zeroed prefix (every zeroed block precedes every readable one,
    /// starting at the first data block — the pattern a fully successful
    /// punch-on-drop reclaim leaves) yields
    /// [`DerivedRestriction::Bound`]: the END key of the first readable block.
    /// Restricting to that key drops the punched prefix AND the first readable
    /// block, which may STRADDLE the true (mid-block) bound: since the end key
    /// is that block's maximum, it is at or above the true bound, so every
    /// served key is live and NO superseded key is resurrected. The cost is at
    /// most that one block's live suffix, which is exactly the trade the
    /// resurrection flag governs; the resurrection path keeps the whole
    /// readable region instead.
    ///
    /// An IRREGULAR pattern — any readable block BELOW a zeroed one — is
    /// positive evidence that individual `punch_hole` calls failed mid-reclaim
    /// (the reclaim logs and continues per block). Then ANY readable block may
    /// equally be an intact-but-consumed block whose punch also failed, and no
    /// geometry bound can separate consumed from live: anchoring anywhere
    /// either resurrects superseded rows or discards live ones. That is
    /// [`DerivedRestriction::IrregularPunch`] — the caller sets the table
    /// aside (the resurrection path, which accepts re-exposure by contract,
    /// still derives greedily instead). The punch-on-drop reclaim punches
    /// top-down and stops at its first failure precisely so any failure lands
    /// in the DETECTABLE irregular class; the only invisible case is a reclaim
    /// whose very first punch failed (no hole at all — zero evidence), which
    /// reads as an unpunched table here.
    ///
    /// [`DerivedRestriction::NoLiveData`] when EVERY block reads as zeros: no
    /// live data survives the punch, so the caller excludes the table (no
    /// recoverable live data to lose).
    ///
    /// # Errors
    ///
    /// Propagates a block-index or positioned-read failure.
    #[cfg(feature = "std")]
    pub(crate) fn conservative_restriction(geometry: &PunchGeometry) -> DerivedRestriction {
        if geometry.irregular {
            return DerivedRestriction::IrregularPunch;
        }
        match &geometry.first_readable {
            Some((_, end_key)) => DerivedRestriction::Bound(end_key.clone()),
            None => DerivedRestriction::NoLiveData,
        }
    }

    /// The GREEDY counterpart of [`conservative_restriction`](Self::conservative_restriction)
    /// for RESURRECTION mode: returns the FIRST (lowest) key of the first
    /// readable block after the LAST zeroed one, so restricting to it keeps the
    /// WHOLE straddling block — resurrecting its sub-bound keys — while still
    /// excluding every punched (zeroed) block below it. Returning the punched
    /// table UNRESTRICTED instead would route a read to a zeroed,
    /// physically-missing block and fail after a supposedly successful repair;
    /// anchoring before the last zeroed block (a partial punch can leave intact
    /// blocks interleaved with zeroed ones) would do the same. Wholly-empty
    /// readable blocks (e.g. a columnar block fully masked by its delete bitmap)
    /// are skipped. `None` when no readable non-empty block follows the last
    /// zeroed one.
    ///
    /// # Errors
    ///
    /// Propagates a block-index, positioned-read, or block-decode failure.
    #[cfg(feature = "std")]
    pub(crate) fn greedy_restriction_bound(
        &self,
        geometry: &PunchGeometry,
    ) -> crate::Result<Option<UserKey>> {
        let Some(start) = geometry.after_last_zeroed else {
            return Ok(None);
        };
        // Every block from here on is readable (a zeroed one would have reset
        // the anchor), so this only walks forward past WHOLLY EMPTY blocks —
        // e.g. a columnar block fully masked by its delete bitmap, which
        // carries no key to anchor on.
        for (i, handle) in self.maintenance_index_walk().enumerate() {
            let handle = handle?;
            if i < start {
                continue;
            }
            let bh = *handle.as_ref();
            if let Some(db) = self.load_data_block_charged(&bh, ReadCharge::Maintenance)?
                && let Some(first) = db.first_user_key(self.comparator.clone())?
            {
                return Ok(Some(first));
            }
        }
        Ok(None)
    }

    /// Reads the `locator` section FROM DISK and pairs it with the ordinal →
    /// handle map (the writer's `block_id` order is the index order), mirroring
    /// the open path. `None` when the table has no locator.
    ///
    /// Read from the file rather than taken from the open table because a
    /// checksum- and parity-consistent forged locator is accepted by the
    /// out-of-band walk on its block role alone, while `point_read_inner`
    /// trusts its answer and reads the addressed block directly.
    ///
    /// # Errors
    ///
    /// Propagates the section decode and the index walk, and rejects a block
    /// that does not carry the locator role.
    #[cfg(feature = "std")]
    fn read_locator_section(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
    ) -> crate::Result<Option<crate::table::locator::LoadedLocator>> {
        let Some(loc_handle) = regions.locator else {
            return Ok(None);
        };
        let block = Block::from_file(
            file,
            loc_handle,
            crate::table::block::BlockIdentity {
                table_id: self.metadata.id,
                block_type: BlockType::Locator,
                dict_id: 0,
                window_log: 0,
            },
            &self.section_transform(),
        )?;
        if block.header.block_type != BlockType::Locator {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        // Verification, not a caller's read: like every other gate's walk it
        // stays out of the read counters and leaves the block cache alone.
        let blocks: Vec<BlockHandle> = self
            .untraced_index_walk()
            .map(|r| r.map(|kbh| *kbh.as_ref()))
            .collect::<crate::Result<Vec<_>>>()?;
        Ok(Some(crate::table::locator::LoadedLocator::new(
            block.data, blocks,
        )))
    }

    /// Cross-checks the recorded `locator` section against the ACTUAL
    /// key → newest-version-block mapping the decode yields. A locator
    /// redirected from a key's newest-version block to a LATER block holding an
    /// OLDER version returns that stale value without falling back to the
    /// sorted index, so any key whose locator answer points at a different
    /// block than the decode does is corruption.
    ///
    /// `seen` carries ACROSS blocks: the first block holding a user key holds
    /// its newest version (blocks are sorted by key then descending seqno), so
    /// that block is the locator's expected answer and a later block's older
    /// versions must not overwrite the expectation.
    ///
    /// `key_hashes[i]` is the hash of `block.entries[i]`'s key.
    #[cfg(feature = "std")]
    fn check_block_locator(
        &self,
        locator: &crate::table::locator::LoadedLocator,
        seen: &mut crate::HashSet<Vec<u8>>,
        block: &DecodedBlock,
        key_hashes: &[u64],
    ) -> crate::Result<()> {
        {
            let block_handle = block.handle;
            // Columnar blocks carry no in-block slot semantics (rows are
            // reconstructed on load), so there the locator is per-block and
            // only the block-id is checked.
            let row_block = block.row.as_ref();
            debug_assert_eq!(key_hashes.len(), block.entries.len());
            for (entry, &key_hash) in block.entries.iter().zip(key_hashes) {
                let user_key: &[u8] = &entry.key.user_key;
                // Copied only when first seen: the set outlives the block.
                if seen.contains(user_key) {
                    continue;
                }
                seen.insert(user_key.to_vec());
                // The writer OMITS the locator section when it cannot build one
                // and otherwise encodes EVERY unique key, so a present locator
                // that gives NO answer for a decoded key is a forgery — e.g. a
                // delete_bitmap relabeled/re-roled to a locator that resolves
                // nothing. The read path falls back to the sorted index on a
                // miss, but a verifier deciding whether to trust the bytes must
                // treat the unanswered key as corrupt (otherwise the relabel
                // records no degradation and the deleted rows come back live).
                let Some((located, hint)) = locator.locate_block(key_hash)? else {
                    return Err(crate::Error::InvalidHeader(
                        "locator gives no answer for a decoded key it should resolve",
                    ));
                };
                if located.offset() != block_handle.offset() {
                    return Err(crate::Error::InvalidHeader(
                        "locator resolves a key to a block other than its newest-version block",
                    ));
                }
                // A `Restart` / `Entry` slot hint sends `point_read_at_slot`
                // straight to that in-block position: a checksum-clean
                // locator can keep the right block id yet redirect the slot
                // to a later restart interval holding an OLDER version of a
                // multi-version key, and the read returns the stale value
                // without falling back to the sorted index. Probe the hint
                // and require the NEWEST version (the first decoded entry for
                // the key, which is `entry` here since `located` == this
                // block). A `None` hint (per-block precision) has no slot to
                // validate.
                if let (Some((slot, is_entry)), Some(block)) = (hint, row_block) {
                    let found = block.point_read_at_slot(
                        slot,
                        is_entry,
                        user_key,
                        crate::seqno::MAX_SEQNO,
                        &self.comparator,
                    )?;
                    let disagrees = match &found {
                        Some(v) => {
                            v.key.seqno != entry.key.seqno
                                || v.key.value_type != entry.key.value_type
                                || v.value != entry.value
                        }
                        None => true,
                    };
                    if disagrees {
                        return Err(crate::Error::InvalidHeader(
                            "locator slot hint does not resolve a key's newest version",
                        ));
                    }
                }
            }
        }
        Ok(())
    }

    /// Confirms every decoded key is RETRIEVABLE through its own block's
    /// in-block indexes, and that the internal-key sort order holds.
    ///
    /// Judged on the DISK-FRESH bytes the walk decoded. A data block's embedded
    /// HASH INDEX is checksum-clean to the out-of-band walk even when a bucket
    /// was re-stamped to `MARKER_FREE`: the sequential decode gates still see
    /// every entry, but `point_read` trusts the index and returns `None` for
    /// the affected keys. Each block is probed through ITS OWN `point_read` —
    /// the table-level probe this replaces went through the recovery-time
    /// in-memory index and the block cache, so a pristine cached copy masked
    /// the on-disk forge. Filter, locator and TLI misdirection have their own
    /// disk-fresh gates.
    ///
    /// A columnar block has no in-block key index to probe (rows are
    /// reconstructed on load), but the GLOBAL order (user key ASC, then seqno
    /// DESC per key) is still an invariant the read path relies on:
    /// `column_batch_match_entries` binary-searches the key column assuming it
    /// is sorted, so a checksum-restamped block with reordered keys — which
    /// every other columnar check tolerates — would make point reads miss a key
    /// or return a stale version.
    ///
    /// `prev_internal` carries the last decoded internal key ACROSS blocks,
    /// which is what makes the order check global rather than per-block: a
    /// restamped later block must not raise the seqno of a key that also ends
    /// the preceding block, since both would decode and probe cleanly on their
    /// own while a later compaction persisted the stale version.
    #[cfg(feature = "std")]
    fn check_block_reachability(
        &self,
        prev_internal: &mut Option<(UserKey, SeqNo)>,
        block: &DecodedBlock,
    ) -> crate::Result<()> {
        {
            // A block whose keys all resolve through its HASH index never
            // exercises the binary index in the probes below, yet range
            // seeks still trust it — authenticate the pointers directly.
            // A columnar block has no in-block index to probe: rows are
            // reconstructed on load, so only the sort order is enforced there.
            if let Some(data_block) = &block.row {
                data_block.verify_binary_index()?;
            }
            let data_block = block.row.as_ref();
            // A key's versions are adjacent within the block (sorted by key
            // then descending seqno), so the FIRST occurrence is the newest
            // and one probe per distinct key suffices.
            let mut prev_key: Option<UserKey> = None;
            for entry in block.entries.iter().cloned() {
                // Enforce the global sort order on EVERY entry (before the
                // per-key dedup below), tracking the previous entry across block
                // boundaries: the user key must strictly increase, or (for the
                // same user key) the seqno must strictly decrease.
                if let Some((pk, ps)) = &prev_internal {
                    let out_of_order = match self.comparator.compare(&entry.key.user_key, pk) {
                        core::cmp::Ordering::Greater => false,
                        core::cmp::Ordering::Less => true,
                        core::cmp::Ordering::Equal => entry.key.seqno >= *ps,
                    };
                    if out_of_order {
                        // Same invariant, but the two block layouts report it
                        // in their own words: a columnar table has no
                        // point_read to fall back on, so its message names the
                        // layout that produced the disorder.
                        return Err(crate::Error::InvalidHeader(if data_block.is_some() {
                            "data-block entries are out of order (a user key decreased, or an \
                             equal key's seqno did not strictly decrease) across the walk"
                        } else {
                            "columnar entries are out of order (a user key decreased, or an \
                             equal key's seqno did not strictly decrease) across the walk"
                        }));
                    }
                }
                *prev_internal = Some((entry.key.user_key.clone(), entry.key.seqno));

                // Columnar blocks have no in-block index, so the sort-order
                // enforcement above is the whole check for them.
                let Some(data_block) = data_block else {
                    continue;
                };
                if prev_key
                    .as_ref()
                    .is_some_and(|p| crate::comparator::same_user_key(p, &entry.key.user_key))
                {
                    continue;
                }
                // Require the probe to return the NEWEST version, not merely
                // SOME version. A key spanning restart intervals has a
                // conflict-marked hash bucket; re-stamping that bucket to a
                // later interval holding an OLDER version still yields
                // `Some`, so an `is_none` check would pass — yet point reads
                // after reopen would return the stale value. Match the
                // decoded newest entry's seqno, value type, and bytes.
                let found = data_block.point_read(
                    entry.key.user_key.as_ref(),
                    crate::seqno::MAX_SEQNO,
                    &self.comparator,
                )?;
                let disagrees = match &found {
                    Some(v) => {
                        v.key.seqno != entry.key.seqno
                            || v.key.value_type != entry.key.value_type
                            || v.value != entry.value
                    }
                    None => true,
                };
                if disagrees {
                    return Err(crate::Error::InvalidHeader(
                        "a decoded key's point_read does not return its newest version \
                         (an in-block index disagrees with the entries)",
                    ));
                }
                prev_key = Some(entry.key.user_key);
            }
        }
        Ok(())
    }

    /// Whether the salvage-mode open degraded a REBUILDABLE side section
    /// (filter / `filter_tli`, seqno bounds, zone map, locator) because its
    /// block did not decode as the claimed type — see
    /// [`Inner::rebuildable_section_degraded`](crate::table::inner::Inner). Used
    /// by salvage to fail closed on a table whose degraded section may be a
    /// relabeled deletion it would otherwise discard and resurrect.
    ///
    /// `std`-gated because its only consumer is the salvage path (`std`-only).
    #[cfg(feature = "std")]
    pub(crate) fn salvage_degraded_a_rebuildable_section(&self) -> bool {
        self.rebuildable_section_degraded
    }

    /// Reads the `filter` section and everything a probe of it needs, so the
    /// combined reconcile pass builds the state once and then probes it with
    /// the shared decode. `None` for a table without a filter.
    ///
    /// Read from the file rather than taken from the open table because a
    /// checksum- and parity-consistent forged filter is accepted by the
    /// out-of-band walk on its framing and role alone — the walk never probes
    /// it — while `check_bloom` trusts it to SKIP point reads.
    ///
    /// # Errors
    ///
    /// Propagates the section reads, and rejects a present-but-empty filter on
    /// a table that has data blocks.
    #[cfg(feature = "std")]
    fn filter_probe<'a>(
        &'a self,
        file: &'a dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
        prefix_extractor: Option<&alloc::sync::Arc<dyn crate::prefix::PrefixExtractor>>,
    ) -> crate::Result<Option<FilterProbe<'a>>> {
        // Re-read the filter FROM DISK: the open path PINS the filter (or
        // its partition index) in memory at recover time, so an on-disk
        // re-stamp after the open (the very forge this check exists for)
        // would be invisible to `check_bloom`. An unreadable filter is an
        // error here (the caller is deciding whether to trust the bytes),
        // unlike the read path's permissive empty-payload sentinel.
        if regions.filter.is_none() && regions.filter_tli.is_none() {
            return Ok(None);
        }
        let filter_transform = self.section_transform();
        // Partitioned mode: the partition index maps a key to its filter
        // block. Loaded from disk for the same reason as the filter itself.
        let filter_index = if let Some(idx_handle) = regions.filter_tli {
            let block = Block::from_file(
                file,
                idx_handle,
                crate::table::block::BlockIdentity {
                    table_id: self.metadata.id,
                    block_type: BlockType::Index,
                    dict_id: 0,
                    window_log: 0,
                },
                &{
                    let t = crate::table::block::BlockTransform::from_parts(
                        self.metadata.index_block_compression,
                        self.encryption.as_deref(),
                        #[cfg(zstd_any)]
                        None,
                    )?;
                    if let Some(ecc) = self.metadata.ecc_params {
                        t.with_ecc(ecc)
                    } else {
                        t
                    }
                },
            )?;
            if block.header.block_type != BlockType::Index {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    block.header.block_type.into(),
                )));
            }
            let idx = IndexBlock::new(block);
            idx.try_iter(self.comparator.clone())?;
            Some(idx)
        } else {
            None
        };
        let full_filter = if filter_index.is_none() {
            regions
                .filter
                .map(|h| Self::load_filter_block(file, &filter_transform, self.metadata.id, h))
                .transpose()?
        } else {
            None
        };
        // A present full filter whose payload decodes to the empty "no filter"
        // sentinel is a forgery on a table with data blocks: the writer omits
        // the section entirely when filtering is disabled, so it never emits a
        // present-but-empty full filter. Left unrejected, the read-path probe
        // below reports Ok(true) for EVERY key (the permissive empty sentinel),
        // so a delete_bitmap renamed and re-roled to an empty filter passes the
        // whole check, the SST is kept, and reopening resurrects the rows the
        // hidden bitmap deleted.
        if let Some(filter) = &full_filter
            && filter.is_empty()
            && self.untraced_index_walk().next().is_some()
        {
            return Err(crate::Error::InvalidHeader(
                "filter section is present but empty on a table with data blocks",
            ));
        }

        // A restricted view's punched prefix blocks decode to zeros; the walk
        // skips them. Their keys are superseded, so the live filter is only
        // obligated to report the suffix keys present.
        Ok(Some(FilterProbe {
            table: self,
            file,
            transform: filter_transform,
            index: filter_index,
            full: full_filter,
            // Partition blocks are shared by many keys; memoized by file offset
            // so the probe reads each partition once.
            partitions: alloc::collections::BTreeMap::new(),
            prev_key: None,
            // Only the extractor the filter was built under emitted the
            // prefixes it holds: probed under another, a healthy filter
            // reports them absent.
            prefix_extractor: prefix_extractor
                .filter(|extractor| {
                    self.metadata.prefix_extractor.as_deref() == Some(extractor.name().as_bytes())
                })
                .cloned(),
        }))
    }

    /// Every key the block decodes must be reported POSSIBLY PRESENT by the
    /// on-disk filter. A false positive is unprovable (it is the filter's
    /// normal error mode), but a false NEGATIVE on an existing key is
    /// corruption by construction: it silently disappears the key from every
    /// read that consults the filter first.
    #[cfg(feature = "std")]
    fn check_filter_block(
        probe: &mut FilterProbe<'_>,
        block: &DecodedBlock,
        key_hashes: &[u64],
    ) -> crate::Result<()> {
        {
            let table = probe.table;
            debug_assert_eq!(key_hashes.len(), block.entries.len());
            for (entry, &key_hash) in block.entries.iter().zip(key_hashes) {
                // Blocks are sorted by key then descending seqno, so a key's
                // older versions are always adjacent — one probe per key.
                if probe
                    .prev_key
                    .as_deref()
                    .is_some_and(|p| crate::comparator::same_user_key(p, &entry.key.user_key))
                {
                    continue;
                }
                let user_key: &[u8] = &entry.key.user_key;
                let maybe_present = if let Some(idx) = &probe.index {
                    let mut iter = idx.iter(table.comparator.clone());
                    iter.seek(user_key, crate::seqno::MAX_SEQNO);
                    let Some(part_handle) = iter.next() else {
                        // A key past the last partition is a definite miss on
                        // the read path — a false negative by construction.
                        return Err(crate::Error::InvalidHeader(
                            "filter partition index does not cover an existing key",
                        ));
                    };
                    let part_handle = part_handle.materialize(idx.as_slice()).into_inner();
                    let filter = match probe.partitions.entry(part_handle.offset().0) {
                        alloc::collections::btree_map::Entry::Occupied(e) => e.into_mut(),
                        alloc::collections::btree_map::Entry::Vacant(e) => {
                            e.insert(Self::load_filter_block(
                                probe.file,
                                &probe.transform,
                                table.metadata.id,
                                part_handle,
                            )?)
                        }
                    };
                    // The partition index only addresses partitions the writer
                    // filled with keys, so a partition that decodes to the empty
                    // "no filter" sentinel yet is sought for an existing key is a
                    // forgery (a delete_bitmap relabeled to an empty filter
                    // partition under a re-stamped filter_tli). Left unrejected,
                    // the probe below reports Ok(true) permissively for every
                    // key and the relabel passes as a filter-less table.
                    if filter.is_empty() {
                        return Err(crate::Error::InvalidHeader(
                            "filter partition is present but empty for an existing key",
                        ));
                    }
                    filter.maybe_contains_hash(key_hash)?
                } else if let Some(filter) = &probe.full {
                    filter.maybe_contains_hash(key_hash)?
                } else {
                    true
                };
                if !maybe_present {
                    return Err(crate::Error::InvalidHeader(
                        "filter reports an existing key as definitely absent",
                    ));
                }
                // A full filter also indexes every PREFIX the extractor
                // emits for a key, and `maybe_contains_prefix` trusts it to
                // SKIP whole tables on a prefix scan. A filter rebuilt from
                // complete-key hashes alone (a salvage without the extractor)
                // passes the key probe above yet turns every prefix into a
                // false negative — the table silently vanishes from prefix
                // scans. Probe each emitted prefix hash too. Partitioned
                // filters stay conservative (their prefix probe is
                // deliberately best-effort), so this runs only for a full
                // filter with a configured extractor.
                if let (Some(filter), Some(extractor)) = (&probe.full, &probe.prefix_extractor) {
                    for prefix in extractor.prefixes(user_key) {
                        let prefix_hash = crate::hash::hash64(prefix);
                        if !filter.maybe_contains_hash(prefix_hash)? {
                            return Err(crate::Error::InvalidHeader(
                                "filter reports an existing key's prefix as definitely absent",
                            ));
                        }
                    }
                }
                probe.prev_key = Some(entry.key.user_key.clone());
            }
            Ok(())
        }
    }

    /// Reads one filter block (full or partition) from the already-open file,
    /// rejecting a block that does not carry the filter role.
    #[cfg(feature = "std")]
    fn load_filter_block(
        file: &dyn crate::fs::FsFile,
        transform: &crate::table::block::BlockTransform<'_>,
        table_id: crate::TableId,
        handle: BlockHandle,
    ) -> crate::Result<crate::table::filter::block::FilterBlock> {
        let block = Block::from_file(
            file,
            handle,
            crate::table::block::BlockIdentity {
                table_id,
                block_type: BlockType::Filter,
                dict_id: 0,
                window_log: 0,
            },
            transform,
        )?;
        if block.header.block_type != BlockType::Filter {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        Ok(crate::table::filter::block::FilterBlock::new(block))
    }

    /// Reads the meta (and range-tombstone) sections the bounds check judges
    /// against, and seeds the accumulators the walk fills, so the combined
    /// reconcile pass builds the state once and feeds it the shared decode.
    ///
    /// Read from the file rather than taken from the open table because both
    /// meta mirrors re-stamped CONSISTENTLY (fresh checksums and parity) pass
    /// every byte-level check and the mirror comparison, while run selection
    /// trusts `key#min`/`key#max` to route reads AROUND this table — a narrowed
    /// range silently hides real keys (and the range tombstones that mask older
    /// tables).
    ///
    /// `bitmap_digest_authenticated`: whether the caller has ALREADY
    /// authenticated this file's bytes — bitmap section included — against a
    /// matching manifest digest (the directly attributable heal path: the
    /// pre-heal digest probed equal, so the file differs solely by that
    /// pass's corrections). Only then may a LEGACY table whose bitmap
    /// carries no `descriptor#delete_bitmap_hash` pass; repair has no such
    /// digest and must keep failing closed on it. Carried on the probe for the
    /// delete-bitmap gate in [`Self::finish_meta_bounds`], which exists only on
    /// columnar builds (a positional delete bitmap is a columnar-layout
    /// section).
    ///
    /// # Errors
    ///
    /// Propagates the section reads and rejects a disk-fresh meta that
    /// disagrees with the recovery-time descriptor.
    #[cfg(feature = "std")]
    fn meta_bounds_probe(
        &self,
        file: &dyn crate::fs::FsFile,
        regions: &regions::ParsedRegions,
        bitmap_digest_authenticated: bool,
    ) -> crate::Result<MetaBoundsProbe> {
        // Tail-first with MID fallback, mirroring recovery: the next open
        // trusts the same copy, and a table living off its intact MID mirror
        // (unreadable forged tail) must be judged by THAT copy's bounds.
        let meta = match crate::table::meta::ParsedMeta::load_with_handle(
            file,
            &regions.metadata,
            Some(self.metadata.id),
            self.encryption.as_deref(),
        ) {
            Ok(meta) => meta,
            Err(tail_err) => {
                let Some(mid_handle) = regions.metadata_mid else {
                    return Err(tail_err);
                };
                crate::table::meta::ParsedMeta::load_with_handle(
                    file,
                    &mid_handle,
                    Some(self.metadata.id),
                    self.encryption.as_deref(),
                )?
            }
        };

        // Nothing on the heal path legitimately rewrites the meta sections,
        // so the disk-fresh copy must equal the recovery-time one FIELD FOR
        // FIELD. A single-field comparison is not enough: any descriptor
        // re-stamped consistently in both mirrors passes the mirror walk,
        // and fields no gate can re-derive from the entries stay
        // authoritative-only — `descriptor#kv_checksum` flipped to `None`
        // makes every reader misread footer bytes as the block trailer
        // after reopen, and a back-dated `created_at` lets FIFO compaction
        // drop the live SST as TTL-expired. The recovery-time copy is
        // trustworthy (the blocks decoded under it at open), so any
        // disk-fresh divergence is a post-open re-stamp.
        if meta != self.metadata {
            return Err(crate::Error::InvalidHeader(
                "disk-fresh meta disagrees with the recovery-time copy",
            ));
        }

        // Load the range tombstones UP FRONT: the synthetic sentinel an RT-ONLY
        // table records is derived from them and must be EXCLUDED from the KV
        // seqno bounds below (its seqno is RT-derived and lies outside the
        // recorded KV range), and the same list feeds the key-range coverage
        // check further down.
        let tombstones = if let Some(rt_handle) = regions.range_tombstones {
            let block = Block::from_file(
                file,
                rt_handle,
                crate::table::block::BlockIdentity {
                    table_id: self.metadata.id,
                    block_type: BlockType::RangeTombstone,
                    dict_id: 0,
                    window_log: 0,
                },
                &self.section_transform(),
            )?;
            if block.header.block_type != BlockType::RangeTombstone {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    block.header.block_type.into(),
                )));
            }
            Some(Self::decode_range_tombstones(
                &block,
                self.comparator.as_ref(),
            )?)
        } else {
            None
        };
        // The `(start, seqno)` of the synthetic sentinel entry (a weak tombstone
        // at the (seqno, start)-minimal tombstone), or `None` when the table is
        // not RT-only. Excluded ONCE from the decoded KV seqno bounds below.
        //
        // Only an RT-ONLY table (no real KV items) carries a synthetic sentinel,
        // written SOLELY to give an otherwise KV-empty range-tombstone table one
        // index entry (the writer's `finish`), so its `item_count` is exactly 1.
        // Gate on that — NOT on a seqno comparison against `highest_kv_seqno`: the
        // sentinel exclusion feeds the seqno-bounds check below, and
        // `highest_kv_seqno` is precisely the field that check validates, so using
        // it to identify the sentinel is circular — an attacker who lowers a
        // re-stamped `highest_kv_seqno` below a REAL weak tombstone would make it
        // look synthetic, exclude it, and slip the forged bound past. `item_count`
        // is instead cross-checked against the DECODED entry count below, so a
        // forged `item_count == 1` on a multi-entry table is rejected there; a
        // genuine single-real-KV table whose sole weak tombstone matches the
        // RT-minimal `(key, seqno)` is unreachable (the covering RT would have to
        // start at that sole key and end past it, exceeding the one-key range the
        // coverage check enforces, and an empty point tombstone is rejected at
        // decode), so this never wrongly excludes a real entry.
        let sentinel = tombstones
            .as_deref()
            .filter(|_| meta.item_count == 1)
            .and_then(crate::range_tombstone::RangeTombstone::sentinel)
            .map(|(k, s)| (k.clone(), s));

        // A restricted (tight-space) view's `[0, punch)` prefix blocks are
        // punched to zeros: the index still LISTS them (so counting index
        // entries yields the whole-table block count, which `meta` records),
        // but they no longer DECODE. Count every block toward `data_block_count`
        // without decoding, and aggregate entries / keys / seqnos over the live
        // suffix only. `meta.item_count` describes the whole table, so its
        // exact-equality check relaxes to a subset check for a restricted view.
        let restricted = self.restrict_lower_bound().is_some();
        // `data_block_count` describes the WHOLE table, punched prefix
        // included, so it is counted off the index itself — no decode.
        let mut block_count: u64 = 0;
        for handle in self.untraced_index_walk() {
            handle?;
            block_count = block_count
                .checked_add(1)
                .ok_or(crate::Error::InvalidHeader("meta bounds"))?;
        }
        Ok(MetaBoundsProbe {
            meta,
            tombstones,
            sentinel,
            sentinel_excluded: false,
            restricted,
            block_count,
            bitmap_digest_authenticated,
            count: 0,
            first_key: None,
            last_key: None,
            seqno_lo: None,
            seqno_hi: None,
        })
    }

    /// Accumulates the decoded entry count, key range and seqno range that
    /// [`Self::finish_meta_bounds`] judges the recorded bounds against.
    #[cfg(feature = "std")]
    fn observe_meta_bounds(probe: &mut MetaBoundsProbe, block: &DecodedBlock) -> crate::Result<()> {
        {
            let sentinel = probe.sentinel.clone();
            let count = &mut probe.count;
            let first_key = &mut probe.first_key;
            let last_key = &mut probe.last_key;
            let seqno_lo = &mut probe.seqno_lo;
            let seqno_hi = &mut probe.seqno_hi;
            let sentinel_excluded = &mut probe.sentinel_excluded;
            let entries = &block.entries;
            *count = count
                .checked_add(entries.len() as u64)
                .ok_or(crate::Error::InvalidHeader("meta bounds"))?;
            if first_key.is_none() {
                *first_key = entries.first().map(|e| e.key.user_key.clone());
            }
            if let Some(last) = entries.last() {
                *last_key = Some(last.key.user_key.clone());
            }
            for entry in entries {
                let s = entry.key.seqno;
                // The MINIMUM counts every decoded entry, sentinel included.
                // `seqno#min` is written over range tombstones as well as KV
                // entries, so a genuine RT-only table's sentinel carries a
                // seqno the recorded minimum already covers and cannot trip the
                // check. Excluding it here instead would hand an adversary the
                // whole cross-check: with `key#max` re-stamped to admit an RT
                // that starts at a one-entry table's sole key, the table's only
                // real seqno looks synthetic, drops out, and leaves nothing to
                // contradict a raised `seqno#min`.
                *seqno_lo = Some(seqno_lo.map_or(s, |lo| lo.min(s)));
                // The MAXIMUM must still skip the synthetic sentinel (once):
                // `seqno#kv_max` excludes range tombstones, so an RT-only
                // table's sentinel seqno legitimately sits above it.
                if !*sentinel_excluded
                    && let Some((sentinel_key, sentinel_seqno)) = &sentinel
                    && s == *sentinel_seqno
                    && entry.key.value_type == crate::ValueType::WeakTombstone
                    && entry.key.user_key.as_ref() == sentinel_key.as_ref()
                {
                    *sentinel_excluded = true;
                    continue;
                }
                *seqno_hi = Some(seqno_hi.map_or(s, |hi| hi.max(s)));
            }
            Ok(())
        }
    }

    /// Judges the recorded metadata BOUNDS against everything the walk
    /// accumulated. Checks, against the ON-DISK meta:
    /// - the recorded key range COVERS the decoded first/last data keys and
    ///   every recorded range tombstone's bounds (covers, not equals: the
    ///   writer legitimately widens the range over tombstone-only spans);
    /// - the recorded `item_count` equals the decoded entry count (the
    ///   tombstone sentinel is an on-disk entry counted on both sides);
    /// - the recorded `data_block_count` equals the indexed block count
    ///   ([`Table::scan`] hands it to the compaction scanner, which stops
    ///   after that many blocks — a smaller forge drops the tail);
    /// - the disk-fresh per-KV footer descriptor matches the recovery-time
    ///   one (a re-stamped `None` would misread footer bytes as the trailer
    ///   after reopen);
    /// - for tables WITHOUT a range-tombstone sentinel, the recorded
    ///   `seqno#min` is at or below the decoded minimum and `seqno#kv_max`
    ///   is at or above the decoded maximum (a raised min / lowered max
    ///   hides visible versions from snapshot reads). RT-bearing tables skip
    ///   this: the writer records the KV range EXCLUDING the sentinel's
    ///   synthetic RT-derived seqno, so the decoded range legitimately
    ///   differs — and those tables are already gated by the fail-closed
    ///   deletion-metadata attribution rule.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] when the recorded bounds disagree with
    /// the decoded contents.
    #[cfg(feature = "std")]
    #[cfg_attr(
        not(feature = "columnar"),
        expect(
            unused_variables,
            reason = "the delete-bitmap gate the authentication flag drives is columnar-only"
        )
    )]
    fn finish_meta_bounds(&self, probe: MetaBoundsProbe) -> crate::Result<()> {
        let MetaBoundsProbe {
            meta,
            tombstones,
            restricted,
            block_count,
            bitmap_digest_authenticated,
            count,
            first_key,
            last_key,
            seqno_lo,
            seqno_hi,
            ..
        } = probe;
        if restricted {
            // The live suffix is a subset of the whole table `meta` describes;
            // it must not decode to MORE entries than the recorded whole-table
            // count (that would be a grafted-in forge, not a punched prefix).
            if count > meta.item_count {
                return Err(crate::Error::InvalidHeader(
                    "restricted view decodes to more entries than meta item_count",
                ));
            }
        } else if count != meta.item_count {
            return Err(crate::Error::InvalidHeader(
                "meta item_count disagrees with the decoded entry count",
            ));
        }

        // Seqno bounds route snapshot visibility: `get_for_key_cmp` skips this
        // table when the query snapshot is at or below the recorded minimum,
        // and treats it as fully visible above the recorded maximum. Both
        // meta mirrors re-stamped with `seqno#min` raised (or `seqno#kv_max`
        // lowered) pass every other gate yet silently hide older / newer
        // visible versions after reopen. Cross-check against the decoded seqnos.
        // The synthetic RT sentinel was already excluded above (its RT-derived
        // seqno lies outside the recorded KV range), so this runs for RT-bearing
        // tables too: an RT-ONLY table's sole entry drops out, leaving no bounds
        // to check, while an RT+KV table's real entries are checked. A recorded
        // minimum ABOVE the real minimum, or a recorded KV maximum BELOW the
        // real maximum, is corruption.
        // Checked INDEPENDENTLY: an RT-only table decodes a minimum (its
        // sentinel counts there) but no KV maximum, and pairing the two would
        // skip the minimum check on exactly the table shape an adversary builds
        // to escape it.
        if let Some(lo) = seqno_lo
            && meta.seqnos.0 > lo
        {
            return Err(crate::Error::InvalidHeader(
                "meta seqno#min is above the decoded minimum seqno",
            ));
        }
        if let Some(hi) = seqno_hi
            && meta.highest_kv_seqno < hi
        {
            return Err(crate::Error::InvalidHeader(
                "meta seqno#kv_max is below the decoded maximum seqno",
            ));
        }
        // `Table::scan` hands the recorded count to the compaction scanner,
        // which stops after that many blocks: a count re-stamped SMALLER
        // silently drops every key in the omitted tail from rewrites.
        if block_count != meta.data_block_count {
            return Err(crate::Error::InvalidHeader(
                "meta data_block_count disagrees with the indexed block count",
            ));
        }
        let cmp = &self.comparator;
        let covers = |key: &[u8]| {
            cmp.compare(meta.key_range.min().as_ref(), key) != core::cmp::Ordering::Greater
                && cmp.compare(meta.key_range.max().as_ref(), key) != core::cmp::Ordering::Less
        };
        if let (Some(first), Some(last)) = (&first_key, &last_key)
            && !(covers(first.as_ref()) && covers(last.as_ref()))
        {
            return Err(crate::Error::InvalidHeader(
                "meta key range does not cover the decoded data keys",
            ));
        }

        // The decoded tombstone count must match the recorded
        // `range_tombstone_count`. A re-stamped RT block that decodes to a
        // SUBSET, or a dropped section, passes the coverage check below for its
        // surviving entries while the missing ranges no longer mask lower-level
        // data — reads then resurrect the keys those tombstones deleted. The
        // count lives in the meta block (already cross-checked field-for-field
        // against the recovery-time copy above), so it is the trustworthy side.
        let decoded_rt_count = tombstones.as_ref().map_or(0, alloc::vec::Vec::len) as u64;
        if decoded_rt_count != meta.range_tombstone_count {
            return Err(crate::Error::InvalidHeader(
                "range_tombstones count disagrees with the recorded range_tombstone_count",
            ));
        }

        // The recorded positional-delete count must match the readable
        // delete_bitmap section EXACTLY, in both directions. The section is
        // OPTIONAL (the writer omits it, and records the count as 0, precisely
        // when the bitmap is empty), so its effective length is its decoded
        // length when present and 0 when absent. A re-stamped TOC can break the
        // agreement either way:
        //   - a `> 0` count with the section RENAMED away (or REPLACED by
        //     another valid optional section, e.g. a full filter that passes
        //     every probe) leaves the table reporting no deletion, resurrecting
        //     every positionally-deleted row;
        //   - a `0` count with a live non-empty section GRAFTED on (the
        //     no-delete count is genuine, but a bitmap from another table is
        //     spliced in) makes reads apply that mask and drop live rows.
        // Comparing effective length to the recorded count catches both, like
        // the range-tombstone count check above. The count lives in the meta
        // block (already cross-checked field-for-field against the recovery-time
        // copy above and against the mirror), so it is the trustworthy side.
        // `None` is an older table without the field: nothing to cross-check.
        // Columnar-only: the bitmap is a columnar-layout section.
        #[cfg(feature = "columnar")]
        if let Some(recorded) = meta.delete_bitmap_len {
            let effective = if self.has_delete_bitmap_section() {
                self.delete_bitmap().len()
            } else {
                0
            };
            if effective != recorded {
                return Err(crate::Error::InvalidHeader(
                    "delete_bitmap count disagrees with the recorded \
                     descriptor#delete_bitmap_len (the section was hidden, \
                     replaced, or grafted on)",
                ));
            }
        }
        // Authenticate the delete-bitmap CONTENTS, not just its cardinality: the
        // count check above accepts an equal-cardinality checksum-valid bitmap
        // substituted for the real one, which — during manifest repair, with no
        // original whole-file digest to compare against — would resurrect the
        // originally-deleted rows and drop different live ones. The meta-bound
        // hash of the section's encoded bytes catches any content substitution;
        // the meta block is itself checksum- and mirror-verified, so a forger
        // cannot restamp the hash without failing meta integrity. Re-encoding the
        // decoded bitmap is byte-identical to the on-disk section (the container
        // kind and its contents round-trip verbatim), so it matches the writer's
        // hash.
        //
        // This gate runs ONLY during repair / heal reconciliation, never on an
        // ordinary read (which the manifest's whole-file digest already
        // protects). Those paths have no original digest, so a PRESENT bitmap
        // section MUST carry a content hash to be authenticated here: a table
        // written before this field (`None`) cannot be authenticated, so it fails
        // closed rather than accepting a possibly-substituted equal-cardinality
        // mask. Ordinary reads of such an older table are unaffected.
        #[cfg(feature = "columnar")]
        if self.has_delete_bitmap_section() {
            match meta.delete_bitmap_hash {
                Some(recorded_hash) => {
                    let actual_hash = crate::hash::hash128(&self.delete_bitmap().encode());
                    if actual_hash != recorded_hash {
                        return Err(crate::Error::InvalidHeader(
                            "delete_bitmap contents disagree with the recorded \
                             descriptor#delete_bitmap_hash (an equal-cardinality bitmap \
                             was substituted)",
                        ));
                    }
                }
                None if !bitmap_digest_authenticated => {
                    return Err(crate::Error::InvalidHeader(
                        "delete_bitmap section present without a \
                         descriptor#delete_bitmap_hash; its contents cannot be \
                         authenticated during repair / heal",
                    ));
                }
                // A LEGACY table (written before the hash existed) on the
                // directly attributable heal path: the pre-heal digest
                // matched the manifest, so the bitmap bytes — untouched by
                // the data-block heal — were just authenticated by that
                // digest. Rejecting here would strip the heal attestation
                // and strand the healed table under a stale digest forever.
                None => {}
            }
        }
        // Range tombstones mask entries in OLDER tables during reads and
        // merges, so a key range narrowed below a tombstone's extent routes
        // reads around this table and resurrects the data it deletes. Reuse the
        // list loaded up front (for the sentinel derivation) rather than
        // re-reading the block.
        if let Some(tombstones) = &tombstones {
            for rt in tombstones {
                if !(covers(rt.start.as_ref()) && covers(rt.end.as_ref())) {
                    return Err(crate::Error::InvalidHeader(
                        "meta key range does not cover a recorded range tombstone",
                    ));
                }
            }
        }
        Ok(())
    }

    /// The SECTION-level half of the block-layout check: the section must not
    /// be present-but-empty on a table that has data blocks.
    ///
    /// The writer emits `block_layout` only when it has a multi-inner-block
    /// frame to record, so an empty map is a forgery — a `delete_bitmap`
    /// renamed and re-roled, which drops the deletion metadata and resurrects
    /// positionally-deleted rows. The per-block cross-check cannot catch that
    /// one: a block absent from the map is skipped, so an empty map trivially
    /// "agrees" with every block.
    ///
    /// This runs on EVERY build, including non-zstd, because the forgery does
    /// not need zstd to do its damage. The per-frame half — where each recorded
    /// boundary is matched against the frame's actual inner blocks — lives in
    /// [`Self::verify_reconcile_gates`], which already holds the decoded frame
    /// and needs no second read to do it.
    ///
    /// # Errors
    ///
    /// [`crate::Error::InvalidHeader`] on the empty-map forgery,
    /// [`crate::Error::InvalidTag`] when the section does not carry the
    /// block-layout role, plus any I/O / decode error from the section read.
    #[cfg(feature = "std")]
    pub(crate) fn verify_block_layout(&self) -> crate::Result<()> {
        // The section-presence + EMPTINESS check runs on EVERY build (including
        // non-zstd, where the per-frame cross-check below is compiled out): a
        // relabeled delete_bitmap→empty block_layout drops the deletion metadata
        // regardless of zstd, so the forgery must be caught either way.
        //
        // Re-read the section FROM DISK: the in-memory map was loaded at recover
        // time, so an on-disk re-stamp after the open (the very forge this check
        // exists for) would be invisible to it.
        let mut file = self.fs.open(&self.path, &FsOpenOptions::new().read(true))?;
        let trailer = crate::sfa::Reader::from_reader(&mut file)?;
        let regions = regions::ParsedRegions::parse_from_toc(trailer.toc())?;
        let Some(bl_handle) = regions.block_layout else {
            return Ok(());
        };
        // Decode the map with an encryption-aware transform: on an encrypted
        // table the section is AEAD-sealed, so both the emptiness check below
        // AND catching a relabeled delete_bitmap (its AAD binds the block type,
        // so decoding it as a BlockLayout fails the AEAD open) need the provider.
        let map = {
            let block = Block::from_file(
                &*file,
                bl_handle,
                crate::table::block::BlockIdentity {
                    table_id: self.metadata.id,
                    block_type: BlockType::BlockLayout,
                    dict_id: 0,
                    window_log: 0,
                },
                &self.section_transform(),
            )?;
            if block.header.block_type != BlockType::BlockLayout {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    block.header.block_type.into(),
                )));
            }
            crate::table::block_layout::BlockLayoutMap::decode(&block.data)?
        };
        // The writer emits the block_layout section ONLY when it has at least
        // one multi-inner-block frame to record, so a PRESENT-but-empty map on a
        // table with data blocks is a forgery — e.g. a delete_bitmap renamed and
        // re-roled to an empty block_layout, which drops the deletion metadata
        // and resurrects positionally-deleted rows. (The per-block loop below
        // cannot catch it: a block absent from the map is skipped, so an empty
        // map trivially "agrees" with every block.)
        if map.is_empty() {
            if self.untraced_index_walk().next().is_some() {
                return Err(crate::Error::InvalidHeader(
                    "block_layout section is present but empty on a table with data blocks",
                ));
            }
            return Ok(());
        }
        Ok(())
    }

    /// Walks the LIVE data blocks once, decoding each DISK-FRESH, and hands
    /// every gate the same [`DecodedBlock`].
    ///
    /// A restricted view's punched prefix blocks are dead (they read as zeros),
    /// so the walk starts at the punch offset — every gate skipped them
    /// individually before, with the same reasoning.
    ///
    /// # Errors
    ///
    /// Propagates the index walk, the punch-offset lookup, the block read and
    /// the decode, plus whatever `check` returns.
    #[cfg_attr(
        not(feature = "std"),
        expect(
            dead_code,
            reason = "gate-only walk; the verify/scrub consumers are std-gated"
        )
    )]
    fn for_each_live_block<F>(&self, mut check: F) -> crate::Result<()>
    where
        F: FnMut(&DecodedBlock) -> crate::Result<()>,
    {
        use crate::table::block::ParsedItem as _;

        let punch = self.punch_offset()?;
        for handle in self.untraced_index_walk() {
            let handle = *handle?.as_ref();
            if handle.offset().0 < punch {
                continue;
            }

            // Keep the block as it came off disk (`raw`) and derive the views
            // from a CLONE: `from_loaded` strips the per-KV footer, and the
            // digest gate needs the footered bytes. A `Block` clone is a
            // header copy plus a refcount bump on the payload, not a copy.
            #[cfg(feature = "columnar")]
            let (raw, frame, row, batch) = if self.metadata.columnar {
                let (raw, frame, batch) = self.load_row_group_from_disk(&handle)?;
                (raw, frame, None, Some(batch))
            } else {
                let (raw, frame) = self.load_block_from_disk(&handle, BlockType::Data)?;
                let row =
                    DataBlock::from_loaded(raw.clone(), self.metadata.kv_checksum_algo.is_some())?;
                (raw, frame, Some(row), None)
            };
            #[cfg(not(feature = "columnar"))]
            let (raw, frame, row) = {
                let (raw, frame) = self.load_block_from_disk(&handle, BlockType::Data)?;
                let row =
                    DataBlock::from_loaded(raw.clone(), self.metadata.kv_checksum_algo.is_some())?;
                (raw, frame, Some(row))
            };

            // Materialize the entries from whichever view this table has. The
            // columnar reconstruction is the same one `decode_block_entries`
            // performs, so a malformed batch still fails here rather than
            // truncating silently.
            let entries: Vec<InternalValue> = match &row {
                Some(block) => block
                    .try_iter(self.comparator.clone())?
                    .map(|p| p.materialize(block.as_slice()))
                    .collect(),
                #[cfg(feature = "columnar")]
                None => match &batch {
                    Some(batch) => crate::table::columnar::column_batch_to_entries(batch)?,
                    None => Vec::new(),
                },
                #[cfg(not(feature = "columnar"))]
                None => Vec::new(),
            };

            check(&DecodedBlock {
                handle,
                raw,
                frame,
                row,
                #[cfg(feature = "columnar")]
                batch,
                entries,
            })?;
        }
        Ok(())
    }

    /// Loads a columnar row group STRAIGHT FROM THE FILE, bypassing the block
    /// cache, for the reconcile gates — the reason [`Self::load_block_from_disk`]
    /// exists, applied to every block of the group.
    ///
    /// Returns the directory block and its frame (the entry's first block,
    /// which is what the gates that look at a raw block get for a columnar
    /// table: pages carry no per-KV footer and no inner-frame layout, so those
    /// gates have nothing further to check in a group) together with the
    /// decoded batch.
    #[cfg(all(feature = "columnar", feature = "std"))]
    fn load_row_group_from_disk(
        &self,
        group: &BlockHandle,
    ) -> crate::Result<(Block, crate::Slice, crate::table::columnar::ColumnBatch)> {
        let mut blocks = self.data_unit_blocks(group)?.into_iter();
        let Some((directory_handle, directory_role)) = blocks.next() else {
            return Err(crate::Error::InvalidHeader(
                "columnar: row group has no directory",
            ));
        };
        let (directory, frame) = self.load_block_from_disk(&directory_handle, directory_role)?;
        let directory_decoded = crate::table::column_page::PageDirectory::decode(&directory.data)?;
        let mut pages = alloc::vec::Vec::with_capacity(directory_decoded.entries().len());
        // The zone blocks in the order they lie: the head one, then the rest.
        let zone_blocks: alloc::vec::Vec<crate::table::column_page::ZoneBlock> = directory_decoded
            .head_zone_block()
            .into_iter()
            .chain(directory_decoded.zone_blocks().iter().copied())
            .collect();
        let mut block_zones = alloc::vec::Vec::with_capacity(zone_blocks.len());
        let mut listed = zone_blocks.iter();
        for (handle, role) in blocks {
            let block = self.load_block_from_disk(&handle, role)?.0;
            if role == BlockType::ColumnZones {
                let column_id =
                    listed
                        .next()
                        .map(|z| z.column_id)
                        .ok_or(crate::Error::InvalidHeader(
                            "columnar: a zone block the directory does not list",
                        ))?;
                block_zones.push(directory_decoded.decode_zone_block(column_id, &block.data)?);
            } else {
                pages.push(block);
            }
        }
        let group = crate::table::row_group::RowGroupBlocks::whole(
            alloc::sync::Arc::new(directory_decoded),
            pages,
        );
        // The gates are verification, which the counters leave out; they
        // re-derive per-group statistics, so the row pages are joined.
        let batch = group.to_row_pages(&mut 0)?.into_batch()?;
        // The row pages' zones decide which pages a read skips, so they are
        // authenticated like the zone map: re-derived from the decoded rows,
        // every zone block's, in the order the writer lays them out, the key
        // column's as the head block before the pages; a zone block that
        // should not exist, or lies elsewhere, is as wrong as one that is
        // missing. A zone that disagrees would let a read prune a row page
        // holding a match, and nothing on the read path looks at the rows it
        // pruned.
        let (key_zones, other_zones) = batch.group_zones(group.directory.row_pages())?;
        let key_column = key_zones.columns().first().copied();
        let expected: alloc::vec::Vec<_> = key_column
            .map(|_| key_zones)
            .into_iter()
            .chain(
                other_zones
                    .columns()
                    .iter()
                    .map(|&column_id| other_zones.only(|c| c == column_id)),
            )
            .collect();
        let head_column = group.directory.head_zone_block().map(|z| z.column_id);
        if expected != block_zones || head_column != key_column {
            return Err(crate::Error::InvalidHeader(
                "columnar: row page statistics disagree with the group's rows",
            ));
        }
        Ok((directory, frame, batch))
    }

    /// Decodes ONE data block's entries (row or columnar) into
    /// [`InternalValue`]s, disk-fresh ([`Self::load_block_from_disk`]).
    ///
    /// Test-only: the cross-check gates consume the walk's shared decode
    /// ([`Self::for_each_live_block`]) rather than decoding a block apiece.
    /// What is left is fixtures that need one named block's contents to build
    /// a forgery from.
    #[cfg(all(feature = "std", test))]
    fn decode_block_entries(
        &self,
        block_handle: &BlockHandle,
    ) -> crate::Result<Vec<InternalValue>> {
        use crate::table::block::ParsedItem as _;
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            let (_, _, batch) = self.load_row_group_from_disk(block_handle)?;
            return crate::table::columnar::column_batch_to_entries(&batch);
        }
        let (block, _frame) = self.load_block_from_disk(block_handle, BlockType::Data)?;
        let data_block = DataBlock::from_loaded(block, self.metadata.kv_checksum_algo.is_some())?;
        Ok(data_block
            .try_iter(self.comparator.clone())?
            .map(|p| p.materialize(data_block.as_slice()))
            .collect())
    }

    /// Loads the filter block (if any) and checks the bloom filter, counting
    /// nothing.
    ///
    /// Returns `Ok(BloomResult::Skip)` if the bloom filter says the key is definitely absent,
    /// `Ok(BloomResult::Proceed { has_filter })` otherwise. A filter block read
    /// from the file is read through `fd`, the lookup's.
    fn judge_bloom(&self, key: &[u8], key_hash: u64, fd: &LookupFd) -> crate::Result<BloomResult> {
        debug_assert_eq!(
            key_hash,
            crate::hash::hash64(key),
            "key_hash must match the hash of the provided key"
        );

        match self.filter_source(key) {
            FilterSource::None => Self::answer_bloom(None, key_hash),
            FilterSource::Pinned(block) => Self::answer_bloom(Some(block), key_hash),
            FilterSource::Block(handle) => {
                let block = self.load_block(
                    &handle,
                    BlockType::Filter,
                    CompressionType::None,
                    #[cfg(zstd_any)]
                    None,
                    fd,
                )?;
                Self::answer_bloom(Some(&FilterBlock::new(block)), key_hash)
            }
            FilterSource::PastPartitions => Ok(BloomResult::PastPartitions),
        }
    }

    /// [`Self::judge_bloom`], counted at once in the global metrics, as a
    /// point read counts its filter answers.
    fn check_bloom(&self, key: &[u8], key_hash: u64, fd: &LookupFd) -> crate::Result<BloomResult> {
        let answer = self.judge_bloom(key, key_hash, fd)?;
        #[cfg(feature = "metrics")]
        if answer.should_skip() {
            use core::sync::atomic::Ordering::Relaxed;
            self.metrics.filter_queries.fetch_add(1, Relaxed);
            self.metrics.io_skipped_by_filter.fetch_add(1, Relaxed);
        }
        Ok(answer)
    }

    /// Adds `answer` to `tally`, counted when the plan holding it is.
    fn tally_bloom(tally: &mut crate::table::probe_stats::PlanCounts, answer: &BloomResult) {
        tally.probes += answer.probe_counts();
        if answer.should_skip() {
            tally.filter_queries += 1;
            tally.filter_skips += 1;
        }
    }

    /// Where the filter `key` is checked against lives, found without a read:
    /// the pinned filter, the block of the filter or of the filter partition
    /// holding the key, or no filter at all.
    pub(crate) fn filter_source(&self, key: &[u8]) -> FilterSource<'_> {
        if let Some(block) = &self.pinned_filter_block {
            FilterSource::Pinned(block)
        } else if let Some(filter_idx) = &self.pinned_filter_index {
            let mut iter = filter_idx.iter(self.comparator.clone());
            // Filter partitions are written with seqno=0, making the seqno
            // parameter irrelevant to partition selection. Use MAX_SEQNO
            // consistently to match the index-block seek in Table::range().
            iter.seek(key, crate::seqno::MAX_SEQNO);
            match iter.next() {
                Some(handle) => {
                    FilterSource::Block(handle.materialize(filter_idx.as_slice()).into_inner())
                }
                // Key sorts past the last filter partition: a definite miss.
                None => FilterSource::PastPartitions,
            }
        } else if self.regions.filter_tli.is_some() {
            // Partitioned, yet its index is not loaded: a live open always
            // loads it, so this is a salvage open that found it unreadable.
            // Without the index no partition can be found, so no key is ruled
            // out.
            FilterSource::None
        } else if let Some(handle) = &self.regions.filter {
            FilterSource::Block(*handle)
        } else {
            FilterSource::None
        }
    }

    /// The answer of `filter` (none: nothing rules the key out) for a key
    /// hashing to `key_hash`, counting nothing.
    fn answer_bloom(filter: Option<&FilterBlock>, key_hash: u64) -> crate::Result<BloomResult> {
        let Some(filter) = filter else {
            return Ok(BloomResult::Proceed { has_filter: false });
        };
        if !filter.maybe_contains_hash(key_hash)? {
            return Ok(BloomResult::Skip);
        }
        Ok(BloomResult::Proceed { has_filter: true })
    }

    /// Records a data-consulting point read for per-segment tiering / placement
    /// stats: a single `Relaxed` counter bump plus, on `std`, the access time.
    /// Called only after the seqno-range + bloom gates pass, so bloom misses do
    /// not inflate the count. Raw counter; the consumer derives a rate / EMA from
    /// successive polls.
    fn record_access(&self) {
        self.record_accesses(1);
    }

    /// Records `reads` data-consulting point reads at once, as
    /// [`Self::record_access`] records one: what a batched read let through
    /// its gates.
    pub(crate) fn record_accesses(&self, reads: u64) {
        self.read_count
            .fetch_add(reads, core::sync::atomic::Ordering::Relaxed);
        #[cfg(feature = "std")]
        self.last_access_secs.store(
            crate::time::unix_timestamp().as_secs(),
            core::sync::atomic::Ordering::Relaxed,
        );
    }

    pub fn get(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
    ) -> crate::Result<Option<InternalValue>> {
        // Tight-space restriction: this version sees the table only at keys
        // `>= bound` (the prefix below it is punched out and superseded by a
        // merged output table). Keys below `bound` must miss here so the read
        // falls through to that output; the punched blocks are never touched.
        if self.is_below_restriction(key) {
            return Ok(None);
        }

        let global_seqno = self.global_seqno();
        // A query snapshot below this table's base seqno predates the table, so
        // none of its rows are visible. `checked_sub` yields `None` there (where a
        // saturating sub would silently clamp to 0); the seqno-range gate below
        // then handles the in-range case.
        let Some(seqno) = seqno.checked_sub(global_seqno) else {
            return Ok(None);
        };

        if self.metadata.seqnos.0 >= seqno {
            return Ok(None);
        }

        // The filter, index and data blocks this lookup reads share the file.
        let fd = LookupFd::default();
        let bloom = self.check_bloom(key, key_hash, &fd)?;
        self.count_probe(&bloom);
        if bloom.should_skip() {
            return Ok(None);
        }

        // Access accounting after the seqno-range + bloom gates, so a segment
        // that excludes the key (seqno range) or rejects it (bloom miss) is not
        // counted as serving it.
        self.record_access();

        // Row-cache fast path: a prior latest-version read cached this key's
        // resolved value for this (immutable) SST, so we can skip the index walk
        // + data-block decode. The cached value is in table-local seqno space
        // (same as `point_read`). Use it only when the cached newest version is
        // visible at the query snapshot; otherwise fall through, because an older
        // version may apply at this snapshot.
        if let Some(mut iv) = self.cache.get_row(self.global_id(), key_hash, key) {
            // Snapshot reads are exclusive: a version is visible iff its seqno is
            // strictly less than the query seqno. Only serve the cached newest
            // version when it is visible; otherwise fall through (an older
            // version may apply at this snapshot).
            if iv.key.seqno < seqno {
                iv.key.seqno = apply_global_seqno(iv.key.seqno, global_seqno);
                return Ok(Some(iv));
            }
        }

        let item = self.point_read(key, seqno, key_hash, &fd)?;

        // Populate the row cache only when this read could see the SST's newest
        // version (`seqno > max`, exclusive), so the resolved value is the SST's
        // newest version for this key — which keeps the seqno-visibility check
        // above correct for later snapshot reads. SSTs are immutable, so the
        // entry stays valid until the SST is compacted away.
        if seqno > self.metadata.seqnos.1
            && let Some(iv) = &item
        {
            let detached = self.cache.insert_row(
                self.global_id(),
                key_hash,
                &iv.key.user_key,
                iv.key.seqno,
                iv.key.value_type,
                &iv.value,
            );
            #[cfg(feature = "metrics")]
            self.metrics.record_gather(detached);
            #[cfg(not(feature = "metrics"))]
            let _ = detached;
        }

        // Translate table-local seqno back to global coordinate so callers
        // can compare across tables/memtables (L0 best-selection, RT suppression).
        let item = item.map(|mut iv| {
            iv.key.seqno = apply_global_seqno(iv.key.seqno, global_seqno);
            iv
        });

        #[cfg(feature = "metrics")]
        {
            use core::sync::atomic::Ordering::Relaxed;
            // NOTE: `check_bloom()` accounts for lookups rejected by the filter
            // (skip I/O entirely). This path accounts for negative point lookups
            // that still reached storage even though a filter was present, so
            // `filter_queries` remains interpretable alongside `filter_efficiency()`.
            // https://github.com/fjall-rs/lsm-tree/issues/246
            if item.is_none() && bloom.has_filter() {
                self.metrics.filter_queries.fetch_add(1, Relaxed);
            }
        }
        if item.is_none() && bloom.has_filter() {
            self.count_false_positive(seqno);
        }

        Ok(item)
    }

    /// Value-only point read: `(value_type, seqno, value)` without
    /// reconstructing the entry key. Used by the value-returning `get` path,
    /// which never reads the matched key (the caller has the needle), so the
    /// delta-key fusion in [`DataBlock::point_read`] is skipped. The value is a
    /// zero-copy slice of the cached block.
    pub(crate) fn get_value(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
    ) -> crate::Result<Option<(crate::ValueType, SeqNo, crate::Slice)>> {
        // Tight-space restriction (mirrors `Table::get`): a key below the bound
        // misses so the read falls through to the superseding output.
        if self.is_below_restriction(key) {
            return Ok(None);
        }

        let global_seqno = self.global_seqno();
        // A query snapshot below this table's base seqno predates the table, so
        // none of its rows are visible. `checked_sub` yields `None` there (where a
        // saturating sub would silently clamp to 0); the seqno-range gate below
        // then handles the in-range case.
        let Some(seqno) = seqno.checked_sub(global_seqno) else {
            return Ok(None);
        };

        if self.metadata.seqnos.0 >= seqno {
            return Ok(None);
        }

        // The filter, index and data blocks this lookup reads share the file.
        let fd = LookupFd::default();
        let bloom = self.check_bloom(key, key_hash, &fd)?;
        self.count_probe(&bloom);
        if bloom.should_skip() {
            return Ok(None);
        }

        // Access accounting after the seqno-range + bloom gates (mirrors `Table::get`).
        self.record_access();

        // Row-cache fast path (mirrors `Table::get`): serve the value tuple from
        // a prior cached point-read result, skipping the index walk + block
        // decode, when the cached newest version is visible at this snapshot.
        if let Some(iv) = self.cache.get_row(self.global_id(), key_hash, key) {
            // Exclusive snapshot visibility (see `Table::get`): serve only when
            // the cached newest version is strictly older than the query seqno.
            if iv.key.seqno < seqno {
                let s = apply_global_seqno(iv.key.seqno, global_seqno);
                return Ok(Some((iv.key.value_type, s, iv.value)));
            }
        }

        let item = self.point_read_value(key, seqno, key_hash, &fd)?;

        // Populate only when this read could see the SST's newest version
        // (`seqno > max`, exclusive), mirroring `Table::get`. The value path does
        // not reconstruct the matched key, so the row is keyed by the query key
        // (the needle) + the resolved `(value_type, seqno, value)`.
        if seqno > self.metadata.seqnos.1
            && let Some((vt, s, v)) = &item
        {
            let detached = self
                .cache
                .insert_row(self.global_id(), key_hash, key, *s, *vt, v);
            #[cfg(feature = "metrics")]
            self.metrics.record_gather(detached);
            #[cfg(not(feature = "metrics"))]
            let _ = detached;
        }

        // Translate table-local seqno back to the global coordinate, mirroring
        // `Table::get`.
        let item = item.map(|(vt, s, v)| (vt, apply_global_seqno(s, global_seqno), v));

        #[cfg(feature = "metrics")]
        {
            use core::sync::atomic::Ordering::Relaxed;
            if item.is_none() && bloom.has_filter() {
                self.metrics.filter_queries.fetch_add(1, Relaxed);
            }
        }
        if item.is_none() && bloom.has_filter() {
            self.count_false_positive(seqno);
        }

        Ok(item)
    }

    /// Value-only block-index walk: companion to [`Table::point_read_inner`]
    /// that reads each candidate data block with
    /// [`DataBlock::point_read_value`] (no key fusion, no retained block).
    fn point_read_value(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
        fd: &LookupFd,
    ) -> crate::Result<Option<(crate::ValueType, SeqNo, crate::Slice)>> {
        // Fast path: retrieval-ribbon locator (see `point_read_inner` for the
        // MVCC-correctness argument). A located-block miss falls through to the
        // index walk below.
        if let Some((handle, hint)) = self.locator_block(key_hash)?
            && let Some(data_block) = self.load_point_block(&handle, key, fd)?
        {
            // A columnar block is narrowed to this key's rows by load_point_block,
            // so the full-block slot hint does not apply.
            let is_columnar = cfg!(feature = "columnar") && self.metadata.columnar;
            let found = match hint {
                Some((slot, is_entry)) if !is_columnar => data_block.point_read_value_at_slot(
                    slot,
                    is_entry,
                    key,
                    seqno,
                    &self.comparator,
                )?,
                _ => data_block.point_read_value_hashed(
                    key,
                    Some(key_hash),
                    seqno,
                    &self.comparator,
                )?,
            };
            if let Some(found) = found {
                return Ok(Some(found));
            }
        }

        let Some(mut iter) = self.block_index.point_read_reader(key, seqno) else {
            return Ok(None);
        };

        while let Some(block_handle) = iter.next_with(fd) {
            let block_handle = block_handle?;

            // A columnar block carrying no row for this key (absent / wholly
            // deleted) returns None here; still honor the end-key cutoff before
            // skipping, so an absent key below this block's end key stops the
            // scan instead of probing every later candidate block.
            let Some(data_block) = self.load_point_block(block_handle.as_ref(), key, fd)? else {
                if self.comparator.compare(block_handle.end_key(), key)
                    == core::cmp::Ordering::Greater
                {
                    return Ok(None);
                }
                continue;
            };

            if let Some(found) =
                data_block.point_read_value_hashed(key, Some(key_hash), seqno, &self.comparator)?
            {
                return Ok(Some(found));
            }

            if self.comparator.compare(block_handle.end_key(), key) == core::cmp::Ordering::Greater
            {
                return Ok(None);
            }
        }

        Ok(None)
    }

    /// Like [`Table::get`], but also returns the [`Block`] containing the value.
    ///
    /// Used by `get_pinned()` to construct `PinnableSlice::Pinned`.
    ///
    pub(crate) fn get_with_block(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
    ) -> crate::Result<Option<(InternalValue, Block)>> {
        // Tight-space restriction (mirrors `Table::get`): a key below the bound
        // misses so the read falls through to the superseding output and never
        // touches the punched-out prefix.
        if self.is_below_restriction(key) {
            return Ok(None);
        }

        let global_seqno = self.global_seqno();
        // A query snapshot below this table's base seqno predates the table, so
        // none of its rows are visible. `checked_sub` yields `None` there (where a
        // saturating sub would silently clamp to 0); the seqno-range gate below
        // then handles the in-range case.
        let Some(seqno) = seqno.checked_sub(global_seqno) else {
            return Ok(None);
        };

        if self.metadata.seqnos.0 >= seqno {
            return Ok(None);
        }

        // The filter, index and data blocks this lookup reads share the file.
        let fd = LookupFd::default();
        let bloom = self.check_bloom(key, key_hash, &fd)?;
        self.count_probe(&bloom);
        if bloom.should_skip() {
            return Ok(None);
        }

        // Access accounting after the seqno-range + bloom gates (mirrors `Table::get`).
        self.record_access();

        let result = self.point_read_with_block(key, seqno, key_hash, &fd)?;

        // Translate table-local seqno back to global coordinate (see Table::get).
        let result = result.map(|(mut iv, block)| {
            iv.key.seqno = apply_global_seqno(iv.key.seqno, global_seqno);
            (iv, block)
        });

        #[cfg(feature = "metrics")]
        {
            use core::sync::atomic::Ordering::Relaxed;
            if result.is_none() && bloom.has_filter() {
                self.metrics.filter_queries.fetch_add(1, Relaxed);
            }
        }
        if result.is_none() && bloom.has_filter() {
            self.count_false_positive(seqno);
        }

        Ok(result)
    }

    /// Shared block-index walk for point reads. Returns the matching entry
    /// together with the [`DataBlock`] it was found in, so callers that need
    /// the block (e.g. for [`PinnableSlice`]) can keep it alive.
    /// Resolve the data block holding `key_hash`'s newest version (plus an
    /// optional in-block slot hint) via the retrieval-ribbon locator, if one is
    /// loaded. `Ok(None)` means no locator or the ribbon could not answer → the
    /// caller uses the sorted-index walk.
    fn locator_block(
        &self,
        key_hash: u64,
    ) -> crate::Result<Option<crate::table::locator::Located>> {
        match &self.locator_index {
            Some(loc) => loc.locate_block(key_hash),
            None => Ok(None),
        }
    }

    fn point_read_inner(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
        fd: &LookupFd,
    ) -> crate::Result<Option<(InternalValue, DataBlock)>> {
        // Fast path: a retrieval-ribbon locator resolves the key to its data
        // block in O(1), skipping the index-block binary search. The located
        // block holds the newest version (the run's highest-seqno prefix), so a
        // hit returns the correct MVCC answer and a miss (absent key, or the
        // visible version lives in a later block) safely falls through to the
        // index walk below.
        if let Some((handle, hint)) = self.locator_block(key_hash)?
            && let Some(data_block) = self.load_point_block(&handle, key, fd)?
        {
            // A columnar block is narrowed to this key's rows by load_point_block,
            // so the full-block slot hint does not apply.
            let is_columnar = cfg!(feature = "columnar") && self.metadata.columnar;
            let found = match hint {
                Some((slot, is_entry)) if !is_columnar => {
                    data_block.point_read_at_slot(slot, is_entry, key, seqno, &self.comparator)?
                }
                _ => data_block.point_read_hashed(key, Some(key_hash), seqno, &self.comparator)?,
            };
            if let Some(item) = found {
                return Ok(Some((item, data_block)));
            }
        }

        // Borrowing point-read seek: avoids cloning the index block + reuses
        // the trailer metadata parsed at table open (see
        // `BlockIndexImpl::point_read_reader`).
        let Some(mut iter) = self.block_index.point_read_reader(key, seqno) else {
            return Ok(None);
        };

        while let Some(block_handle) = iter.next_with(fd) {
            let block_handle = block_handle?;

            // A columnar block carrying no row for this key (absent / wholly
            // deleted) returns None here; still honor the end-key cutoff before
            // skipping, so an absent key below this block's end key stops the
            // scan instead of probing every later candidate block.
            let Some(data_block) = self.load_point_block(block_handle.as_ref(), key, fd)? else {
                if self.comparator.compare(block_handle.end_key(), key)
                    == core::cmp::Ordering::Greater
                {
                    return Ok(None);
                }
                continue;
            };

            if let Some(item) =
                data_block.point_read_hashed(key, Some(key_hash), seqno, &self.comparator)?
            {
                return Ok(Some((item, data_block)));
            }

            // NOTE: If the last block key is higher than ours,
            // our key cannot be in the next block
            if self.comparator.compare(block_handle.end_key(), key) == core::cmp::Ordering::Greater
            {
                return Ok(None);
            }
        }

        Ok(None)
    }

    fn point_read(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
        fd: &LookupFd,
    ) -> crate::Result<Option<InternalValue>> {
        self.point_read_inner(key, seqno, key_hash, fd)
            .map(|opt| opt.map(|(iv, _)| iv))
    }

    /// Like [`Table::point_read`], but also returns the underlying [`Block`].
    ///
    /// Holding on to the returned [`Block`] (e.g. for [`PinnableSlice`]) keeps the
    /// block data alive while the value is in use, but does not guarantee that the
    /// cache will retain its own entry for that block.
    fn point_read_with_block(
        &self,
        key: &[u8],
        seqno: SeqNo,
        key_hash: u64,
        fd: &LookupFd,
    ) -> crate::Result<Option<(InternalValue, Block)>> {
        self.point_read_inner(key, seqno, key_hash, fd)
            .map(|opt| opt.map(|(iv, db)| (iv, db.inner)))
    }

    /// Batch point-read variant of [`Table::get`].
    ///
    /// Each input pair is `(key, key_hash)`. The slice **must be
    /// strictly sorted ascending by `key` under this table's
    /// comparator** — duplicate adjacent keys are a caller bug
    /// (callers should dedup before batching; a duplicate
    /// suggests a logic error in the query construction) and
    /// are rejected by a `debug_assert!` in debug builds.
    /// Returns one `Option<InternalValue>` per input pair in
    /// input order: `Some(_)` for found values (including
    /// tombstones — callers distinguish via [`InternalValue`]'s
    /// value type), `None` for absent keys.
    ///
    /// # Hash contract
    ///
    /// `key_hash` **must** equal `crate::hash::hash64(key)` — the
    /// same function the writer used when populating the bloom
    /// filter. The bloom probe consumes the hash; the
    /// key↔hash agreement check is a `debug_assert!` only, so
    /// release builds trust the caller. Passing a wrong hash in
    /// release produces false-negative skips: the corresponding
    /// `results[i]` slot stays `None` as if the key weren't in
    /// the table (the result vector itself is always
    /// `sorted_keys.len()` long — nothing is dropped from it).
    /// Callers should derive both values from the same
    /// `(&[u8], u64) = (key, hash64(key))` expression at the
    /// same scope to make the agreement trivially auditable.
    ///
    /// In partitioned-filter mode (`pinned_filter_index` /
    /// `filter_tli`), `check_bloom` ALSO uses the raw `key`
    /// bytes — not the hash — to select which filter partition
    /// to probe. The hash drives the bit probes inside the
    /// selected partition. Bottom line: BOTH inputs are
    /// load-bearing in the partitioned case; only the
    /// monolithic-filter case is "hash-only".
    ///
    /// # Why this exists vs. calling [`Table::get`] in a loop
    ///
    /// Sequential per-key calls each pay:
    ///
    /// 1. Bloom-filter dereference + N hash probes — duplicated
    ///    across calls.
    /// 2. Block-index seek from scratch — every call walks
    ///    `forward_reader(key, seqno)` and re-pays the index
    ///    binary search even when the previous call already
    ///    landed inside the same data block.
    /// 3. Block load — every call re-fetches the data block
    ///    from cache, so cache hits still pay a hashmap lookup
    ///    + Arc clone per call.
    ///
    /// `batch_get` collapses all three:
    ///
    /// 1. Filter probed once per key in a tight loop. For
    ///    monolithic filters (the default) the filter block is
    ///    fetched once and the loop just checks N hashes
    ///    against it. For partitioned filters
    ///    (`pinned_filter_index` / `filter_tli`), each probe
    ///    still seeks the partition index and may load the
    ///    relevant partition block lazily — so "one filter
    ///    fetch total" only holds in the monolithic case;
    ///    partitioned filters amortise loads across keys that
    ///    land in the same partition rather than across the
    ///    whole batch.
    /// 2. Block-index seek runs at the smallest passing key and
    ///    again only at a passing key past the block before it;
    ///    keys in the same or the next block share the walk, and
    ///    a sparse batch over a large table never steps through
    ///    the entries and partitions between its keys.
    /// 3. Each data block is loaded at most once for the entire
    ///    batch. Multiple input keys that fall in the same block
    ///    share a single load.
    ///
    /// The wire-format is identical to N independent `get()`
    /// calls; the savings are purely call-overhead.
    ///
    /// # Sort requirement
    ///
    /// Sorting is the caller's responsibility because the
    /// `batch_get_from_tables` driver already maintains the
    /// remaining-keys list in comparator order between L1+ runs
    /// (re-sorted after each `covered_miss` split). Re-sorting
    /// inside `batch_get` would be redundant work; passing
    /// pre-sorted input lets the implementation rely on a
    /// monotone two-pointer walk between input keys and block
    /// boundaries.
    ///
    /// # Errors
    ///
    /// Propagates any I/O / corruption error from the filter
    /// fetch, block-index read, or data-block load. On error
    /// the partial `results` vector is discarded — callers
    /// observe an all-or-nothing outcome per call.
    #[expect(
        clippy::indexing_slicing,
        reason = "every index access in this routine is bounded by construction: \
                  `passing` indices are produced from enumerate(sorted_keys) so they're \
                  < sorted_keys.len() == results.len(); `passing[p]` is guarded by \
                  `p < passing.len()` on every loop iteration; `passing[0]` is read \
                  only after an explicit emptiness check above."
    )]
    pub fn batch_get(
        &self,
        sorted_keys: &[(&[u8], u64)],
        seqno: SeqNo,
    ) -> crate::Result<Vec<Option<InternalValue>>> {
        let mut results: Vec<Option<InternalValue>> = vec![None; sorted_keys.len()];

        if sorted_keys.is_empty() {
            return Ok(results);
        }

        // Debug-time guard for the sorted-input contract.
        // Unsorted input would silently return wrong Nones
        // (the two-pointer walk between block_iter and the
        // input slice assumes monotone keys); catch the
        // accidental misuse before it ships to a release
        // benchmark. Strict-monotone is the contract — equal
        // adjacent keys would be a duplicate query, also a
        // caller bug.
        debug_assert!(
            sorted_keys
                .windows(2)
                .all(|w| self.comparator.compare(w[0].0, w[1].0) == core::cmp::Ordering::Less),
            "batch_get input must be strictly sorted ascending by key under \
             the table's comparator; unsorted/duplicate input produces silent \
             None misses because the two-pointer walk assumes monotone keys"
        );

        let global_seqno = self.global_seqno();
        // A query snapshot below this table's base seqno predates the table, so no
        // key is visible. `checked_sub` yields `None` there (a saturating sub would
        // clamp to 0); the seqno-range gate below handles the in-range case.
        let Some(table_seqno) = seqno.checked_sub(global_seqno) else {
            return Ok(results);
        };

        // Table is entirely above the snapshot — no key is visible.
        if self.metadata.seqnos.0 >= table_seqno {
            return Ok(results);
        }

        // Filter the input through the bloom filter once. The
        // filter resource (mmap / Arc) is fetched lazily by
        // check_bloom on the first call; subsequent calls reuse
        // it through the table-internal cache.
        let mut passing: Vec<usize> = Vec::with_capacity(sorted_keys.len());
        let mut had_filter = false;
        // Every filter, index and data block the batch reads shares the file.
        let fd = LookupFd::default();
        for (i, (key, hash)) in sorted_keys.iter().enumerate() {
            // Below a tight-space restriction, as for a point read.
            if self.is_below_restriction(key) {
                continue;
            }
            let bloom = self.check_bloom(key, *hash, &fd)?;
            self.count_probe(&bloom);
            if !bloom.should_skip() {
                passing.push(i);
                if bloom.has_filter() {
                    had_filter = true;
                }
            }
        }
        if passing.is_empty() {
            return Ok(results);
        }
        // Counted as single reads are, after the seqno-range and filter gates.
        self.record_accesses(u64::try_from(passing.len()).unwrap_or(u64::MAX));
        // The filter let these keys through; the ones no read below finds are
        // its false positives.
        let count_false_positives = |results: &[Option<InternalValue>]| {
            if had_filter && self.probe_stats().is_some() {
                for &i in &passing {
                    if results.get(i).is_some_and(Option::is_none) {
                        self.count_false_positive(table_seqno);
                    }
                }
            }
        };

        // Seek the block index once at the smallest passing key.
        // forward_reader returns the first block whose end_key
        // can cover that key; everything past it walks forward.
        let first_key = sorted_keys[passing[0]].0;
        let Some(mut block_iter) = self.block_index.forward_reader(first_key, table_seqno) else {
            // No block can contain the smallest passing key — every
            // passing key is "negative with filter present" for
            // metrics accounting purposes, mirroring Table::get
            // where a bloom-passing key that point_read can't find
            // increments filter_queries. Falling through to the
            // shared metrics block below ensures the batch path
            // doesn't under-report compared to N independent get()s.
            #[cfg(feature = "metrics")]
            {
                // Use core::* rather than std::* re-exports: the
                // `metrics` feature isn't std-gated in Cargo.toml,
                // and `Ordering` lives in `core::sync::atomic`
                // unchanged — keeps this hot-path import no-std
                // friendly without any runtime impact (the std
                // path is just a re-export of the core symbol).
                use core::sync::atomic::Ordering::Relaxed;
                if had_filter && !passing.is_empty() {
                    self.metrics
                        .filter_queries
                        .fetch_add(passing.len(), Relaxed);
                }
            }
            count_false_positives(&results);
            return Ok(results);
        };

        // Two-pointer walk: outer loop advances block_iter, inner
        // loop drains passing keys that fall inside the current
        // block's range. Both sides are monotone (sorted by the
        // same comparator), so each side advances at most once
        // per pair.
        let mut p = 0_usize;
        while p < passing.len() {
            let Some(handle_result) = block_iter.next_with(&fd) else {
                break;
            };
            let block_handle = handle_result?;
            let end_key = block_handle.end_key();

            // Lazy load: only fetch the data block if at least
            // one passing key falls into this block's range.
            // Most blocks will contain at least one key (we
            // seeked here precisely because the first key did),
            // but bloom may have skipped enough later keys that
            // the next passing one is in a later block — in
            // which case we skip the load.
            let first_in_block = sorted_keys[passing[p]].0;
            if self.comparator.compare(first_in_block, end_key) == core::cmp::Ordering::Greater {
                // The next passing key is BEYOND this block's range: skip
                // the load and seek the index at that key, so a sparse
                // batch over a large table reads only the entries and
                // partitions its keys fall in instead of stepping through
                // every one between them.
                let Some(reader) = self.block_index.forward_reader(first_in_block, table_seqno)
                else {
                    break;
                };
                block_iter = reader;
                continue;
            }

            // A wholly-deleted columnar block carries no keys; skip it.
            let Some(data_block) = self.load_data_block(block_handle.as_ref(), &fd)? else {
                continue;
            };

            // Drain passing keys that fall inside [..end_key].
            //
            // Three-way handling mirrors Table::point_read_inner's
            // end-key boundary check:
            //   - Greater (key > end_key): key belongs to a later
            //     block. Break inner loop, advance outer.
            //   - Less    (key < end_key): key is strictly inside
            //     this block. point_read decides; either way the
            //     key cannot continue into the next block (block
            //     keys are sorted, and a later block's first key
            //     is > this block's end_key), so we always advance
            //     p — set Some on hit, leave None on miss.
            //   - Equal   (key == end_key): block end_key matches
            //     the query exactly. point_read may return None
            //     even when a visible version of THIS user key
            //     exists in the NEXT block (same-key spans block
            //     boundary — common with MVCC versions of a hot
            //     key). On None, do NOT advance p — break out so
            //     the next outer iteration loads the next block
            //     and retries the same key.
            while p < passing.len() {
                let key_idx = passing[p];
                let (key, key_hash) = sorted_keys[key_idx];
                match self.comparator.compare(key, end_key) {
                    core::cmp::Ordering::Greater => break,
                    core::cmp::Ordering::Less => {
                        if let Some(mut item) = data_block.point_read_hashed(
                            key,
                            Some(key_hash),
                            table_seqno,
                            &self.comparator,
                        )? {
                            // Translate table-local seqno back to
                            // the global coordinate so callers can
                            // compare results across tables /
                            // memtables (matches Table::get's
                            // contract).
                            item.key.seqno = apply_global_seqno(item.key.seqno, global_seqno);
                            results[key_idx] = Some(item);
                        }
                        p += 1;
                    }
                    core::cmp::Ordering::Equal => {
                        if let Some(mut item) = data_block.point_read_hashed(
                            key,
                            Some(key_hash),
                            table_seqno,
                            &self.comparator,
                        )? {
                            item.key.seqno = apply_global_seqno(item.key.seqno, global_seqno);
                            results[key_idx] = Some(item);
                            p += 1;
                        } else {
                            // Same user key may continue in the
                            // next block — leave p in place so the
                            // outer loop's next iteration retries
                            // this key against the next block.
                            break;
                        }
                    }
                }
            }
        }

        #[cfg(feature = "metrics")]
        {
            // core::* (vs the std re-export) for no-std friendliness;
            // see the comment on the matching import above.
            use core::sync::atomic::Ordering::Relaxed;
            // Mirror Table::get's accounting: count negative
            // point lookups that reached storage despite a
            // filter being present. Only keys that passed bloom
            // AND came back empty count.
            if had_filter {
                let negative_with_filter =
                    passing.iter().filter(|&&i| results[i].is_none()).count();
                if negative_with_filter > 0 {
                    // filter_queries is AtomicUsize; the count is
                    // already a usize, no conversion needed.
                    self.metrics
                        .filter_queries
                        .fetch_add(negative_with_filter, Relaxed);
                }
            }
        }
        count_false_positives(&results);

        Ok(results)
    }

    /// Shared setup for the prewarm and chunked block planners: rejects a table
    /// that cannot contribute (empty input, or entirely above the read snapshot),
    /// bloom-filters `sorted_keys` to the passing positions, and opens a forward
    /// block-index reader at the first passing key.
    ///
    /// `Ok(Some(..))` carries the passing positions, the reader, and the
    /// table-local read seqno. `Ok(None)` means the table genuinely contributes no
    /// block (nothing passes the snapshot/bloom/index). `Err` is a real
    /// [`Table::check_bloom`] failure (a partitioned filter's block read) and is
    /// propagated so the authoritative chunked planner surfaces it instead of
    /// mistaking it for a miss; the best-effort prewarm planner maps it back to
    /// `None`.
    ///
    /// The filter answers are added to `tally` when one is given, for the
    /// caller to count once it answers from this plan. Filter blocks are read
    /// through `fd`, the caller's lookup.
    #[expect(
        clippy::indexing_slicing,
        reason = "passing[0] is valid after the emptiness check"
    )]
    fn plan_block_walk_setup(
        &self,
        sorted_keys: &[(&[u8], u64)],
        seqno: SeqNo,
        tally: &mut crate::table::probe_stats::PlanCounts,
        fd: &LookupFd,
    ) -> crate::Result<Option<(Vec<usize>, block_index::BlockIndexIterImpl, SeqNo)>> {
        if sorted_keys.is_empty() {
            return Ok(None);
        }
        let global_seqno = self.global_seqno();
        let Some(table_seqno) = seqno.checked_sub(global_seqno) else {
            return Ok(None);
        };
        if self.metadata.seqnos.0 >= table_seqno {
            return Ok(None);
        }
        let mut passing: Vec<usize> = Vec::with_capacity(sorted_keys.len());
        for (i, (key, hash)) in sorted_keys.iter().enumerate() {
            // Below a tight-space restriction, as for a point read.
            if self.is_below_restriction(key) {
                continue;
            }
            // Counted with the plan, not here: a level handed to the serial
            // resolve is probed and counted there.
            let bloom = self.judge_bloom(key, *hash, fd)?;
            Self::tally_bloom(tally, &bloom);
            if !bloom.should_skip() {
                passing.push(i);
            }
        }
        if passing.is_empty() {
            return Ok(None);
        }
        let Some(block_iter) = self
            .block_index
            .forward_reader(sorted_keys[passing[0]].0, table_seqno)
        else {
            // Every passed key lies past the last block: none is held.
            self.tally_blockless(tally, table_seqno, passing.len());
            return Ok(None);
        };
        Ok(Some((passing, block_iter, table_seqno)))
    }

    /// Counts in `tally` the `keys` the filter let through that no block of
    /// the table can hold, read at `table_seqno`: each a false positive, as
    /// [`Self::count_false_positive`] counts one, and a filter query that
    /// reached the table, as a point read counts one.
    pub(crate) fn tally_blockless(
        &self,
        tally: &mut crate::table::probe_stats::PlanCounts,
        table_seqno: SeqNo,
        keys: usize,
    ) {
        if !self.has_filter() {
            return;
        }
        tally.filter_queries += keys;
        if table_seqno > self.metadata.seqnos.1 {
            tally.probes.negatives += keys as u64;
        }
    }

    /// Charges blocks of `block_type` a batched multi-get read is about to ask
    /// of the filesystem, at the moment it is issued.
    #[cfg_attr(
        not(feature = "metrics"),
        expect(
            clippy::unused_self,
            reason = "the table's counters are the feature's payload"
        )
    )]
    pub(crate) fn record_batched_read(&self, block_type: BlockType, handles: &[BlockHandle]) {
        #[cfg(feature = "metrics")]
        for handle in handles {
            crate::table::util::record_block_read(&self.metrics, block_type, handle.size().into());
        }
        #[cfg(not(feature = "metrics"))]
        let _ = (block_type, handles);
    }

    /// Capacity in bytes of this table's (shared) block cache, for the level
    /// prewarm's eviction-avoiding size bound.
    pub(crate) fn cache_capacity(&self) -> u64 {
        self.cache.capacity()
    }

    /// How many files the descriptor cache this table opens through keeps
    /// open, or `None` when its descriptor is pinned and always open.
    pub(crate) fn descriptor_capacity(&self) -> Option<u64> {
        self.file_accessor
            .as_descriptor_table()
            .map(crate::descriptor_table::DescriptorTable::capacity)
    }

    /// This table's file, for a caller that reads its blocks itself.
    ///
    /// # Errors
    ///
    /// Propagates a failure to open the file.
    pub(crate) fn open_file(&self) -> crate::Result<Arc<dyn crate::fs::FsFile>> {
        self.lookup_file(LookupFd::default())
    }

    /// The file `fd` resolved for a lookup, or this table's file taken now,
    /// owned for a caller that reads the lookup's blocks itself. Counted as the
    /// load path counts the file it opens.
    fn lookup_file(&self, fd: LookupFd) -> crate::Result<Arc<dyn crate::fs::FsFile>> {
        Ok(fd.into_file(
            &self.file_accessor,
            &self.global_id(),
            &self.path,
            ReadCharge::Foreground,
            #[cfg(feature = "metrics")]
            &self.metrics,
        )?)
    }

    /// Whether this table's data blocks need the special load path rather than a
    /// plain bytes decode: Page-ECC (re-read recovery) or columnar (PAX
    /// reconstruction). The chunked `multi_get` resolver reads these via
    /// [`Table::load_data_block`] instead of [`Table::decode_data_block_from_bytes`].
    pub(crate) fn is_chunk_special(&self) -> bool {
        if self.metadata.ecc_params.is_some() {
            return true;
        }
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            return true;
        }
        false
    }

    /// Plans the data blocks [`Table::batch_get`] would read for `sorted_keys`
    /// (bloom + block-index walk, no decode), returning this table's file handle,
    /// the table-local read seqno, whether it needs the special load path, and per
    /// block the positions (into `sorted_keys`) of the keys that fall in it.
    ///
    /// Used by the chunked `multi_get` resolver to read MANY SSTs' blocks in one
    /// batch and point-read directly, without the cache. Conservative at block
    /// boundaries: a key equal to a block's end key is listed in that block AND
    /// the next (an MVCC version of the same key can span the boundary), mirroring
    /// `batch_get`'s span-retry; the higher-seqno hit wins at resolution.
    ///
    /// `Ok(None)` means this table covers none of `sorted_keys`. Unlike the
    /// best-effort prewarm planner, a bloom-probe or table-open failure is
    /// PROPAGATED (not swallowed to `None`): the chunked resolver is authoritative
    /// for its level, so a swallowed error would let a stale lower level answer.
    ///
    /// # Errors
    ///
    /// Propagates a bloom-probe or table-open failure.
    ///
    /// The filter answers, and the filter queries and skips they make, are
    /// added to `tally`: the chunked resolve counts them once it answers from
    /// its plan, and not when it hands the level to the serial resolve, which
    /// probes the same filters again.
    #[expect(
        clippy::indexing_slicing,
        reason = "`passing` positions index into `sorted_keys` (< its len); `passing[p]` \
                  is guarded by `p < passing.len()` each iteration."
    )]
    pub(crate) fn plan_block_tasks(
        &self,
        sorted_keys: &[(&[u8], u64)],
        seqno: SeqNo,
        tally: &mut crate::table::probe_stats::PlanCounts,
    ) -> crate::Result<Option<BlockTaskPlan>> {
        // The filter and index blocks the plan reads, and the file the planned
        // blocks are read through after it, share one descriptor access.
        let fd = LookupFd::default();
        let Some((passing, mut block_iter, table_seqno)) =
            self.plan_block_walk_setup(sorted_keys, seqno, tally, &fd)?
        else {
            return Ok(None);
        };

        let mut blocks: Vec<(BlockHandle, Vec<usize>)> = Vec::new();
        let mut p = 0_usize;
        while p < passing.len() {
            // None ends the index; an Err (index-read / decode failure) is
            // PROPAGATED, not treated as end-of-index. Swallowing it would skip
            // the rest of this table and let a lower level answer a key the
            // failed table actually covers (same `?` contract as `batch_get`).
            let Some(handle_result) = block_iter.next_with(&fd) else {
                break;
            };
            let block_handle = handle_result?;
            let end_key = block_handle.end_key();
            let first_in_block = sorted_keys[passing[p]].0;
            if self.comparator.compare(first_in_block, end_key) == core::cmp::Ordering::Greater {
                // Sought at the next key, as `batch_get` does, instead of
                // stepped through every entry between.
                let Some(reader) = self.block_index.forward_reader(first_in_block, table_seqno)
                else {
                    break;
                };
                block_iter = reader;
                continue;
            }
            let handle = *block_handle.as_ref();
            let mut block_keys: Vec<usize> = Vec::new();
            while p < passing.len() {
                let pos = passing[p];
                match self.comparator.compare(sorted_keys[pos].0, end_key) {
                    core::cmp::Ordering::Greater => break,
                    core::cmp::Ordering::Less => {
                        block_keys.push(pos);
                        p += 1;
                    }
                    // Equal: list in THIS block and (by not advancing p) the next,
                    // since a version of this key may continue across the boundary.
                    core::cmp::Ordering::Equal => {
                        block_keys.push(pos);
                        break;
                    }
                }
            }
            blocks.push((handle, block_keys));
        }
        // The passed keys past the last block. A key equal to that block's
        // end key is listed in it and left for a next block there is not.
        let listed = blocks.last().map(|(_, keys)| keys.as_slice());
        let blockless = passing
            .iter()
            .skip(p)
            .filter(|pos| !listed.is_some_and(|keys| keys.contains(pos)))
            .count();
        self.tally_blockless(tally, table_seqno, blockless);
        if blocks.is_empty() {
            return Ok(None);
        }

        // The blocks are read through this file, with no second lookup.
        let file = self.lookup_file(fd)?;
        Ok(Some((file, table_seqno, self.is_chunk_special(), blocks)))
    }

    /// Decodes the data block at `handle` from its on-disk `bytes` (read by the
    /// batched multi-get), using the same path as [`Table::load_data_block`]
    /// for a non-special table ([`Block::from_reader`] shares the header /
    /// decrypt helpers), so the block is byte-identical, and puts it in the
    /// cache when its weight fits in `room`, taking it out of `room`. Not for
    /// Page-ECC / columnar tables
    /// ([`is_chunk_special`]).
    ///
    /// # Errors
    ///
    /// Propagates a corruption / decode error (the resolver surfaces it).
    pub(crate) fn decode_data_block_keeping(
        &self,
        bytes: &[u8],
        handle: &BlockHandle,
        room: &mut u64,
        lead: Option<crate::cache::BlockLead>,
    ) -> crate::Result<DataBlock> {
        let block = self.decode_block_from_bytes(bytes, *handle.offset(), BlockType::Data)?;
        // Weighed as the cache weighs it: decoded, not as it was read.
        let weight = crate::cache::block_weight(&block);
        if weight <= *room {
            *room -= weight;
            self.cache
                .insert_block(self.global_id(), handle.offset(), block.clone());
        }
        // Published whether cached or not: a point read waiting on it caches
        // the block itself when this read had no room left for it.
        if let Some(lead) = lead {
            lead.publish(&block);
        }
        self.data_block_of(block)
    }

    /// How a batched read gets the data block at `handle` of this Page-ECC or
    /// columnar table: as bytes it reads with its other blocks, then
    /// [`Self::decode_special_block`], or through the table's own load path in
    /// a job.
    ///
    /// A columnar group goes through the load path when its directory is
    /// cached (its pages may be too, which that path takes from the cache),
    /// when it is wider than one request, or when it carries Page-ECC, whose
    /// recovery re-reads a page to confirm a heal.
    pub(crate) fn batched_special_read(&self, handle: &BlockHandle) -> SpecialRead {
        if self.check_block_size(handle).is_err() {
            return SpecialRead::Load;
        }
        #[cfg(feature = "columnar")]
        if self.metadata.columnar
            && (self.metadata.ecc_params.is_some()
                || handle.size() > self.read_budget().io_buffer()
                || self
                    .cache
                    .get_directory(self.global_id(), handle.offset(), false)
                    .is_some())
        {
            return SpecialRead::Load;
        }
        SpecialRead::Bytes {
            offset: *handle.offset(),
            len: handle.size() as usize,
        }
    }

    /// The data block at `handle` of this Page-ECC table, when the cache
    /// holds it, counted as a cache hit as the load path counts one. Never a
    /// columnar group's: the cache holds its directory and pages, not the
    /// group, and the load path assembles it from them.
    pub(crate) fn cached_special_block(&self, handle: &BlockHandle) -> Option<DataBlock> {
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            return None;
        }
        self.cached_data_block(handle)
    }

    /// The role a batched read of a Page-ECC or columnar data block is
    /// charged to: a columnar group is read as its pages are.
    #[cfg_attr(
        not(feature = "columnar"),
        expect(clippy::unused_self, reason = "only a columnar table reads as pages")
    )]
    pub(crate) fn special_read_role(&self) -> BlockType {
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            return BlockType::ColumnPage;
        }
        BlockType::Data
    }

    /// The data block at `handle` of this Page-ECC or columnar table, from the
    /// `bytes` [`Self::batched_special_read`] asked for: checked, recovered
    /// and reconstructed exactly as the load path does it, cached (a row block
    /// while it fits in `room`), and `None` when a columnar block's delete
    /// mask removes every row.
    ///
    /// # Errors
    ///
    /// A check fails; and a block whose payload Page-ECC had to correct,
    /// which the load path reads again to schedule its heal, so the caller
    /// takes that path for it.
    pub(crate) fn decode_special_block(
        &self,
        handle: &BlockHandle,
        bytes: alloc::vec::Vec<u8>,
        room: &mut u64,
    ) -> crate::Result<Option<DataBlock>> {
        #[cfg(feature = "columnar")]
        if self.metadata.columnar {
            let fd = LookupFd::default();
            let blocks = self
                .group_read(handle, ReadCharge::Foreground, &fd)
                .load_whole(&crate::Slice::from(bytes))?;
            return self.columnar_data_block_from(handle, &blocks, ReadCharge::Foreground);
        }
        let compression = self.metadata.data_block_compression;
        let transform = crate::table::util::build_block_transform(
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.zstd_dictionary.as_deref(),
        )?;
        let identity = crate::table::block::BlockIdentity {
            table_id: self.global_id().table_id(),
            block_type: BlockType::Data,
            dict_id: compression.dict_id(),
            window_log: 0,
        };
        let (header, payload, status, recovery) =
            Block::verify_frame(bytes, *handle, identity, &transform)?;
        if matches!(status, crate::table::block::EccStatus::Corrected) {
            return Err(crate::Error::Io(crate::io::Error::other(
                "a block Page-ECC corrected is loaded through the path that heals it",
            )));
        }
        let mut produced = 0;
        let data = Block::decompress_payload(&header, payload, &transform, &mut produced);
        #[cfg(feature = "metrics")]
        crate::table::util::record_block_decoded(&self.metrics, ReadCharge::Foreground, produced);
        let block = crate::table::util::admit_read_block(
            self.global_id(),
            &self.path,
            &self.file_accessor,
            handle,
            BlockType::Data,
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            self.zstd_dictionary.as_deref(),
            self.heal_hints.get().map(AsRef::as_ref),
            #[cfg(feature = "metrics")]
            &self.metrics,
            ReadCharge::Foreground,
            Block {
                header,
                data: data?,
            },
            status,
            recovery,
        )?;
        let weight = crate::cache::block_weight(&block);
        if weight <= *room {
            *room -= weight;
            self.cache
                .insert_block(self.global_id(), handle.offset(), block.clone());
        }
        self.data_block_of(block).map(Some)
    }

    /// `block`, a data block of this table, as the point reads take it.
    pub(crate) fn data_block_of(&self, block: Block) -> crate::Result<DataBlock> {
        DataBlock::from_loaded(block, self.metadata.kv_checksum_algo.is_some())
    }

    /// Refuses the block at `handle` when its size is one no block of this
    /// table can have, without allocating for it.
    ///
    /// # Errors
    ///
    /// The size is past the largest block this table can hold.
    pub(crate) fn check_block_size(&self, handle: &BlockHandle) -> crate::Result<()> {
        crate::table::block::check_on_disk_size(
            u64::from(handle.size()),
            self.encryption.as_deref(),
            self.metadata.ecc_params,
        )
    }

    /// The data block at `handle`, when the cache holds it, counted as a cache
    /// hit as the load path counts one.
    pub(crate) fn cached_data_block(&self, handle: &BlockHandle) -> Option<DataBlock> {
        let block = self.cached_block(handle, BlockType::Data)?;
        DataBlock::from_loaded(block, self.metadata.kv_checksum_algo.is_some()).ok()
    }

    /// The block of `block_type` at `handle`, when the cache holds it, counted
    /// as a cache hit as the load path counts one.
    pub(crate) fn cached_block(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
    ) -> Option<Block> {
        let block = self
            .cache
            .get_block(self.global_id(), handle.offset())
            .filter(|block| block.header.block_type == block_type)?;
        #[cfg(feature = "metrics")]
        crate::table::util::record_block_load_cached(&self.metrics, block_type);
        Some(block)
    }

    /// The codec a block a batched read decodes is written with. Filter blocks
    /// are written uncompressed and without the dictionary, index blocks with
    /// the index codec, data blocks with the data codec and its dictionary:
    /// the same choice each block's load makes.
    fn batched_codec(&self, block_type: BlockType) -> CompressionType {
        match block_type {
            BlockType::Filter => CompressionType::None,
            BlockType::Index => self.metadata.index_block_compression,
            _ => self.metadata.data_block_compression,
        }
    }

    /// Claims the lead of the load of the block at `handle`, of `block_type`,
    /// for a batched read about to read it with others, when `lead` lets it:
    /// a point read missing the same block meanwhile then waits for it rather
    /// than reading it again. `None` when the read reads it alone. Never
    /// waits, since a batched read holds the leads of its other blocks.
    pub(crate) fn claim_batched_block(
        &self,
        handle: &BlockHandle,
        block_type: BlockType,
        lead: bool,
    ) -> Option<crate::cache::BlockLead<'_>> {
        self.cache.claim_batched_block(
            self.global_id(),
            handle.offset(),
            crate::cache::LoadIdentity::Block {
                block_type,
                size: handle.size(),
                compression: self.batched_codec(block_type),
                encrypted: self.encryption.is_some(),
            },
            lead,
        )
    }

    /// Decodes the on-disk `bytes` of this table's block of `block_type` read
    /// at `offset`, with the codec that block type is written with, exactly as
    /// the load path decodes it; a block of another type is refused. Not for
    /// Page-ECC tables, whose recovery needs the re-reading load path.
    ///
    /// # Errors
    ///
    /// Propagates a corruption or decode error.
    pub(crate) fn decode_block_from_bytes(
        &self,
        bytes: &[u8],
        offset: u64,
        block_type: BlockType,
    ) -> crate::Result<Block> {
        // Never an ECC table's block: `from_reader` repairs an ECC-corrected
        // payload silently, and a corrected block kept in the cache as clean
        // would let later cache hits skip the heal scheduling the load path
        // does, leaving the latent fault on disk.
        debug_assert!(
            self.metadata.ecc_params.is_none(),
            "a Page-ECC table's blocks are read through the load path, which heals"
        );
        let compression = self.batched_codec(block_type);
        let transform = crate::table::util::build_block_transform(
            compression,
            self.encryption.as_deref(),
            self.metadata.ecc_params,
            #[cfg(zstd_any)]
            if block_type == BlockType::Data {
                self.zstd_dictionary.as_deref()
            } else {
                None
            },
        )?;
        let identity = crate::table::block::BlockIdentity {
            table_id: self.global_id().table_id(),
            block_type,
            dict_id: compression.dict_id(),
            window_log: 0,
        };
        // The transform runs here, outside the block cache, so its output is
        // charged here, before the result is judged: a block the length or
        // role check refuses was still decoded. The read was charged when the
        // batch was issued.
        let mut produced = 0;
        let decoded = Block::from_reader_counting(
            &mut crate::io::Cursor::new(bytes),
            identity,
            &transform,
            crate::table::block::ChecksumAt::block(identity.table_id, block_type, offset),
            &mut produced,
        );
        #[cfg(feature = "metrics")]
        self.metrics
            .block_bytes_decoded
            .fetch_add(produced as u64, core::sync::atomic::Ordering::Relaxed);
        let block = decoded?;
        if block.header.block_type != block_type {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }
        // Loaded from disk, as the load path counts a block once it passed
        // every check.
        #[cfg(feature = "metrics")]
        crate::table::util::record_block_loaded(&self.metrics, block_type);
        Ok(block)
    }

    /// Point-reads `key` in an already-decoded `block`, translating the
    /// table-local seqno of any hit back to the global coordinate (matching
    /// [`Table::batch_get`]'s contract).
    ///
    /// # Errors
    ///
    /// Propagates a decode / corruption error from the point read.
    pub(crate) fn point_read_translated(
        &self,
        block: &DataBlock,
        key: &[u8],
        key_hash: u64,
        table_seqno: SeqNo,
    ) -> crate::Result<Option<InternalValue>> {
        let global_seqno = self.global_seqno();
        Ok(block
            .point_read_hashed(key, Some(key_hash), table_seqno, &self.comparator)?
            .map(|mut item| {
                item.key.seqno = apply_global_seqno(item.key.seqno, global_seqno);
                item
            }))
    }

    /// Whether the table has a filter to probe.
    pub(crate) fn has_filter(&self) -> bool {
        self.pinned_filter_block.is_some()
            || self.pinned_filter_index.is_some()
            || self.regions.filter.is_some()
            || self.regions.filter_tli.is_some()
    }

    /// Creates a scanner over the `Table`.
    ///
    /// The scanner is ĺogically the same as a normal iter(),
    /// however it uses its own file descriptor, does not look into the block cache
    /// and uses buffered I/O.
    ///
    /// Used for compactions and thus not available to a user.
    ///
    /// # Errors
    ///
    /// Will return `Err` if an IO error occurs.
    #[doc(hidden)]
    pub fn scan(&self) -> crate::Result<Scanner> {
        self.scan_paced(None)
    }

    /// [`Self::scan`], telling `pace` how long each read from the file takes,
    /// from the first.
    pub(crate) fn scan_paced(
        &self,
        pace: Option<&crate::table::util::Pacer>,
    ) -> crate::Result<Scanner> {
        #[expect(
            clippy::expect_used,
            reason = "there shouldn't be 4 billion data blocks in a single table"
        )]
        let mut block_count: usize = self
            .metadata
            .data_block_count
            .try_into()
            .expect("data block count should fit");

        // Tight-space restriction: start at the first LIVE block. Blocks
        // wholly below the bound are hole-punched (they read as zeros and
        // cannot decode), and even before the punch runs their rows'
        // authoritative copies live in the superseding slice output — a
        // compaction reading them here would merge every prefix row twice.
        // The bound never exceeds the table's last key, so at least one live
        // block always remains; the straddling block's sub-bound entries are
        // dropped by the scanner's key filter.
        let mut start_offset = 0u64;
        // A columnar scan streams the data without the index, so the index
        // hands it the entry of every group it will read: a group whose tag or
        // lengths disagree with its entry is refused against it, as an indexed
        // read refuses it.
        let mut groups = Vec::new();
        if self.1.is_some() || self.metadata.columnar {
            let mut started = self.1.is_none();
            // The index walk reads from the file too, a cold index at length:
            // its reads report as the scan's do.
            let walk = self.maintenance_index_walk();
            let walk = match pace {
                Some(pace) => walk.with_pace(alloc::sync::Arc::clone(pace)),
                None => walk,
            };
            for keyed in walk {
                let keyed = keyed?;
                if !started {
                    if let Some(bound) = &self.1
                        && self.comparator.compare(keyed.end_key(), bound.as_ref())
                            == core::cmp::Ordering::Less
                    {
                        // Cannot underflow: this loop walks the block index the
                        // count was derived from, so at most `block_count`
                        // decrements can ever run.
                        block_count -= 1;
                        continue;
                    }
                    start_offset = keyed.offset().0;
                    started = true;
                    if !self.metadata.columnar {
                        break;
                    }
                }
                groups.push(*keyed.as_ref());
            }
        }
        self.scan_groups(block_count, start_offset, groups, pace)
    }

    /// A scanner of `block_count` blocks from `start_offset`, checking each
    /// columnar group it streams against its index entry in `groups`, and
    /// telling `pace` how long its reads take.
    fn scan_groups(
        &self,
        block_count: usize,
        start_offset: u64,
        groups: Vec<BlockHandle>,
        pace: Option<&crate::table::util::Pacer>,
    ) -> crate::Result<Scanner> {
        Scanner::new(
            &self.fs,
            &self.path,
            block_count,
            self.metadata.data_block_compression,
            self.global_seqno(),
            self.encryption.clone(),
            self.metadata.ecc_params,
            self.metadata.kv_checksum_algo.is_some(),
            #[cfg(zstd_any)]
            self.zstd_dictionary.clone(),
            self.comparator.clone(),
            self.metadata.id,
            self.metadata.columnar,
            self.metadata.data_block_restart_interval,
            start_offset,
            self.1.clone(),
            groups,
            pace.cloned(),
        )
    }

    /// Scans this columnar SST lazily, yielding one [`ColumnBatch`] per row page
    /// of every data block that survives the optional predicate, each carrying
    /// only the projected columns. A block is read when the scan reaches it, so
    /// a caller that stops early reads nothing more.
    ///
    /// `projection` lists the column ids to decode; every other column is
    /// stepped over without decoding. When `predicate` is set, a block or row
    /// page whose statistics prove it out of range is skipped without being
    /// loaded, and, unless the predicate only prunes, each surviving one is
    /// filtered to the rows that match. How far the predicate ran is what
    /// [`ColumnarCursor::predicate_support`] reports for the blocks read so far;
    /// [`Tree::columnar_scan`](crate::Tree::columnar_scan) reports it for a
    /// whole scan.
    ///
    /// [`ColumnBatch`]: crate::table::columnar::ColumnBatch
    /// [`ColumnarCursor::predicate_support`]: crate::table::columnar_cursor::ColumnarCursor::predicate_support
    ///
    /// # Errors
    ///
    /// Returns an error if this SST is not columnar, and, while iterating, on a
    /// block read / decode failure.
    #[cfg(feature = "columnar")]
    pub fn columnar_scan(
        &self,
        projection: &[u16],
        predicate: Option<&crate::table::columnar_predicate::ColumnRangePredicate>,
    ) -> crate::Result<crate::table::columnar_cursor::ColumnarCursor> {
        self.columnar_cursor(
            projection,
            predicate,
            core::ops::Bound::Unbounded,
            core::ops::Bound::Unbounded,
            None,
        )
    }

    /// [`Self::columnar_scan`] over the rows within `lo..hi`: blocks wholly
    /// outside the range are not read. Rows of a boundary block that fall
    /// outside it are still yielded, for the caller to mask. With `share`,
    /// a row group larger than it is read in runs of row pages that fit it.
    #[cfg(feature = "columnar")]
    pub(crate) fn columnar_cursor(
        &self,
        projection: &[u16],
        predicate: Option<&crate::table::columnar_predicate::ColumnRangePredicate>,
        lo: core::ops::Bound<UserKey>,
        hi: core::ops::Bound<UserKey>,
        share: Option<u64>,
    ) -> crate::Result<crate::table::columnar_cursor::ColumnarCursor> {
        crate::table::columnar_cursor::ColumnarCursor::new(
            self, projection, predicate, lo, hi, share,
        )
    }

    /// Creates an iterator over the `Table`.
    ///
    /// # Errors
    ///
    /// Will return `Err` if an IO error occurs.
    #[must_use]
    #[doc(hidden)]
    pub fn iter(&self) -> impl DoubleEndedIterator<Item = crate::Result<InternalValue>> + use<> {
        self.range(..)
    }

    /// Collects the entries of this SST whose global seqno is in
    /// `[target_seqno, end_seqno]`, applying the per-block seqno-bounds skip
    /// when the SST carries it: a data block whose `seqno_bounds` entry cannot
    /// overlap the window is skipped without being read, and an SST without
    /// the section reads and filters every block. Entries come back in the
    /// SST's stored order (key-ascending, seqno-descending within a key);
    /// ordering across sources is the caller's job.
    ///
    /// The upper bound is INCLUSIVE so that a watermark of [`SeqNo::MAX`] — the
    /// value a scan derives when an entry sits at the maximum seqno — still
    /// delivers the entry that defined it.
    /// The upper bound lets the tree-level scan pin a stable snapshot watermark
    /// so a concurrent write cannot leak in mid-scan.
    ///
    /// `block_skip` enables the per-block seqno-bounds optimization (skip data
    /// blocks whose recorded `[seqno_min, seqno_max]` cannot overlap the
    /// window). Pass `false` for a paranoid full scan that reads every block and
    /// filters per entry, so even an undetected-corrupt seqno bound (one that
    /// somehow slipped past the block XXH3 checksum) cannot cause a qualifying
    /// record to be skipped.
    ///
    /// `keys` bounds the blocks read, in the table comparator's order: the
    /// index is sought to the first block that can hold the lower bound and
    /// the walk stops after the first block reaching past the upper one. The
    /// blocks at either end hold keys outside the bounds too; filtering those
    /// is the caller's job.
    ///
    /// # Errors
    ///
    /// Returns `Err` if reading the index or a data block fails.
    #[doc(hidden)]
    pub fn scan_seqno_range(
        &self,
        target_seqno: SeqNo,
        end_seqno: SeqNo,
        block_skip: bool,
        keys: (Bound<&[u8]>, Bound<&[u8]>),
    ) -> crate::Result<Vec<InternalValue>> {
        // Bulk-ingested tables store entries at LOCAL seqno coordinates with a
        // `global_seqno` offset; the on-disk seqno bounds and per-entry seqnos
        // are all local. Translate the incoming global target down to local
        // for the comparisons, then translate matched record seqnos back up to
        // global before returning — exactly as `Table::get` does. For a
        // non-ingested table `global_seqno` is 0 and both translations are
        // no-ops.
        let global_seqno = self.global_seqno();
        // An upper bound BELOW the ingest base excludes the whole table: every
        // effective seqno here is >= `global_seqno`. Checked BEFORE the
        // saturating translation, because both bounds would clamp to local 0
        // and `[0, 0]` is a valid one-seqno window that matches every stored
        // row of a bulk-ingested table (all at local 0) — returning entries
        // whose translated-back seqno exceeds the caller's inclusive bound.
        if end_seqno < global_seqno {
            return Ok(Vec::new());
        }
        // Here the saturating clamp to 0 is the INTENDED result, not the silent
        // overflow-masking the point-read path avoids: a lower bound below the
        // offset means "start at the table's first entry", so clamping the
        // translated lower bound to 0 is exactly right.
        let local_target = target_seqno.saturating_sub(global_seqno);
        // Upper bound in local coords. `SeqNo::MAX` (the unbounded case) maps to
        // `MAX - global_seqno`, still far above any reachable local seqno, so
        // every entry passes (effectively unbounded); a bound below the offset
        // returned above already.
        let local_end = end_seqno.saturating_sub(global_seqno);

        // Empty window (a target ABOVE the watermark — e.g. a bulk-ingest offset
        // that puts the whole table below the caller's target): nothing can
        // qualify, so skip walking the index entirely. Without this a legacy SST
        // (no per-block seqno bounds) would load + filter every block to return
        // nothing on every poll. The bound is inclusive, so equality is a
        // one-seqno window, not an empty one.
        if local_target > local_end {
            return Ok(Vec::new());
        }

        use block_index::BlockIndexIter;
        use core::cmp::Ordering;

        let mut out = Vec::new();

        let mut index = self.block_index.iter();
        // The first block that can hold the lower bound: every block before it
        // ends below the bound.
        if let Bound::Included(lo) | Bound::Excluded(lo) = keys.0
            && !index.seek_lower(lo, SeqNo::MAX)
        {
            return Ok(out);
        }
        for handle in index {
            let handle = handle?;
            // The last block that can hold a key within the upper bound. A
            // block ending ON an included bound may be followed by older
            // versions of that key, and the walk goes on to them.
            let reaches_hi = match keys.1 {
                Bound::Included(hi) => {
                    self.comparator.compare(handle.end_key(), hi) == Ordering::Greater
                }
                Bound::Excluded(hi) => {
                    self.comparator.compare(handle.end_key(), hi) != Ordering::Less
                }
                Bound::Unbounded => false,
            };
            self.collect_seqno_range(&handle, (local_target, local_end), block_skip, &mut out)?;
            if reaches_hi {
                break;
            }
        }

        Ok(out)
    }

    /// The data blocks that can hold a version of `key`, whatever its seqno,
    /// found through the index alone, with the table's file to read them
    /// through. A key's versions run from the block its first one is in
    /// through every block ending on the key.
    ///
    /// # Errors
    ///
    /// The index or the file fails to read.
    pub(crate) fn key_blocks(
        &self,
        key: &[u8],
    ) -> crate::Result<(Arc<dyn crate::fs::FsFile>, Vec<BlockHandle>)> {
        let file = self.open_file()?;
        let mut blocks = Vec::new();
        if let Some(mut index) = self.block_index.forward_reader(key, SeqNo::MAX) {
            let fd = LookupFd::default();
            while let Some(handle) = index.next_with(&fd) {
                let handle = handle?;
                // A block ending before the key holds none of it; one ending
                // on it may be followed by older versions in the next.
                match self.comparator.compare(key, handle.end_key()) {
                    core::cmp::Ordering::Greater => {}
                    core::cmp::Ordering::Equal => blocks.push(*handle.as_ref()),
                    core::cmp::Ordering::Less => {
                        blocks.push(*handle.as_ref());
                        break;
                    }
                }
            }
        }
        Ok((file, blocks))
    }

    /// The versions of `key` in `block`, one of the blocks
    /// [`Self::key_blocks`] names, newest first, with their global seqnos, of
    /// those visible at `seqno`; and whether the block holds a version of the
    /// key at all, whatever its seqno, as the table's reader reports it.
    pub(crate) fn key_versions(
        &self,
        block: &DataBlock,
        key: &[u8],
        seqno: SeqNo,
    ) -> (Vec<InternalValue>, bool) {
        let global_seqno = self.global_seqno();
        let mut versions = Vec::new();
        let mut found = false;
        let data = &block.inner.data;
        let mut entries = block.iter(self.comparator.clone());
        if !entries.seek(key, SeqNo::MAX) {
            return (versions, found);
        }
        for item in entries {
            let mut version = item.materialize(data);
            match self.comparator.compare(&version.key.user_key, key) {
                core::cmp::Ordering::Less => continue,
                core::cmp::Ordering::Greater => break,
                core::cmp::Ordering::Equal => {}
            }
            found = true;
            // Filtered before it is translated, as the table's reader takes a
            // version: a sum past `SeqNo::MAX` is above every snapshot.
            if let Some(global) = version.key.seqno.checked_add(global_seqno)
                && crate::range::seqno_filter(global, seqno)
            {
                version.key.seqno = global;
                versions.push(version);
            }
        }
        (versions, found)
    }

    /// The entries of the block `handle` names whose local seqno lies in
    /// `window`, with their global seqnos, appended to `out`.
    fn collect_seqno_range(
        &self,
        handle: &KeyedBlockHandle,
        (local_target, local_end): (SeqNo, SeqNo),
        block_skip: bool,
        out: &mut Vec<InternalValue>,
    ) -> crate::Result<()> {
        let global_seqno = self.global_seqno();

        // Tight-space restriction: a block whose last key is below the bound
        // sits entirely in the punched-out (zeroed) prefix — never read it.
        // The block straddling the bound is intact (punch starts at its
        // offset) and is filtered per entry in the loop below.
        if let Some(bound) = &self.1
            && self.comparator.compare(handle.end_key(), bound) == core::cmp::Ordering::Less
        {
            return Ok(());
        }

        // Block-skip: look this block's seqno bounds up in the parallel
        // `seqno_bounds` section (keyed by file offset). If its (local) min
        // exceeds the upper bound, or its (local) max is below the target, it
        // cannot reference a qualifying record — skip the data-block read.
        // Bounds live in the section, NOT inline in the index entry, so a
        // point read never pays for them. Disabled in paranoid full-scan
        // mode (`block_skip == false`); absent for a table written without
        // the section → no skip, full filter (correct regardless).
        if block_skip
            && let Some((seqno_min, seqno_max)) =
                self.seqno_bounds.bounds_for(handle.as_ref().offset().0)
            && (seqno_max < local_target || seqno_min > local_end)
        {
            return Ok(());
        }

        // A wholly-deleted columnar block carries no keys; skip it.
        let Some(block) = self.load_data_block(handle.as_ref(), &LookupFd::default())? else {
            return Ok(());
        };
        let data = &block.inner.data;
        for item in block.iter(self.comparator.clone()) {
            let mut value = item.materialize(data);
            // Drop entries below the restriction bound in the straddling
            // block (their authoritative copy lives in the superseding
            // output table).
            if let Some(bound) = &self.1
                && self.comparator.compare(&value.key.user_key, bound) == core::cmp::Ordering::Less
            {
                continue;
            }
            if value.key.seqno >= local_target && value.key.seqno <= local_end {
                value.key.seqno = apply_global_seqno(value.key.seqno, global_seqno);
                out.push(value);
            }
        }
        Ok(())
    }

    /// Creates a ranged iterator over the `Table`.
    ///
    /// # Errors
    ///
    /// Will return `Err` if an IO error occurs.
    #[must_use]
    #[doc(hidden)]
    pub fn range<R: RangeBounds<UserKey> + Send>(
        &self,
        range: R,
    ) -> impl DoubleEndedIterator<Item = crate::Result<InternalValue>> + Send + use<R> {
        self.range_iter(range)
    }

    /// Builds the positional delete mask for a columnar iterator from the
    /// on-open cache: the delete-bitmap plus each block's first global row
    /// position. `None` when the segment has no deletes, so a delete-free table
    /// pays nothing. Cheap (two `Arc` clones); the cumulative row counts were
    /// computed once on open.
    fn build_delete_mask(&self) -> Option<iter::DeleteMask> {
        let block_start_rows = self.delete_block_starts.clone()?;
        Some(iter::DeleteMask {
            bitmap: self.delete_bitmap.clone(),
            block_start_rows,
        })
    }

    /// Like [`Self::range`] but returns the concrete [`iter::Iter`] reader.
    ///
    /// The seekable range pipeline holds the concrete type so it can re-position
    /// the reader in place via [`Self::reseek_range`] instead of rebuilding it.
    pub(crate) fn range_iter<R: RangeBounds<UserKey> + Send>(&self, range: R) -> iter::Iter {
        let index_iter = self.block_index.iter();

        let mut iter = Iter::new(
            self.global_id(),
            self.global_seqno(),
            self.path.clone(),
            index_iter,
            self.file_accessor.clone(),
            self.cache.clone(),
            self.metadata.data_block_compression,
            self.encryption.clone(),
            self.metadata.ecc_params,
            self.heal_hints.get().cloned(),
            self.metadata.kv_checksum_algo.is_some(),
            self.metadata.columnar,
            self.build_delete_mask(),
            #[cfg(zstd_any)]
            self.zstd_dictionary.clone(),
            self.comparator.clone(),
            #[cfg(feature = "zstd")]
            self.block_layout.clone(),
            #[cfg(feature = "zstd")]
            self.metadata.data_block_restart_interval,
            #[cfg(feature = "metrics")]
            self.metrics.clone(),
        )
        .with_read_budget(self.read_budget());

        match range.start_bound() {
            Bound::Included(key) => iter.set_lower_bound(iter::Bound::Included(key.clone())),
            Bound::Excluded(key) => iter.set_lower_bound(iter::Bound::Excluded(key.clone())),
            Bound::Unbounded => {}
        }

        // Tight-space restriction: raise the scan's lower bound up to `bound`
        // when this version restricts the table, so the iterator never walks
        // index entries pointing into the punched-out (zeroed) prefix below
        // `bound`. Only raises (never lowers) the requested start: a request
        // already at or above `bound` is left untouched.
        if let Some(bound) = &self.1 {
            let raise = match range.start_bound() {
                Bound::Included(key) | Bound::Excluded(key) => {
                    self.comparator.compare(bound, key) == core::cmp::Ordering::Greater
                }
                Bound::Unbounded => true,
            };
            if raise {
                iter.set_lower_bound(iter::Bound::Included(bound.clone()));
            }
        }

        match range.end_bound() {
            Bound::Included(key) => iter.set_upper_bound(iter::Bound::Included(key.clone())),
            Bound::Excluded(key) => iter.set_upper_bound(iter::Bound::Excluded(key.clone())),
            Bound::Unbounded => {}
        }

        iter
    }

    /// Re-position an existing [`iter::Iter`] (produced by [`Self::range`] on
    /// this same table) to a fresh `range`, reusing its owned index iterator and
    /// `Arc` handles instead of constructing a new reader.
    ///
    /// Applies the exact same bound translation as [`Self::range`] (including the
    /// tight-space lower-bound raise), so the re-seeked iterator yields the same
    /// entries a freshly-built `self.range(range)` would. Used by the seekable
    /// range pipeline to move leaf cursors without per-seek allocation.
    #[doc(hidden)]
    pub fn reseek_range<R: RangeBounds<UserKey> + Send>(&self, iter: &mut iter::Iter, range: R) {
        iter.reset_for_reseek();

        match range.start_bound() {
            Bound::Included(key) => iter.set_lower_bound(iter::Bound::Included(key.clone())),
            Bound::Excluded(key) => iter.set_lower_bound(iter::Bound::Excluded(key.clone())),
            Bound::Unbounded => {}
        }

        // Mirror `range()`'s tight-space restriction: raise the scan's lower
        // bound up to `bound` when this version restricts the table.
        if let Some(bound) = &self.1 {
            let raise = match range.start_bound() {
                Bound::Included(key) | Bound::Excluded(key) => {
                    self.comparator.compare(bound, key) == core::cmp::Ordering::Greater
                }
                Bound::Unbounded => true,
            };
            if raise {
                iter.set_lower_bound(iter::Bound::Included(bound.clone()));
            }
        }

        match range.end_bound() {
            Bound::Included(key) => iter.set_upper_bound(iter::Bound::Included(key.clone())),
            Bound::Excluded(key) => iter.set_upper_bound(iter::Bound::Excluded(key.clone())),
            Bound::Unbounded => {}
        }
    }

    fn read_tli(
        regions: &ParsedRegions,
        file: &dyn FsFile,
        table_id: TableId,
        compression: CompressionType,
        encryption: Option<&dyn crate::encryption::EncryptionProvider>,
        ecc: Option<crate::table::block::EccParams>,
    ) -> crate::Result<IndexBlock> {
        // Tail copy first (preferred): if a fresh `tli_tail` exists it
        // landed after the head `tli`, so it's the most-recently
        // fsynced copy. On any decode / decrypt / checksum failure
        // fall back to the head `tli` if present.
        //
        // Both copies encode the same handles list (the writer hands
        // a single `tli_bytes` buffer to both sites) and both are
        // written under the same `CompressionType`
        // (`metadata.index_block_compression`); the block header does
        // not record a compression tag, so this single value decodes
        // either copy. Encryption nonce differs per copy (fresh per
        // `Block::write_into`) and the ciphertext therefore differs
        // byte-for-byte, but both decrypt to the same plaintext
        // IndexBlock.
        //
        // Tables written before the TLI-mirror change have no
        // `tli_tail`; reader falls straight through to the head copy.
        if let Some(tail_handle) = regions.tli_tail {
            log::trace!("Reading TLI tail mirror, with tli_tail_ptr={tail_handle:?}");
            match Self::read_tli_at(file, tail_handle, table_id, compression, encryption, ecc) {
                Ok(idx) => return Ok(idx),
                Err(tail_err) => {
                    log::warn!(
                        "TLI tail mirror unreadable ({tail_err}); falling back to TLI head copy at {:?}",
                        regions.tli,
                    );
                    // Match the meta-mirror pattern: when BOTH
                    // copies fail, surface the original `tail_err`
                    // (callers care about the authoritative /
                    // preferred copy's failure mode). The head
                    // failure goes to the log so it's not silently
                    // dropped from diagnostics.
                    log::trace!("Reading TLI head copy, with tli_ptr={:?}", regions.tli);
                    return match Self::read_tli_at(
                        file,
                        regions.tli,
                        table_id,
                        compression,
                        encryption,
                        ecc,
                    ) {
                        Ok(idx) => Ok(idx),
                        Err(head_err) => {
                            log::warn!(
                                "TLI head copy also unreadable ({head_err}); returning original tail error",
                            );
                            Err(tail_err)
                        }
                    };
                }
            }
        }

        log::trace!("Reading TLI head copy, with tli_ptr={:?}", regions.tli);
        Self::read_tli_at(file, regions.tli, table_id, compression, encryption, ecc)
    }

    fn read_tli_at(
        file: &dyn FsFile,
        handle: BlockHandle,
        table_id: TableId,
        compression: CompressionType,
        encryption: Option<&dyn crate::encryption::EncryptionProvider>,
        ecc: Option<crate::table::block::EccParams>,
    ) -> crate::Result<IndexBlock> {
        let block = Block::from_file(
            file,
            handle,
            crate::table::block::BlockIdentity {
                table_id,
                block_type: BlockType::Index,
                dict_id: 0,
                window_log: 0,
            },
            &{
                // Index blocks are SST blocks that omit the block_flags byte,
                // so ECC presence comes from the per-SST descriptor: upgrade
                // to the `*Ecc` transform when this table was written with
                // Page ECC. Identity without the feature.
                let t = crate::table::block::BlockTransform::from_parts(
                    compression,
                    encryption,
                    #[cfg(zstd_any)]
                    None,
                )?;
                if let Some(ecc) = ecc {
                    t.with_ecc(ecc)
                } else {
                    t
                }
            },
        )?;

        if block.header.block_type != BlockType::Index {
            return Err(crate::Error::InvalidTag((
                "BlockType",
                block.header.block_type.into(),
            )));
        }

        Ok(IndexBlock::new(block))
    }

    /// Tries to recover a table from a file.
    ///
    /// A corrupt delete-bitmap fails recovery rather than silently resurrecting
    /// deleted rows; see [`Self::recover_inner`] for the salvage variant that
    /// degrades to "all rows live" instead.
    pub fn recover(params: RecoverParams) -> crate::Result<Self> {
        Self::recover_inner(params, RecoveryMode::Live)
    }

    /// Recovers a table, optionally in **salvage mode** (see [`RecoveryMode`]).
    ///
    /// In salvage mode a corrupt or truncated delete-bitmap degrades to empty
    /// ("all rows live, pending recompaction") and a delete-bitmap with an
    /// unreadable zone map is ignored rather than erroring, so a columnar
    /// segment with a damaged sidecar still opens and its data blocks can be
    /// recovered. Normal recovery ([`RecoveryMode::Live`]) fails closed on
    /// both, to avoid resurrecting deleted rows. Used by [`crate::salvage`].
    #[expect(clippy::too_many_lines, reason = "recovery is inherently complex")]
    pub(crate) fn recover_inner(params: RecoverParams, mode: RecoveryMode) -> crate::Result<Self> {
        use core::sync::atomic::AtomicBool;
        use meta::ParsedMeta;
        use regions::ParsedRegions;

        let RecoverParams {
            file_path,
            checksum,
            global_seqno,
            recency,
            tree_id,
            table_id,
            cache,
            descriptor_table,
            fs,
            pin_filter,
            pin_index,
            encryption,
            #[cfg(zstd_any)]
            zstd_dictionaries,
            comparator,
            prefix_extractor,
            #[cfg(feature = "metrics")]
            metrics,
        } = params;

        let salvage = matches!(mode, RecoveryMode::Salvage { .. });

        log::debug!("Recovering table from file {}", file_path.display());
        let mut file = fs.open(&file_path, &FsOpenOptions::new().read(true))?;
        let file_path = Arc::new(file_path);
        let file_len = file.metadata()?.len;

        #[cfg(feature = "metrics")]
        metrics
            .table_file_opened_uncached
            .fetch_add(1, core::sync::atomic::Ordering::Relaxed);

        let trailer = crate::sfa::Reader::from_reader(&mut file)?;
        let regions = ParsedRegions::parse_from_toc(trailer.toc())?;

        log::trace!("Reading meta block, with meta_ptr={:?}", regions.metadata);
        // The expected-id cross-check rejects a swapped / wrong-id file in a
        // LIVE tree, where the manifest / file name is the durable identity.
        // A salvage open with a caller-known id (repair — from the file name)
        // keeps the check so a forged TAIL id falls back to the MID mirror; a
        // STANDALONE salvage reader has no out-of-band id, so the SOURCE's
        // own stored id is the identity and the check is skipped (None). An
        // ENCRYPTED open always passes the caller's id — the meta block's AAD
        // binds it, so decryption itself requires the right id.
        let expected_id = match mode {
            RecoveryMode::Live => Some(table_id),
            RecoveryMode::Salvage { expected_id, .. } => {
                if encryption.is_some() {
                    Some(table_id)
                } else {
                    expected_id
                }
            }
        };
        // Salvage arbitration may invert the mirror order (see
        // `RecoveryMode::Salvage::prefer_mid_meta`); live opens always load
        // tail-first.
        let prefer_mid_meta = matches!(
            mode,
            RecoveryMode::Salvage {
                prefer_mid_meta: true,
                ..
            }
        );
        // TAIL first (authoritative copy by convention; physically
        // identical content to MID — same `file_size`, same
        // `created_at`, same KV map — the only difference is which
        // SFA section is loaded). On any decode/decrypt/checksum
        // failure fall back to the MID copy if present. Under salvage
        // arbitration (`prefer_mid_meta`) the order is inverted: MID
        // first, tail as the fallback.
        let (first_handle, first_name, second, second_name) =
            if prefer_mid_meta && let Some(mid_handle) = regions.metadata_mid {
                (mid_handle, "MID", Some(regions.metadata), "TAIL")
            } else {
                (regions.metadata, "TAIL", regions.metadata_mid, "MID")
            };
        let metadata = match ParsedMeta::load_with_handle(
            &*file,
            &first_handle,
            expected_id,
            encryption.as_deref(),
        ) {
            Ok(m) => m,
            Err(first_err) => {
                if let Some(second_handle) = second {
                    log::warn!(
                        "{first_name} meta block unreadable for {} ({first_err}); \
                         falling back to {second_name} copy",
                        file_path.display(),
                    );
                    // Match the PR contract: when BOTH copies fail,
                    // surface the FIRST error (callers care about the
                    // preferred copy's failure mode). The fallback
                    // failure goes to the log so it's not silently
                    // dropped from diagnostics.
                    // MID and TAIL are byte-identical: same `file_size`
                    // (= `*self.meta.file_pos`, only bumped inside
                    // `spill_block`, unchanged between the two writes),
                    // same `created_at` (snapshotted once in
                    // `finish()`), same KV map. Either payload is usable
                    // directly — no sentinel patching, no
                    // `std::fs::metadata` (which would also bypass the
                    // pluggable `Fs` backend).
                    match ParsedMeta::load_with_handle(
                        &*file,
                        &second_handle,
                        expected_id,
                        encryption.as_deref(),
                    ) {
                        Ok(m) => m,
                        Err(second_err) => {
                            log::warn!(
                                "{second_name} meta block also unreadable for {}: {second_err}; \
                                 returning original {first_name} error",
                                file_path.display(),
                            );
                            return Err(first_err);
                        }
                    }
                } else {
                    return Err(first_err);
                }
            }
        };

        // Refuse a table whose BuRR sections are in the superseded wire format,
        // here rather than on the first probe. The filter and the retrieval
        // locator share `FORMAT_VERSION`, so both are covered by the one stamp
        // and both are checked by the one condition — a table converted on the
        // filter side alone would otherwise open and then fail inside a point
        // read on its stale locator.
        //
        // Gated on a section actually being present: a table with no filter and
        // no locator has nothing that could be misread, and refusing it would
        // turn a harmless absence into an outage.
        //
        // NOT exempted in salvage mode, though salvage does re-derive every one
        // of these sections from the recovered entries and so could in
        // principle re-emit a legacy table in the current format. Exempting it
        // here alone would not produce that migration: `verify_keep_decision`
        // grades a table that RECOVERED by its block-verify verdict, and a
        // healthy legacy table verdicts Clean and is KEPT verbatim — so the
        // rebuilt manifest would reference unconverted tables, repair would
        // report success, and the next ordinary open would refuse again. A
        // repair that reports success and leaves an unopenable store is worse
        // than one that refuses. Turning salvage into a real migration means a
        // keep-decision reason that forces the rewrite, which is the offline
        // converter's job and is tracked with it.
        {
            let has_burr_section = regions.filter.is_some()
                || regions.filter_tli.is_some()
                || regions.locator.is_some();
            let expected = crate::table::filter::ribbon::burr::FORMAT_VERSION;
            if has_burr_section && metadata.filter_format != Some(expected) {
                return Err(crate::Error::UnsupportedFormat {
                    part: crate::FormatPart::Filter,
                    found: metadata.filter_format,
                    expected,
                });
            }
        }

        // The same refusal for a columnar table's row groups, for the same
        // reasons and with the same salvage-mode reasoning as above. It
        // matters more here, not less: a row group read under the wrong
        // layout fails as a block-role mismatch, which the recovery paths
        // grade as DAMAGE, so without this a repair would drop every columnar
        // table in a store awaiting conversion. Gated on the table being
        // columnar: a row-major table has no row groups to misread. A build
        // without the `columnar` feature reads no columnar layout at all and
        // reports that on the first read, which is a different remedy from
        // conversion, so the refusal is not raised there.
        #[cfg(feature = "columnar")]
        if metadata.columnar
            && metadata.columnar_format != Some(crate::table::meta::COLUMNAR_FORMAT_VERSION)
        {
            return Err(crate::Error::UnsupportedFormat {
                part: crate::FormatPart::Columnar,
                found: metadata.columnar_format,
                expected: crate::table::meta::COLUMNAR_FORMAT_VERSION,
            });
        }

        // Resolve the dictionary this table was written against, by the id the
        // table itself records. Fail-fast: a tree that does not hold that id
        // cannot decompress a single data block, so say so here rather than on
        // the first read. `got` reports what the tree DOES hold when it holds
        // exactly one, which is the common misconfiguration (the wrong
        // dictionary supplied) and the only case where naming one is useful.
        #[cfg(zstd_any)]
        let zstd_dictionary =
            if let CompressionType::ZstdDict { dict_id, .. } = metadata.data_block_compression {
                let Some(dict) = zstd_dictionaries.get(dict_id) else {
                    return Err(crate::Error::ZstdDictMismatch {
                        expected: dict_id,
                        got: (zstd_dictionaries.len() == 1)
                            .then(|| zstd_dictionaries.ids().next())
                            .flatten(),
                    });
                };
                Some(dict.clone())
            } else {
                // Not dictionary-compressed: carrying a dictionary would be a
                // handle nothing reads.
                None
            };

        let file_handle: Arc<dyn FsFile> = Arc::from(file);

        let file_accessor = if let Some(dt) = descriptor_table {
            FileAccessor::DescriptorTable {
                table: dt,
                fs: fs.clone(),
            }
        } else {
            FileAccessor::File(file_handle.clone())
        };

        let block_index = if regions.index.is_some() {
            log::trace!(
                "Creating partitioned block index, with tli_ptr={:?}",
                regions.tli,
            );

            let block = Self::read_tli(
                &regions,
                file_handle.as_ref(),
                metadata.id,
                metadata.index_block_compression,
                encryption.as_deref(),
                metadata.ecc_params,
            )?;

            BlockIndexImpl::TwoLevel(TwoLevelBlockIndex {
                top_level_index: block,
                cache: cache.clone(),
                compression: metadata.index_block_compression,
                path: Arc::clone(&file_path),
                file_accessor: file_accessor.clone(),
                table_id: (tree_id, metadata.id).into(),
                encryption: encryption.clone(),
                ecc: metadata.ecc_params,
                comparator: comparator.clone(),

                #[cfg(feature = "metrics")]
                metrics: metrics.clone(),
            })
        } else if pin_index {
            log::trace!(
                "Creating pinned, full block index, with tli_ptr={:?}",
                regions.tli,
            );

            let block = Self::read_tli(
                &regions,
                file_handle.as_ref(),
                metadata.id,
                metadata.index_block_compression,
                encryption.as_deref(),
                metadata.ecc_params,
            )?;
            BlockIndexImpl::Full(FullBlockIndex::new(block, comparator.clone())?)
        } else {
            log::trace!("Creating volatile, full block index");

            BlockIndexImpl::VolatileFull(VolatileBlockIndex {
                cache: cache.clone(),
                compression: metadata.index_block_compression,
                file_accessor: file_accessor.clone(),
                handle: regions.tli,
                path: Arc::clone(&file_path),
                table_id: (tree_id, metadata.id).into(),
                encryption: encryption.clone(),
                ecc: metadata.ecc_params,
                comparator: comparator.clone(),

                #[cfg(feature = "metrics")]
                metrics: metrics.clone(),
            })
        };

        // Set when the salvage-mode open DEGRADES a rebuildable side section
        // (filter / filter_tli, seqno bounds, zone map, locator) because its
        // block did not decode as the claimed type. Salvage re-derives every
        // such section from the recovered entries, so a section that is present
        // but does not decode may be a `range_tombstones` / `delete_bitmap`
        // relabeled to a rebuildable name and re-roled — which salvage would
        // discard, resurrecting the suppressed rows. This is a purely
        // STRUCTURAL signal (each decode reads its own section's bytes,
        // independent of the data blocks), so a corrupt DATA block does not
        // trip it. `block_layout` is excluded: it fails the open outright, so a
        // relabel to it is rejected by the failed recovery rather than
        // salvaged.
        let mut rebuildable_section_degraded = false;

        let pinned_filter_index = if let Some(filter_tli_handle) = regions.filter_tli {
            let load = || -> crate::Result<IndexBlock> {
                let block = Block::from_file(
                    file_handle.as_ref(),
                    filter_tli_handle,
                    crate::table::block::BlockIdentity {
                        table_id: metadata.id,
                        block_type: BlockType::Index,
                        dict_id: 0,
                        window_log: 0,
                    },
                    &{
                        // Filter TLI is an Index (SST) block: no block_flags byte,
                        // so ECC presence comes from the per-SST descriptor.
                        let t = crate::table::block::BlockTransform::from_parts(
                            metadata.index_block_compression,
                            encryption.as_deref(),
                            #[cfg(zstd_any)]
                            None,
                        )?;
                        if let Some(ecc) = metadata.ecc_params {
                            t.with_ecc(ecc)
                        } else {
                            t
                        }
                    },
                )?;
                if block.header.block_type != BlockType::Index {
                    return Err(crate::Error::InvalidTag((
                        "BlockType",
                        block.header.block_type.into(),
                    )));
                }
                let idx = IndexBlock::new(block);
                // Validate filter index trailer eagerly (same as FullBlockIndex::new)
                // so later iter() calls cannot panic on malformed blocks.
                idx.try_iter(comparator.clone())?;
                Ok(idx)
            };
            match load() {
                Ok(idx) => Some(idx),
                // Only an ENVIRONMENTAL read propagates so the caller can retry
                // (or supply the right key): degradation is not free — it sets
                // `rebuildable_section_degraded`, which fails salvage closed and
                // costs the whole recoverable table. A failure on the DATA (bad
                // sector, truncation) degrades under salvage like the
                // seqno-bounds / zone-map / delete-bitmap / locator loaders.
                Err(e) if e.is_environmental() => return Err(e),
                // Salvage never consults the source's filter — the
                // destination writer rebuilds it from the recovered keys —
                // so a STRUCTURALLY or PERSISTENTLY unreadable filter index must not
                // cost the recoverable data (a live open still fails closed).
                Err(e) if salvage => {
                    log::warn!(
                        "filter index for table {:?} is unreadable ({e}); salvaging \
                         without it (the recovered copy re-derives its filter)",
                        metadata.id
                    );
                    rebuildable_section_degraded = true;
                    None
                }
                Err(e) => return Err(e),
            }
        } else {
            None
        };

        // TODO: FilterBlock newtype
        //
        // In SALVAGE mode the source filter is never PINNED (the destination
        // rebuilds it from the recovered keys), but a present full filter must
        // still be PROBED even when `pin_filter` is false: a delete_bitmap
        // renamed and re-roled to a `filter` (an empty sentinel, or a
        // checksum/parity-valid but structurally broken BuRR payload) launders
        // the deletion metadata. Loading and parsing it here trips the
        // rebuildable-section degradation, which the salvage guard turns into a
        // fail-closed refusal. A live open (pin_filter, not salvage) keeps
        // its exact prior behaviour.
        let pinned_filter_block = if pinned_filter_index.is_none() && (pin_filter || salvage) {
            let loaded = regions
                .filter
                .map(|filter_handle| {
                    log::debug!(
                        "Loading and pinning filter block, with filter_ptr={filter_handle:?}"
                    );

                    let block = Block::from_file(
                        file_handle.as_ref(),
                        filter_handle,
                        crate::table::block::BlockIdentity {
                            table_id: metadata.id,
                            block_type: BlockType::Filter,
                            dict_id: 0,
                            window_log: 0,
                        },
                        // Filter blocks are never written compressed, so the
                        // transform is Plain or Encrypted depending on whether
                        // the table is keyed. Filter is an SST block (no
                        // block_flags byte), so ECC presence comes from the
                        // per-SST descriptor: upgrade to `*Ecc` when page_ecc.
                        &{
                            let t = match encryption.as_deref() {
                                Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                                None => crate::table::block::BlockTransform::PLAIN,
                            };
                            if let Some(ecc) = metadata.ecc_params {
                                t.with_ecc(ecc)
                            } else {
                                t
                            }
                        },
                    )
                    .and_then(|block| {
                        if block.header.block_type == BlockType::Filter {
                            Ok(block)
                        } else {
                            Err(crate::Error::InvalidTag((
                                "BlockType",
                                block.header.block_type.into(),
                            )))
                        }
                    })?;

                    Ok::<_, crate::Error>(FilterBlock::new(block))
                })
                .transpose();
            match loaded {
                Ok(Some(filter)) => {
                    // A present full filter that decodes to the empty sentinel,
                    // or whose BuRR payload does not parse, is not something the
                    // writer ever emits (it omits the section when filtering is
                    // disabled). In salvage mode treat it as a degraded
                    // rebuildable section so a relabeled delete_bitmap cannot
                    // pass as a filter-less table and resurrect deleted rows.
                    if salvage && (filter.is_empty() || filter.maybe_contains_hash(0).is_err()) {
                        log::warn!(
                            "filter block for table {:?} is empty or unparsable; salvaging \
                             as a degraded rebuildable section",
                            metadata.id
                        );
                        rebuildable_section_degraded = true;
                    }
                    // Never PIN in salvage (the destination rebuilds the
                    // filter); a live open with pin_filter keeps it.
                    if pin_filter { Some(filter) } else { None }
                }
                Ok(None) => None,
                // An InvalidTag here is STRUCTURAL, not corruption: the block
                // loaded and verified its own PAYLOAD checksum, it is just the
                // WRONG role. `Header::checksum` covers the payload, not the
                // header, so a `block_type` byte that flips to another valid SST
                // discriminant does NOT fail that checksum — it reaches this
                // role check exactly like a TOC rename (a delete_bitmap renamed
                // to `filter` without re-roling its header). Both are a valid
                // block of the wrong name (the relabel signature), so degrade
                // like the empty / unparsable payload above and fail closed.
                //
                // Any OTHER load failure (payload checksum / AEAD) is GENUINE
                // bit-rot: a re-stamped relabel produces a checksum-VALID block,
                // so a broken payload checksum is real corruption, rebuilt from
                // the recovered keys. A delete-free table with a bit-rotted
                // filter must auto-repair, not fail closed, so salvaging
                // continues without degrading.
                Err(e) if salvage => {
                    if matches!(e, crate::Error::InvalidTag(_)) {
                        log::warn!(
                            "filter block for table {:?} has the wrong role ({e}); salvaging \
                             as a degraded rebuildable section",
                            metadata.id
                        );
                        rebuildable_section_degraded = true;
                    } else {
                        log::warn!(
                            "filter block for table {:?} is unreadable ({e}); salvaging \
                             without it (the recovered copy re-derives its filter)",
                            metadata.id
                        );
                    }
                    None
                }
                Err(e) => return Err(e),
            }
        } else {
            None
        };

        // Load range tombstones (if present)
        let range_tombstones = if let Some(rt_handle) = regions.range_tombstones {
            log::trace!("Loading range tombstone block, with rt_ptr={rt_handle:?}");
            let block = Block::from_file(
                file_handle.as_ref(),
                rt_handle,
                crate::table::block::BlockIdentity {
                    table_id: metadata.id,
                    block_type: BlockType::RangeTombstone,
                    dict_id: 0,
                    window_log: 0,
                },
                // Range-tombstone blocks are always uncompressed; the
                // transform is Plain or Encrypted depending on whether the
                // table is keyed. RangeTombstone is an SST block (no
                // block_flags byte), so ECC presence comes from the per-SST
                // descriptor: upgrade to `*Ecc` when page_ecc.
                &{
                    let t = match encryption.as_deref() {
                        Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                        None => crate::table::block::BlockTransform::PLAIN,
                    };
                    if let Some(ecc) = metadata.ecc_params {
                        t.with_ecc(ecc)
                    } else {
                        t
                    }
                },
            )?;

            if block.header.block_type != BlockType::RangeTombstone {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    block.header.block_type.into(),
                )));
            }

            let mut rts = Self::decode_range_tombstones(&block, comparator.as_ref())?;
            // Sort range tombstones by (start asc, seqno desc) using the
            // user comparator so the order matches the tree's key ordering.
            // The seqno-desc tiebreaker ensures higher-seqno RTs are checked
            // first when multiple share the same start key.
            let cmp = &comparator;
            rts.sort_unstable_by(|a, b| {
                cmp.compare(&a.start, &b.start)
                    .then_with(|| b.seqno.cmp(&a.seqno))
            });
            rts
        } else {
            Vec::new()
        };
        let range_tombstones_end = range_tombstones
            .iter()
            .map(|rt| &rt.end)
            .max_by(|a, b| comparator.compare(a, b))
            .cloned();

        // Load the optional inner-block layout section (present only when the
        // table has data blocks that split into >= 2 inner zstd blocks). Mirrors
        // the range-tombstone loader: same Plain/Encrypted (+ optional ECC)
        // transform the writer used for this uncompressed meta section.
        let block_layout = if let Some(bl_handle) = regions.block_layout {
            let block = Block::from_file(
                file_handle.as_ref(),
                bl_handle,
                crate::table::block::BlockIdentity {
                    table_id: metadata.id,
                    block_type: BlockType::BlockLayout,
                    dict_id: 0,
                    window_log: 0,
                },
                &{
                    let t = match encryption.as_deref() {
                        Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                        None => crate::table::block::BlockTransform::PLAIN,
                    };
                    if let Some(ecc) = metadata.ecc_params {
                        t.with_ecc(ecc)
                    } else {
                        t
                    }
                },
            )?;

            if block.header.block_type != BlockType::BlockLayout {
                return Err(crate::Error::InvalidTag((
                    "BlockType",
                    block.header.block_type.into(),
                )));
            }

            let map = crate::table::block_layout::BlockLayoutMap::decode(&block.data)?;
            log::trace!(
                "Loaded block-layout index with {} multi-inner-block entries",
                map.len(),
            );
            map
        } else {
            crate::table::block_layout::BlockLayoutMap::default()
        };

        // Load the optional seqno-bounds section (parallel to the index; powers
        // the scan_since_seqno block-skip). Absent unless seqno_in_index was on.
        //
        // Best-effort, like the zone map below: the seqno-bounds section is
        // derived, non-authoritative metadata, so a corrupt / unreadable section
        // disables the block-skip (falling back to a full per-entry filter)
        // rather than failing the whole table open.
        let seqno_bounds = if let Some(sb_handle) = regions.seqno_bounds {
            let load = || -> crate::Result<crate::table::seqno_bounds::SeqnoBoundsMap> {
                let block = Block::from_file(
                    file_handle.as_ref(),
                    sb_handle,
                    crate::table::block::BlockIdentity {
                        table_id: metadata.id,
                        block_type: BlockType::SeqnoBounds,
                        dict_id: 0,
                        window_log: 0,
                    },
                    &{
                        let t = match encryption.as_deref() {
                            Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                            None => crate::table::block::BlockTransform::PLAIN,
                        };
                        if let Some(ecc) = metadata.ecc_params {
                            t.with_ecc(ecc)
                        } else {
                            t
                        }
                    },
                )?;
                if block.header.block_type != BlockType::SeqnoBounds {
                    return Err(crate::Error::InvalidTag((
                        "BlockType",
                        block.header.block_type.into(),
                    )));
                }
                crate::table::seqno_bounds::SeqnoBoundsMap::decode(&block.data)
            };
            match load() {
                Ok(m) => m,
                // Only an ENVIRONMENTAL read propagates so the caller can retry
                // (or supply the right key); a failure on the DATA (bad sector,
                // truncation) degrades this rebuildable, derived section to an
                // empty map (seqno block-skip disabled) rather than failing the
                // whole open — turning an optimization's bit-rot into a hard
                // availability loss would be wrong.
                Err(e) if e.is_environmental() => return Err(e),
                Err(e) => {
                    log::warn!(
                        "seqno-bounds section for table {:?} is unreadable ({e}); disabling seqno block-skip",
                        metadata.id
                    );
                    rebuildable_section_degraded = true;
                    crate::table::seqno_bounds::SeqnoBoundsMap::default()
                }
            }
        } else {
            crate::table::seqno_bounds::SeqnoBoundsMap::default()
        };
        if !seqno_bounds.is_empty() {
            log::trace!("Loaded {} seqno-bounds entries", seqno_bounds.len());
        }

        // Load the optional zone-map section (parallel to the index; powers the
        // predicate-based block-skip). Absent unless the zone-map policy was on.
        //
        // Best-effort: the zone map is DERIVED, non-authoritative metadata. A
        // corrupt or unreadable section disables block-skip for this table (an
        // empty map) rather than failing the whole `Table::recover` — turning an
        // optimization's bit-rot into a hard availability loss would be wrong.
        let zone_map = if let Some(zm_handle) = regions.zone_map {
            let load = || -> crate::Result<crate::table::zone_map::ZoneMap> {
                let block = Block::from_file(
                    file_handle.as_ref(),
                    zm_handle,
                    crate::table::block::BlockIdentity {
                        table_id: metadata.id,
                        block_type: BlockType::ZoneMap,
                        dict_id: 0,
                        window_log: 0,
                    },
                    &{
                        let t = match encryption.as_deref() {
                            Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                            None => crate::table::block::BlockTransform::PLAIN,
                        };
                        if let Some(ecc) = metadata.ecc_params {
                            t.with_ecc(ecc)
                        } else {
                            t
                        }
                    },
                )?;
                if block.header.block_type != BlockType::ZoneMap {
                    return Err(crate::Error::InvalidTag((
                        "BlockType",
                        block.header.block_type.into(),
                    )));
                }
                crate::table::zone_map::ZoneMap::decode(&block.data)
            };
            match load() {
                Ok(m) => m,
                // Only an ENVIRONMENTAL read propagates so the caller can retry
                // (or supply the right key); a failure on the DATA degrades this
                // rebuildable, derived section to an empty map (block-skip
                // disabled) rather than failing the whole open.
                Err(e) if e.is_environmental() => return Err(e),
                Err(e) => {
                    log::warn!(
                        "zone-map section for table {:?} is unreadable ({e}); disabling block-skip",
                        metadata.id
                    );
                    rebuildable_section_degraded = true;
                    crate::table::zone_map::ZoneMap::default()
                }
            }
        } else {
            crate::table::zone_map::ZoneMap::default()
        };

        // Load the optional positional delete-bitmap section. Unlike the zone
        // map (a skip optimization that degrades safely to empty), the delete
        // bitmap is correctness data: silently dropping an unreadable one would
        // resurrect deleted rows, so normal recovery propagates the error and
        // fails. In salvage mode it degrades to empty ("all rows live, pending
        // recompaction") so the segment's data is still recoverable.
        let mut delete_bitmap_degraded = false;
        let mut delete_bitmap = if let Some(db_handle) = regions.delete_bitmap {
            let load = || -> crate::Result<crate::table::delete_bitmap::DeleteBitmap> {
                let block = Block::from_file(
                    file_handle.as_ref(),
                    db_handle,
                    crate::table::block::BlockIdentity {
                        table_id: metadata.id,
                        block_type: BlockType::DeleteBitmap,
                        dict_id: 0,
                        window_log: 0,
                    },
                    &{
                        let t = match encryption.as_deref() {
                            Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                            None => crate::table::block::BlockTransform::PLAIN,
                        };
                        if let Some(ecc) = metadata.ecc_params {
                            t.with_ecc(ecc)
                        } else {
                            t
                        }
                    },
                )?;
                if block.header.block_type != BlockType::DeleteBitmap {
                    return Err(crate::Error::InvalidTag((
                        "BlockType",
                        block.header.block_type.into(),
                    )));
                }
                crate::table::delete_bitmap::DeleteBitmap::decode(&block.data)
            };
            match load() {
                Ok(db) => db,
                // An ENVIRONMENTAL read propagates so the caller can retry (or
                // supply the right key): degrading the delete mask to "all rows
                // live" on a fixable fault would resurrect deleted rows in the
                // rebuilt table, or — under the default policy — cost the whole
                // table. A read failure on the DATA in salvage mode instead
                // falls through to the degradation branch below, where the
                // caller's `allow_delete_resurrection` opt-in is honored
                // downstream (a non-salvage open still fails closed via the
                // final arm).
                Err(e) if e.is_environmental() => return Err(e),
                Err(e) if salvage => {
                    log::warn!(
                        "delete-bitmap for table {:?} is unreadable ({e}); salvaging all rows as live",
                        metadata.id
                    );
                    delete_bitmap_degraded = true;
                    crate::table::delete_bitmap::DeleteBitmap::default()
                }
                Err(e) => return Err(e),
            }
        } else {
            crate::table::delete_bitmap::DeleteBitmap::default()
        };

        // A delete-bitmap is positional; masking it on the read path needs each
        // block's row count, which comes from the zone map. The writer co-writes
        // both, so a bitmap without a zone map is a malformed SST (masking would
        // resolve every block to position 0 and corrupt visibility).
        if !delete_bitmap.is_empty() && zone_map.is_empty() {
            if salvage {
                // Without a readable zone map the bitmap cannot be positioned
                // (every block would resolve to row 0), so ignore it: show all
                // rows live rather than masking against the wrong positions.
                log::warn!(
                    "salvage: delete-bitmap for table {:?} has no readable zone map; ignoring it (all rows live)",
                    metadata.id
                );
                delete_bitmap_degraded = true;
                delete_bitmap = crate::table::delete_bitmap::DeleteBitmap::default();
            } else {
                return Err(crate::Error::InvalidHeader(
                    "delete-bitmap SST is missing its zone map",
                ));
            }
        }

        // Cache each data block's first global row position (file offset -> start
        // row) once on open, so positional delete masking is O(1) per block on
        // every read instead of recomputing cumulative row counts. Empty when the
        // segment has no deletes.
        let delete_block_starts = if delete_bitmap.is_empty() {
            None
        } else {
            let mut map = crate::HashMap::default();
            let mut start: u32 = 0;
            // Part of opening the table, not a read a caller made, so it stays
            // out of the read counters like the locator walk below.
            let walk = block_index.iter().with_charge(ReadCharge::Maintenance);
            for keyed in walk {
                let keyed = keyed?;
                map.insert(keyed.offset().0, start);
                let row_count = zone_map
                    .columns_for(keyed.offset().0)
                    .and_then(|stats| stats.first())
                    .map_or(0, |col| col.row_count);
                start = start.wrapping_add(row_count);
            }
            Some(alloc::sync::Arc::new(map))
        };
        let delete_bitmap = alloc::sync::Arc::new(delete_bitmap);

        // Load the optional retrieval-ribbon locator section and pair it with an
        // ordinal → data-block-handle map (the index yields handles in key/write
        // order, which is the writer's block_id ordering). Only when the section
        // exists, so non-locator tables pay nothing.
        // Load the optional retrieval-ribbon locator as a BEST-EFFORT point-read
        // accelerator: any failure (corrupt locator section, unexpected block
        // type, or a corrupt sub-index block hit while walking the index to pair
        // locators with their data-block handles) degrades to `None` rather than
        // failing the table open. Point reads then use the sorted-index path,
        // which isolates a corrupt sub-index partition to its own keys — so
        // enabling the locator by default does NOT widen the blast radius of a
        // partitioned-index corruption from "one partition" back to "whole SST".
        let locator_block = match regions.locator {
            None => None,
            Some(loc_handle) => match Block::from_file(
                file_handle.as_ref(),
                loc_handle,
                crate::table::block::BlockIdentity {
                    table_id: metadata.id,
                    block_type: BlockType::Locator,
                    dict_id: 0,
                    window_log: 0,
                },
                &{
                    let t = match encryption.as_deref() {
                        Some(enc) => crate::table::block::BlockTransform::Encrypted(enc),
                        None => crate::table::block::BlockTransform::PLAIN,
                    };
                    if let Some(ecc) = metadata.ecc_params {
                        t.with_ecc(ecc)
                    } else {
                        t
                    }
                },
            ) {
                Ok(block) => Some(block),
                // An ENVIRONMENTAL locator read during salvage must PROPAGATE,
                // not degrade: `rebuildable_section_degraded` makes
                // `salvage_attempt` read a delete-free table as possibly hiding
                // deletion metadata and fail the whole SST
                // (`FeatureUnsupported`), dropping an otherwise-salvageable
                // table instead of surfacing a fault the caller can fix by
                // retrying or supplying the right key. Mirrors the zone-map /
                // seqno-bounds / delete-bitmap loaders. A non-salvage open keeps
                // the best-effort accelerator behavior (degrade to the
                // sorted-index path), so a fault there never fails the open.
                Err(e) if salvage && e.is_environmental() => return Err(e),
                Err(e) => {
                    log::warn!("retrieval-ribbon locator disabled: section load failed: {e:?}");
                    rebuildable_section_degraded = true;
                    None
                }
            },
        };
        let locator_index = locator_block.and_then(|block| {
            if block.header.block_type != BlockType::Locator {
                log::warn!(
                    "retrieval-ribbon locator disabled: unexpected block type {:?}",
                    block.header.block_type
                );
                rebuildable_section_degraded = true;
                return None;
            }
            let walk = block_index.iter().with_charge(ReadCharge::Maintenance);
            let blocks: Vec<BlockHandle> = walk
                .map(|r| r.map(|kbh| *kbh.as_ref()))
                .collect::<crate::Result<Vec<_>>>()
                .inspect_err(|e| {
                    log::warn!("retrieval-ribbon locator disabled: index walk failed: {e:?}");
                })
                .ok()?;
            log::trace!(
                "Loaded retrieval-ribbon locator over {} blocks",
                blocks.len()
            );
            Some(crate::table::locator::LoadedLocator::new(
                block.data, blocks,
            ))
        });

        log::debug!(
            "Recovered table #{} from {}",
            metadata.id,
            file_path.display(),
        );

        let l0_recency = recency.unwrap_or(metadata.recency);
        // Decided once, here: the tree's extractor is fixed for the life of
        // an open tree, and a filter indexes only the prefixes of the one it
        // was built under.
        let prefix_filter = prefix_extractor.filter(|current| {
            metadata.prefix_extractor.as_deref() == Some(current.name().as_bytes())
        });

        Ok(Self(
            Arc::new(Inner {
                path: file_path,
                tree_id,

                metadata,
                file_len,
                l0_recency,
                regions,

                cache,

                file_accessor,
                fs,

                block_index: Arc::new(block_index),

                pinned_filter_index,

                pinned_filter_block,

                prefix_filter,

                is_deleted: AtomicBool::default(),
                entry_durable: AtomicBool::default(),
                punch_on_drop: AtomicU64::new(u64::MAX),
                punched_through: once_cell::race::OnceBox::new(),

                checksum,
                global_seqno,

                comparator,

                #[cfg(feature = "metrics")]
                metrics,

                blob_links: once_cell::race::OnceBox::new(),
                read_count: AtomicU64::new(0),
                scan_count: AtomicU64::new(0),
                counting_since_secs: crate::time::unix_timestamp().as_secs(),
                last_access_secs: AtomicU64::new(0),
                probe_stats: once_cell::race::OnceBox::new(),
                range_tombstones,
                range_tombstones_end,
                block_layout,
                seqno_bounds,
                zone_map,
                delete_bitmap,
                delete_block_starts,
                delete_bitmap_degraded,
                rebuildable_section_degraded,
                locator_index,
                encryption,

                #[cfg(zstd_any)]
                zstd_dictionary,

                deletion_pause: once_cell::race::OnceBox::new(),

                #[cfg(feature = "std")]
                background_deleter: once_cell::race::OnceBox::new(),

                heal_hints: once_cell::race::OnceBox::new(),

                read_budget: once_cell::race::OnceBox::new(),

                #[cfg(all(feature = "std", feature = "page_ecc"))]
                heal_lock: once_cell::race::OnceBox::new(),
            }),
            None,
            None,
        ))
    }

    /// The tight-space restriction lower bound for this version's view of the
    /// table, or `None` on the common path. `Some(bound)` means the data below
    /// `bound` has been punched out and superseded by a merged output table, so
    /// reads route keys `< bound` elsewhere and clamp this table's scans to
    /// start at `bound` (its index still references the punched prefix).
    #[must_use]
    pub(crate) fn restrict_lower_bound(&self) -> Option<&UserKey> {
        self.1.as_ref()
    }

    /// True when `key` is below this version's tight-space restriction bound, so
    /// a read must miss here and fall through to the output table that
    /// superseded the punched-out prefix. Every point-read entry point
    /// ([`get`](Self::get), [`get_value`](Self::get_value),
    /// [`get_with_block`](Self::get_with_block)) and every batch read
    /// ([`batch_get`](Self::batch_get), the block planners and the staged
    /// read) consults this first.
    #[inline]
    pub(crate) fn is_below_restriction(&self, key: &[u8]) -> bool {
        self.1
            .as_ref()
            .is_some_and(|bound| self.comparator.compare(key, bound) == core::cmp::Ordering::Less)
    }

    /// Whether this version sees the table only from a tight-space
    /// restriction's bound up.
    pub(crate) fn is_restricted(&self) -> bool {
        self.1.is_some()
    }

    /// Returns a view of this table restricted to keys `>= lower`, for
    /// tight-space compaction. Shares the same `Arc<Inner>` (no file re-open,
    /// no extra handle, no [`Drop`] interaction), so the original and the
    /// restricted view are one physical SST seen by different versions. The
    /// caller punches the data blocks below `lower` only after this view is
    /// durably installed.
    #[must_use]
    pub(crate) fn with_restriction(&self, lower: UserKey) -> Self {
        Self(self.0.clone(), Some(lower), self.2)
    }

    /// Re-opens this table as a DISTINCT [`Inner`](inner::Inner) (its own file
    /// handle and fresh drop / punch-on-drop atomics) restricted to keys
    /// `>= lower`. Used by tight-space compaction so the PRIOR unrestricted view
    /// can drop — and punch its consumed prefix on that drop — independently of
    /// this restricted view, which keeps serving the suffix. Heavier than
    /// [`with_restriction`](Self::with_restriction) (re-reads the footer + block
    /// index), which is acceptable on the opt-in, emergency tight-space path.
    ///
    /// Opens with its own file handle (no shared descriptor table) so the old
    /// view's handle lifecycle stays fully separate.
    ///
    /// The suffix digest captured here must stay consistent with what the caller
    /// installs in the manifest, so the caller MUST hold this table's
    /// [`heal_lock_arc`](Self::heal_lock_arc) across BOTH this call and the
    /// version edit that installs the returned view. Without it a concurrent
    /// patrol heal could refresh a suffix block between the capture and the
    /// install, binding the restricted manifest to a pre-heal digest that the
    /// post-restriction patrol can neither match nor re-attribute (its
    /// attestation binds whole-file, not suffix, digests).
    ///
    /// # Errors
    ///
    /// Propagates any error from re-opening the SST file.
    // std-only: computes the suffix digest via `crate::repair` (file I/O) and is
    // reached only from tight-space compaction, which is itself std-gated.
    #[cfg(feature = "std")]
    pub(crate) fn reopen_restricted(&self, lower: UserKey) -> crate::Result<Self> {
        self.reopen_restricted_with(lower, None)
    }

    /// [`Self::reopen_restricted`], with the view's file kept in the given
    /// descriptor cache under the given tree id instead of a handle of its
    /// own: for a view no other view of this table shares that id with, such
    /// as the tables a repair holds.
    ///
    /// # Errors
    ///
    /// Propagates any error from re-opening the SST file.
    #[cfg(feature = "std")]
    pub(crate) fn reopen_restricted_with(
        &self,
        lower: UserKey,
        descriptors: Option<(Arc<crate::DescriptorTable>, crate::tree::inner::TreeId)>,
    ) -> crate::Result<Self> {
        // The restricted view's digest is the LIVE SUFFIX only: its
        // `[0, punch_offset)` prefix is hole-punched right after this view is
        // installed, so a whole-file digest (what `self.checksum()` holds) would
        // never match the punched file. Compute the suffix digest over the
        // CURRENT bytes NOW, while the file is still whole — the suffix is
        // untouched by the punch, and reading it fresh also folds in any in-place
        // heal that refreshed this table (so a tight-space swap installs the
        // healed suffix digest, never a stale pre-heal one).
        let punch_offset = self.punch_offset_for(&lower)?;
        let restricted_checksum = crate::Checksum::from_raw(
            crate::repair::compute_table_checksum_from(&*self.fs, &self.path, punch_offset)?,
        );
        let reopened = {
            let mut params = RecoverParams::new(
                (*self.path).clone(),
                restricted_checksum,
                self.metadata.id,
                self.fs.clone(),
                self.comparator.clone(),
                self.cache.clone(),
            );
            params.global_seqno = self.global_seqno;
            params.recency = Some(self.l0_recency);
            params.tree_id = self.tree_id;
            if let Some((cache, tree_id)) = descriptors {
                params.descriptor_table = Some(cache);
                params.tree_id = tree_id;
            }
            params.pin_filter = self.pinned_filter_size() > 0;
            params.pin_index = self.pinned_block_index_size() > 0;
            params.encryption.clone_from(&self.encryption);
            // The same file under the same meta: its filter indexes the
            // prefixes it did, of the extractor the table was opened under.
            params.prefix_extractor.clone_from(&self.prefix_filter);
            #[cfg(zstd_any)]
            {
                // Reopening THIS table, so the only dictionary the recovery can
                // need is the one it already resolved: the reopened view has
                // the same id in its metadata.
                params.zstd_dictionaries = self
                    .zstd_dictionary
                    .clone()
                    .map_or_else(crate::compression::ZstdDictionaries::new, |dict| {
                        crate::compression::ZstdDictionaries::new().with(dict)
                    });
            }
            #[cfg(feature = "metrics")]
            {
                params.metrics = self.metrics.clone();
            }
            Self::recover(params)?
        };
        // The reopened `Inner` is DISTINCT from this one, so it starts without
        // the tree-installed shared gates. Carry them forward, or the restricted
        // view would lose them: without the checkpoint deletion pause a
        // checkpoint could link healed bytes under a stale digest, and without
        // the shared heal lock two patrols could heal + reconcile the same SST
        // concurrently and leave a clean file mismatched with the manifest.
        if let Some(pause) = self.0.deletion_pause.get() {
            reopened.install_deletion_pause(Arc::clone(pause));
        }
        // How far the file is punched is the file's, not a view's.
        let punched = self
            .0
            .punched_through
            .get_or_init(|| Box::new(Arc::new(AtomicU64::new(0))));
        reopened
            .0
            .punched_through
            .get_or_init(|| Box::new(Arc::clone(punched)));
        #[cfg(all(feature = "std", feature = "page_ecc"))]
        reopened.install_heal_lock(self.heal_lock_arc());
        // The heal-hint sink too: a correctable read from the restricted view
        // must still queue this table for a healing recompaction, or
        // persistent bitrot keeps being corrected in memory on every read but
        // is never scheduled for a durable rewrite.
        if let Some(hints) = self.0.heal_hints.get() {
            reopened.install_heal_hints(Arc::clone(hints));
        }
        // And the columnar read budget, or the suffix's scans fall back to the
        // default budget whatever the tree was configured with.
        if let Some(budget) = self.0.read_budget.get() {
            reopened.0.read_budget.get_or_init(|| Box::new(*budget));
        }
        // The suffix keeps the share of the probe counts its data holds; the
        // slice outputs take the prefix's share from this view.
        if self.probe_stats().is_some() {
            let suffix = crate::table::probe_stats::share_of(
                self,
                (
                    core::ops::Bound::Included(lower.as_ref()),
                    core::ops::Bound::Unbounded,
                ),
            )?;
            reopened.0.probe_stats.get_or_init(Box::default).add(suffix);
        }
        Ok(reopened.with_restriction(lower))
    }

    /// Marks this view to punch `[0, offset)` when its last `Arc` drops (see
    /// [`Inner::punch_on_drop`](inner::Inner::punch_on_drop)). Set on the PRIOR
    /// unrestricted view once a tight-space slice has been installed, so the
    /// consumed prefix is reclaimed exactly when no reader can still see it.
    #[cfg_attr(
        not(feature = "std"),
        allow(
            dead_code,
            reason = "tight-space punch hook; its compaction consumer is std-gated, so unused under no_std"
        )
    )]
    pub(crate) fn mark_punch_on_drop(&self, offset: u64) {
        self.0
            .punch_on_drop
            .store(offset, core::sync::atomic::Ordering::Release);
    }

    /// A handle that tells whether this view's file is still held: its
    /// punch or deletion runs only once no handle is left.
    #[cfg(feature = "std")]
    pub(crate) fn downgrade(&self) -> alloc::sync::Weak<inner::Inner> {
        Arc::downgrade(&self.0)
    }

    /// Byte offset of the first data block whose last key reaches `key`. Punching
    /// `[0, offset)` reclaims every data block strictly below `key` while leaving
    /// the straddling block and the index / footer (which follow all data blocks)
    /// intact. When `key` is past the last block's keys, returns the end of the
    /// data region (every data block is punchable).
    ///
    /// # Errors
    ///
    /// Propagates a block-index read error.
    #[cfg_attr(
        not(feature = "std"),
        allow(
            dead_code,
            reason = "tight-space punch offset; its compaction consumer is std-gated, so unused under no_std"
        )
    )]
    pub(crate) fn punch_offset_for(&self, key: &[u8]) -> crate::Result<u64> {
        self.punch_offset_charged(key, ReadCharge::Maintenance)
    }

    /// [`Self::punch_offset_for`], every index block the walk reads from the
    /// file paced by `pace` just before the read is made.
    #[cfg_attr(
        not(feature = "std"),
        allow(dead_code, reason = "its verify consumer is std-gated")
    )]
    pub(crate) fn punch_offset_paced(
        &self,
        key: &[u8],
        charge: ReadCharge,
        pace: crate::table::util::Pacer,
    ) -> crate::Result<u64> {
        self.punch_offset_walk(key, self.index_walk_charged(charge).with_pace(pace))
    }

    /// [`Self::punch_offset_for`], charging its index walk as `charge` says.
    fn punch_offset_charged(&self, key: &[u8], charge: ReadCharge) -> crate::Result<u64> {
        self.punch_offset_walk(key, self.index_walk_charged(charge))
    }

    /// The punch offset for `key` over the index handles `walk` yields.
    fn punch_offset_walk(
        &self,
        key: &[u8],
        walk: block_index::BlockIndexIterImpl,
    ) -> crate::Result<u64> {
        let mut data_end = 0u64;
        for handle in walk {
            let handle = handle?;
            if self.comparator.compare(handle.end_key(), key) != core::cmp::Ordering::Less {
                return Ok(handle.offset().0);
            }
            data_end = handle.offset().0 + u64::from(handle.size());
        }
        Ok(data_end)
    }

    /// Byte offset of this view's first LIVE data block: `0` for a normal table,
    /// or the punch offset for a tight-space RESTRICTED view (its `[0, offset)`
    /// data blocks are hole-punched and read as zeros). A data block or section
    /// entry at a lower offset is DEAD (superseded, never read), so the
    /// disk-fresh verification gates skip it.
    ///
    /// # Errors
    ///
    /// Propagates a restricted view's punch-offset lookup failure instead of
    /// grading it `0`: falling back to `0` would make the verification gates walk
    /// the hole-punched prefix (which reads as zeros), report its blocks as
    /// structural corruption, and — on the heal reconcile path — strip a valid
    /// heal attestation for what is really a transient partitioned-index read.
    /// Propagating keeps a transient failure inconclusive (the marker survives for
    /// the next patrol). A normal (unrestricted) table never calls the fallible
    /// lookup, so it always returns `Ok(0)`.
    pub(crate) fn punch_offset(&self) -> crate::Result<u64> {
        match self.restrict_lower_bound() {
            Some(bound) => self.punch_offset_for(bound),
            None => Ok(0),
        }
    }

    /// The whole-file digest for a normal table, or the LIVE-SUFFIX digest for a
    /// tight-space RESTRICTED view: its `[0, punch_offset)` prefix is hole-
    /// punched once a superseding output table owns those keys, so hashing the
    /// whole physical file would fold the punched (zeroed) prefix into the
    /// digest and never match the manifest. Digesting only `[punch_offset, end)`
    /// keeps the checksum stable across the punch, and it is what
    /// [`reopen_restricted`](Self::reopen_restricted) records and what
    /// verification / heal reconciliation must recompute for a restricted view.
    pub(crate) fn live_region_checksum(&self) -> crate::Result<Checksum> {
        self.suffix_checksum_for(self.restrict_lower_bound())
    }

    /// The entries this view actually serves.
    ///
    /// `metadata.item_count` describes the WHOLE original SST, prefix included,
    /// so a restricted view reports entries a superseding output now owns.
    /// While a tight-space slice is in flight the version holds both, and
    /// summing the raw metadata counts those entries twice.
    ///
    /// Exact when the table carries a zone map (per-block row counts); without
    /// one the blocks above the straddling one are apportioned by data bytes,
    /// which is the same granularity every other estimate over this table uses.
    ///
    /// `charge` says whose read this is. A query planner's estimate is part of
    /// the query and is counted; a monitoring report is not, so polling it
    /// leaves a workload's read counters unchanged.
    ///
    /// # Errors
    ///
    /// Propagates the index walk and the read of the straddling block.
    pub(crate) fn live_item_count(&self, charge: ReadCharge) -> crate::Result<u64> {
        let Some(bound) = self.restrict_lower_bound() else {
            return Ok(self.metadata.item_count);
        };
        // One walk serves all of it: the blocks below the straddling one are
        // skipped, the straddling one is counted, the rest are summed.
        let mut walk = self.index_walk_charged(charge);
        let mut any_block = false;
        let straddle = loop {
            let Some(handle) = walk.next() else {
                break None;
            };
            let handle = handle?;
            any_block = true;
            if self.comparator.compare(handle.end_key(), bound) != core::cmp::Ordering::Less {
                break Some(handle);
            }
        };
        let Some(straddle) = straddle else {
            // Past every block the whole data region is superseded; a table
            // with no data blocks keeps its recorded count.
            return Ok(if any_block {
                0
            } else {
                self.metadata.item_count
            });
        };
        let punch = straddle.offset().0;
        if punch == 0 {
            return Ok(self.metadata.item_count);
        }
        let straddle_live = self.straddling_block_live(&straddle, bound, charge)?;
        if !self.zone_map.is_empty() {
            // The straddling block is counted exactly above: its recorded row
            // count covers the dead rows below the bound too.
            let mut rows = straddle_live;
            for handle in walk {
                let handle = handle?;
                if let Some(col) = self
                    .zone_map
                    .columns_for(*handle.offset())
                    .and_then(<[_]>::first)
                {
                    rows += u64::from(col.row_count);
                }
            }
            return Ok(rows);
        }
        let straddle_end = punch + u64::from(straddle.size());
        let last = match walk.next_back() {
            Some(last) => last?,
            None => straddle,
        };
        let data_end = *last.offset() + u64::from(last.size());
        // A straddling block reaching past the data section cannot be reasoned
        // about; keep the recorded count rather than inventing a smaller one.
        let Some(above) = data_end.checked_sub(straddle_end).filter(|_| data_end > 0) else {
            return Ok(self.metadata.item_count);
        };
        let apportioned = u64::try_from(
            u128::from(self.metadata.item_count) * u128::from(above) / u128::from(data_end),
        )
        .unwrap_or(self.metadata.item_count);
        Ok(straddle_live + apportioned)
    }

    /// This view's block-index walk, charged to the read counters only when it
    /// serves a caller's read.
    fn index_walk_charged(&self, charge: ReadCharge) -> block_index::BlockIndexIterImpl {
        self.block_index.iter().with_charge(charge)
    }

    /// The live rows of the block STRADDLING the restriction: the first whose
    /// last key reaches `bound`, of which the view serves only the entries
    /// `>= bound`.
    ///
    /// Every block below it is dead in full and every block above is live in
    /// full, so it is the only one whose rows have to be counted rather than
    /// read off the index — and a bound landing on a block's last key (what a
    /// tight-space slice commonly produces) makes almost all of its rows dead.
    ///
    /// # Errors
    ///
    /// Propagates the read of the block.
    fn straddling_block_live(
        &self,
        straddle: &KeyedBlockHandle,
        bound: &[u8],
        charge: ReadCharge,
    ) -> crate::Result<u64> {
        // A wholly delete-masked columnar block serves no keys at all.
        let Some(block) = self.load_data_block_charged(straddle.as_ref(), charge)? else {
            return Ok(0);
        };
        let data = &block.inner.data;
        let cmp = &*self.comparator;
        let mut live = 0u64;
        for item in block.iter(self.comparator.clone()) {
            if item.compare_key(bound, data, cmp) != core::cmp::Ordering::Less {
                live += 1;
            }
        }
        Ok(live)
    }

    /// The same digest for a restriction this VIEW does not carry yet: the
    /// recovery scan digests a candidate before the manifest's restrictions are
    /// attached (that happens when the version is built), so a restricted table
    /// would otherwise be hashed whole and never match its committed
    /// live-suffix digest.
    ///
    /// `None` digests the whole file, which is what an unrestricted table's
    /// manifest entry records.
    ///
    /// # Errors
    ///
    /// Propagates the index lookup of `bound` and the read of the file.
    pub(crate) fn suffix_checksum_for(&self, bound: Option<&UserKey>) -> crate::Result<Checksum> {
        let start = match bound {
            Some(bound) => self.punch_offset_for(bound)?,
            None => 0,
        };
        crate::file::checksum_from_with_overrides(&*self.fs, &self.path, start, &[])
            .map(Checksum::from_raw)
    }

    /// Installs the tree-wide deletion pause used by checkpoints.
    ///
    /// Idempotent: a second call is a no-op. Called by the owning tree
    /// after recovery and after compaction registers freshly-built tables.
    pub(crate) fn install_deletion_pause(&self, pause: Arc<crate::deletion_pause::DeletionPause>) {
        let _ = self.0.deletion_pause.set(Box::new(pause));
    }

    /// The shared heal-serialization lock for this table, lazily created on
    /// first use. Held by the patrol scrub across the whole scan-to-reconcile
    /// span so two overlapping heals cannot race the link-count probe or the
    /// digest reconciliation. Shared by STABLE table identity:
    /// [`reopen_restricted`](Self::reopen_restricted) propagates it into the
    /// distinct `Inner` it creates.
    #[cfg(all(feature = "std", feature = "page_ecc"))]
    pub(crate) fn heal_lock_arc(&self) -> Arc<parking_lot::Mutex<()>> {
        Arc::clone(
            self.0
                .heal_lock
                .get_or_init(|| Box::new(Arc::new(parking_lot::Mutex::new(())))),
        )
    }

    /// Installs a shared heal lock, so a re-opened view serializes heals against
    /// the original. Idempotent: a second call is a no-op.
    #[cfg(all(feature = "std", feature = "page_ecc"))]
    pub(crate) fn install_heal_lock(&self, lock: Arc<parking_lot::Mutex<()>>) {
        let _ = self.0.heal_lock.set(Box::new(lock));
    }

    /// Installs the tree-wide background file deleter.
    ///
    /// Idempotent: a second call is a no-op. Called by the owning tree after
    /// recovery and after compaction registers freshly-built tables, so an
    /// obsolete SST's `unlink` runs off the foreground path while its blocks
    /// are reclaimed synchronously at Drop.
    #[cfg(feature = "std")]
    pub(crate) fn install_background_deleter(&self, deleter: Arc<crate::BackgroundDeleter>) {
        let _ = self.0.background_deleter.set(Box::new(deleter));
    }

    /// Installs the tree-wide ECC heal-hint sink.
    ///
    /// Idempotent: a second call is a no-op. Called by the owning tree after
    /// recovery and after compaction registers freshly-built tables, so a
    /// confirmed-persistent ECC correction on a read can queue this SST for a
    /// healing recompaction.
    pub(crate) fn install_heal_hints(&self, hints: Arc<crate::heal_hints::HealHints>) {
        let _ = self.0.heal_hints.set(Box::new(hints));
    }

    /// Binds this freshly created table to the tree's shared machinery.
    ///
    /// **Every path that makes a new table reachable must call this**, and
    /// nothing else should install the individual sinks by hand: a table is
    /// only correct once it is bound, and hand-rolled installation at each
    /// publication site is how sites come to differ. A table that skips it
    /// looks perfectly healthy and fails silently and much later — a
    /// confirmed-persistent ECC correction can never queue it for a healing
    /// rewrite, so the bitrot stays on disk and every read pays the
    /// correction again, and its in-place heal can race a checkpoint's
    /// hard-link.
    ///
    /// Idempotent per sink, so re-binding a table is harmless.
    pub(crate) fn bind_to_tree(&self, sinks: &TableSinks<'_>) {
        self.install_deletion_pause(Arc::clone(sinks.deletion_pause));
        self.install_heal_hints(Arc::clone(sinks.heal_hints));
        // A second bind keeps the first budget, like the other sinks.
        let _ = self.0.read_budget.set(Box::new(sinks.read_budget));
        #[cfg(feature = "std")]
        self.install_background_deleter(Arc::clone(sinks.background_deleter));
        // A second bind keeps the counts the first one started.
        if sinks.track_filter_probes {
            self.0.probe_stats.get_or_init(Box::default);
        }
    }

    /// This table's filter probes, when its tree counts them.
    pub(crate) fn probe_stats(&self) -> Option<&crate::table::probe_stats::ProbeStats> {
        self.0.probe_stats.get()
    }

    /// Counts a probe the filter answered, and whether it answered absent.
    /// Only the reads that produce the answer count: a prewarm that probes
    /// ahead of the read it warms does not.
    fn count_probe(&self, bloom: &BloomResult) {
        if let Some(stats) = self.probe_stats() {
            let counts = bloom.probe_counts();
            if counts.probes != 0 {
                stats.probe();
            }
            if counts.negatives != 0 {
                stats.negative();
            }
        }
    }

    /// Counts the probes a read tallied while planning, once it answers from
    /// that plan.
    pub(crate) fn count_probes(&self, counts: crate::table::probe_stats::ProbeCounts) {
        if let Some(stats) = self.probe_stats() {
            stats.add(counts);
        }
    }

    /// Counts what a batched read tallied while planning, once it answers
    /// from that plan: the probes, and the filter queries and skips.
    pub(crate) fn count_plan(&self, counts: crate::table::probe_stats::PlanCounts) {
        self.count_probes(counts.probes);
        if counts.point_reads > 0 {
            self.record_accesses(u64::try_from(counts.point_reads).unwrap_or(u64::MAX));
        }
        #[cfg(feature = "metrics")]
        {
            use core::sync::atomic::Ordering::Relaxed;
            self.metrics
                .filter_queries
                .fetch_add(counts.filter_queries, Relaxed);
            self.metrics
                .io_skipped_by_filter
                .fetch_add(counts.filter_skips, Relaxed);
        }
    }

    /// Counts a probe the filter let through whose read found no version of
    /// the key.
    ///
    /// That is a false positive only when the read could see every version the
    /// table holds (`table_seqno` above its newest): at an older snapshot the
    /// key may be held only in versions the snapshot cannot see, and the index
    /// walk skips the blocks holding them, so telling the two apart would cost
    /// a read the probe did not make. Those probes are left uncounted.
    pub(crate) fn count_false_positive(&self, table_seqno: SeqNo) {
        if let Some(stats) = self.probe_stats()
            && table_seqno > self.metadata.seqnos.1
        {
            stats.negative();
        }
    }

    /// Whether a key this table's filter let through and no read found is
    /// counted: the table has a filter, and the count has somewhere to go.
    pub(crate) fn counts_filter_misses(&self) -> bool {
        self.has_filter() && (cfg!(feature = "metrics") || self.probe_stats().is_some())
    }

    /// Counts a key the filter let through that the read of this table, at
    /// `table_seqno`, found no version of: a filter query that reached the
    /// table, and a false positive where [`Self::count_false_positive`] says.
    pub(crate) fn count_filter_miss(&self, table_seqno: SeqNo) {
        #[cfg(feature = "metrics")]
        self.metrics
            .filter_queries
            .fetch_add(1, core::sync::atomic::Ordering::Relaxed);
        self.count_false_positive(table_seqno);
    }

    /// The bytes of this table's data section a key range covers, at data
    /// block granularity and read from the block index alone (no data block
    /// is read), or `None` when the table has no data block.
    ///
    /// `edge` says which blocks a range boundary takes (see [`SpanEdge`]).
    /// `table_seqno` is table-local.
    pub(crate) fn data_span(
        &self,
        bounds: (core::ops::Bound<&[u8]>, core::ops::Bound<&[u8]>),
        table_seqno: SeqNo,
        edge: SpanEdge,
    ) -> crate::Result<Option<DataSpan>> {
        use crate::table::block_index::BlockIndex;
        use core::cmp::Ordering;
        use core::ops::Bound;

        // data_end = the data section's byte extent = last data block's end.
        let Some(last) = self.block_index.iter().next_back() else {
            return Ok(None);
        };
        let last = last?;
        let data_end = *last.offset() + u64::from(last.size());
        if data_end == 0 {
            return Ok(None);
        }

        // The data block that would contain `key`, as (start, end) byte
        // offsets, or `None` when `key` is past the last block.
        let block_span = |key: &[u8]| -> crate::Result<Option<(u64, u64)>> {
            let Some(mut iter) = self.block_index.forward_reader(key, table_seqno) else {
                return Ok(None);
            };
            let Some(handle) = iter.next() else {
                return Ok(None);
            };
            let h = handle?;
            let start = *h.offset();
            Ok(Some((start, (start + u64::from(h.size())).min(data_end))))
        };
        // Tight-space restriction: a restricted table view serves only keys
        // at or above its lower bound, with the punched-out prefix served by
        // the replacement table, so the data below it is not this view's.
        let live_start = match self.restrict_lower_bound() {
            Some(rb) => block_span(rb.as_ref())?.map_or(data_end, |(start, _)| start),
            None => 0,
        };
        // Where the first block whose last key is at or past `key` starts, or
        // strictly past it when `past`; the data end when there is none. The
        // versions of one key can fill several blocks, all ending at it.
        let first_block_from = |key: &[u8], past: bool| -> crate::Result<u64> {
            let Some(iter) = self.block_index.forward_reader(key, table_seqno) else {
                return Ok(data_end);
            };
            for handle in iter {
                let h = handle?;
                if !past || self.comparator.compare(h.end_key(), key) != Ordering::Equal {
                    return Ok(*h.offset());
                }
            }
            Ok(data_end)
        };
        let off_lo = match (bounds.0, edge) {
            (Bound::Unbounded, _) => 0,
            (Bound::Included(k) | Bound::Excluded(k), SpanEdge::Whole) => {
                block_span(k)?.map_or(data_end, |(start, _)| start)
            }
            (Bound::Included(k), SpanEdge::ByLastKey) => first_block_from(k, false)?,
            (Bound::Excluded(k), SpanEdge::ByLastKey) => first_block_from(k, true)?,
        }
        .max(live_start);
        let off_hi = match (bounds.1, edge) {
            (Bound::Unbounded, _) => data_end,
            (Bound::Included(k) | Bound::Excluded(k), SpanEdge::Whole) => {
                block_span(k)?.map_or(data_end, |(_, end)| end)
            }
            (Bound::Included(k), SpanEdge::ByLastKey) => first_block_from(k, true)?,
            (Bound::Excluded(k), SpanEdge::ByLastKey) => first_block_from(k, false)?,
        };
        Ok(Some(DataSpan {
            // A range ending before it starts covers nothing.
            covered: off_hi.saturating_sub(off_lo),
            live_start,
            data_end,
        }))
    }

    /// How this table's columnar reads fetch their pages: the budget its tree
    /// bound it with, or the default for a table no tree owns.
    pub(crate) fn read_budget(&self) -> crate::config::ReadBudget {
        self.0.read_budget.get().copied().unwrap_or_default()
    }

    /// The installed heal-hint sink, exposed so tests outside this module can
    /// assert every publication path binds it. Gated with the tests that use
    /// it: without Page ECC nothing produces a heal hint to begin with.
    #[cfg(all(test, feature = "page_ecc"))]
    pub(crate) fn heal_hints_for_test(&self) -> Option<Arc<crate::heal_hints::HealHints>> {
        self.0.heal_hints.get().cloned()
    }

    #[must_use]
    pub fn checksum(&self) -> Checksum {
        // The refreshed digest (an in-place heal changed the bytes after
        // recovery) supersedes the one captured at recovery.
        self.2.unwrap_or(self.0.checksum)
    }

    /// A view of this table whose full-file checksum is `checksum`: an
    /// in-place heal changed the file's bytes, and installing this view into
    /// a new version makes the diff persist the refreshed digest to the
    /// manifest (see [`crate::Version::with_refreshed_table_checksum`]).
    #[must_use]
    pub(crate) fn with_refreshed_checksum(&self, checksum: Checksum) -> Self {
        Self(self.0.clone(), self.1.clone(), Some(checksum))
    }

    /// Read `len` bytes from the cursor position with checked arithmetic.
    /// Uses `.get()` instead of direct indexing to satisfy `clippy::indexing_slicing`.
    #[expect(
        clippy::cast_possible_truncation,
        reason = "block sizes are bounded well within usize on all supported platforms"
    )]
    fn read_checked_slice(
        cursor: &mut crate::io::Cursor<&[u8]>,
        field: &'static str,
        len: usize,
    ) -> crate::Result<Vec<u8>> {
        let offset = cursor.position();
        let data = cursor.get_ref();
        let pos = offset as usize;
        let end_pos = pos
            .checked_add(len)
            .ok_or(crate::Error::RangeTombstoneDecode { field, offset })?;
        let buf = data
            .get(pos..end_pos)
            .ok_or(crate::Error::RangeTombstoneDecode { field, offset })?
            .to_vec();
        cursor.set_position(end_pos as u64);
        Ok(buf)
    }

    /// Decodes range tombstones from a raw block.
    ///
    /// Wire format (repeated): `[start_len:u16_le][start][end_len:u16_le][end][seqno:u64_le]`
    ///
    /// # Errors
    ///
    /// Will return `Err` if the block data is malformed.
    #[expect(
        clippy::cast_possible_truncation,
        reason = "block sizes are bounded well within usize on all supported platforms"
    )]
    fn decode_range_tombstones(
        block: &Block,
        comparator: &dyn crate::comparator::UserComparator,
    ) -> crate::Result<Vec<RangeTombstone>> {
        use crate::io::{Cursor, LE, ReadBytesExt};

        let mut tombstones = Vec::new();
        let data = block.data.as_ref();

        // A dedicated RT block with empty payload is corruption — the writer
        // only creates an RT block handle when at least one tombstone exists.
        if data.is_empty() {
            log::error!("Range tombstone block: missing start_len");
            return Err(crate::Error::RangeTombstoneDecode {
                field: "start_len",
                offset: 0,
            });
        }

        let mut cursor = Cursor::new(data);

        while (cursor.position() as usize) < data.len() {
            let entry_offset = cursor.position();
            let start_len_offset = entry_offset;
            let start_len =
                cursor
                    .read_u16::<LE>()
                    .map_err(|_| crate::Error::RangeTombstoneDecode {
                        field: "start_len",
                        offset: start_len_offset,
                    })? as usize;

            // Validate length against remaining data before allocating
            let remaining = data.len() - cursor.position() as usize;
            if start_len > remaining {
                log::error!(
                    "Range tombstone block: start_len {start_len} exceeds remaining {remaining}"
                );
                return Err(crate::Error::RangeTombstoneDecode {
                    field: "start_len",
                    offset: start_len_offset,
                });
            }

            // Extract validated slice from cursor position.
            // Using .get() instead of direct indexing to satisfy clippy::indexing_slicing.
            let start_buf = Self::read_checked_slice(&mut cursor, "start", start_len)?;

            let end_len_offset = cursor.position();
            let end_len =
                cursor
                    .read_u16::<LE>()
                    .map_err(|_| crate::Error::RangeTombstoneDecode {
                        field: "end_len",
                        offset: end_len_offset,
                    })? as usize;

            let remaining = data.len() - cursor.position() as usize;
            if end_len > remaining {
                log::error!(
                    "Range tombstone block: end_len {end_len} exceeds remaining {remaining}"
                );
                return Err(crate::Error::RangeTombstoneDecode {
                    field: "end_len",
                    offset: end_len_offset,
                });
            }

            let end_buf = Self::read_checked_slice(&mut cursor, "end", end_len)?;

            let seqno_offset = cursor.position();
            let seqno =
                cursor
                    .read_u64::<LE>()
                    .map_err(|_| crate::Error::RangeTombstoneDecode {
                        field: "seqno",
                        offset: seqno_offset,
                    })?;

            let start = UserKey::from(start_buf);
            let end = UserKey::from(end_buf);

            // Validate invariant: start < end using the tree's comparator
            // (reject corrupted or misordered intervals)
            if comparator.compare(&start, &end) != core::cmp::Ordering::Less {
                log::error!("Range tombstone block: invalid interval (start >= end)");
                return Err(crate::Error::RangeTombstoneDecode {
                    field: "interval",
                    offset: entry_offset,
                });
            }

            tombstones.push(RangeTombstone::new(start, end, seqno));
        }

        Ok(tombstones)
    }

    /// Returns the range tombstones stored in this table.
    #[must_use]
    pub(crate) fn range_tombstones(&self) -> &[RangeTombstone] {
        &self.0.range_tombstones
    }

    /// The greatest end of this table's range tombstones, in the tree's key
    /// order: with the first one's start, the stretch they can cover, which
    /// may reach past the table's key range. `None` without tombstones.
    pub(crate) fn range_tombstones_end(&self) -> Option<&UserKey> {
        self.0.range_tombstones_end.as_ref()
    }

    /// The range tombstones as visible through THIS view: a tight-space
    /// restriction clamps them to the live suffix (`>= bound`). The punched
    /// prefix's deletions belong to the slice output that superseded it, so
    /// exposing them unclamped would emit a change-data-capture event twice
    /// (once from the clipped copy in the slice output, once from here) and
    /// cover keys this view no longer owns. Read-path masking keeps using
    /// the raw list — an over-wide tombstone there only masks keys the
    /// restricted view refuses to serve anyway.
    /// Borrowed as stored; only a tombstone the restriction clamps is a new
    /// one.
    pub(crate) fn visible_range_tombstones(
        &self,
    ) -> impl Iterator<Item = alloc::borrow::Cow<'_, RangeTombstone>> + '_ {
        use alloc::borrow::Cow;

        self.0.range_tombstones.iter().filter_map(move |rt| {
            let Some(bound) = self.1.as_ref() else {
                return Some(Cow::Borrowed(rt));
            };
            // Live keys are `>= bound`; a tombstone covers `[start, end)`.
            if self.comparator.compare(&rt.end, bound) != core::cmp::Ordering::Greater {
                // Wholly below the restriction: every covered key is punched.
                return None;
            }
            if self.comparator.compare(&rt.start, bound) == core::cmp::Ordering::Less {
                return Some(Cow::Owned(RangeTombstone::new(
                    bound.clone(),
                    rt.end.clone(),
                    rt.seqno,
                )));
            }
            Some(Cow::Borrowed(rt))
        })
    }

    pub(crate) fn mark_as_deleted(&self) {
        self.0
            .is_deleted
            .store(true, core::sync::atomic::Ordering::Release);
    }

    /// Checks if a key range overlaps (partially or fully) with this table's key range.
    pub(crate) fn check_key_range_overlap_cmp(
        &self,
        bounds: &(Bound<&[u8]>, Bound<&[u8]>),
        cmp: &dyn crate::comparator::UserComparator,
    ) -> bool {
        if !self
            .metadata
            .key_range
            .overlaps_with_bounds_cmp(bounds, cmp)
        {
            return false;
        }

        // Tight-space restriction: the live range is `[bound, hi]`. If the
        // query's upper bound is strictly below `bound`, the query targets only
        // the punched-out prefix (now served by a superseding output table), so
        // this table does not overlap.
        if let Some(bound) = &self.1 {
            match bounds.1 {
                Bound::Included(end) => {
                    if cmp.compare(end, bound) == core::cmp::Ordering::Less {
                        return false;
                    }
                }
                Bound::Excluded(end) => {
                    // end <= bound: every key the query can reach is below the
                    // live range.
                    if cmp.compare(end, bound) != core::cmp::Ordering::Greater {
                        return false;
                    }
                }
                Bound::Unbounded => {}
            }
        }

        true
    }

    /// Checks the full-table bloom filter for a hash value.
    ///
    /// Returns `Ok(true)` if the hash may exist in the filter (or if no full
    /// filter is available), `Ok(false)` if the hash is definitely absent.
    ///
    /// Handles full (non-partitioned) filters directly. Partitioned / TLI
    /// filters are keyed by user key, not raw hash, so this method returns
    /// `Ok(true)` conservatively for those types.
    fn bloom_may_contain_hash(&self, hash: u64) -> crate::Result<bool> {
        // Full (non-partitioned) filter — single bloom covers the entire table
        if let Some(block) = &self.pinned_filter_block {
            return block.maybe_contains_hash(hash);
        }

        // Partitioned / TLI filters: partition index is keyed by user key, not
        // raw hash — we would need to scan ALL partitions to check,
        // which is O(partitions) I/O and defeats the purpose of bloom skip.
        // Returning Ok(true) is correct (conservative: segment is NOT skipped).
        if self.pinned_filter_index.is_some() || self.regions.filter_tli.is_some() {
            return Ok(true);
        }

        // Unpinned full filter — load from disk.
        // Safe: if we reach here, filter_tli is None (no partitioned filter),
        // so regions.filter is a single full-table bloom, not a concatenation.
        if let Some(filter_block_handle) = &self.regions.filter {
            let block = self.load_block(
                filter_block_handle,
                BlockType::Filter,
                CompressionType::None, // NOTE: Filter blocks are never compressed (crate invariant)
                #[cfg(zstd_any)]
                None,
                &LookupFd::default(),
            )?;
            let block = FilterBlock::new(block);
            return block.maybe_contains_hash(hash);
        }

        // No filter available — cannot rule out the hash
        Ok(true)
    }

    /// Checks the bloom filter for a prefix hash.
    ///
    /// Returns `Ok(true)` if the prefix may exist in this table (or if no
    /// filter is available), `Ok(false)` if the prefix is definitely absent.
    ///
    /// This is used by prefix scans to skip segments that contain no keys
    /// with a matching prefix. The prefix must have been indexed at write
    /// time via a [`PrefixExtractor`](crate::PrefixExtractor): a table whose
    /// filter indexes another extractor's prefixes, or none, cannot rule the
    /// prefix out and answers `Ok(true)`.
    pub(crate) fn maybe_contains_prefix(&self, prefix_hash: u64) -> crate::Result<bool> {
        if self.prefix_filter.is_none() {
            return Ok(true);
        }
        self.bloom_may_contain_hash(prefix_hash)
    }

    /// Whether [`Self::maybe_contains_prefix`] asks the filter at all: the
    /// filter indexes the prefixes of the extractor the table was opened
    /// under.
    pub(crate) fn has_prefix_filter(&self) -> bool {
        self.prefix_filter.is_some()
    }

    /// Checks the bloom filter for a precomputed key hash.
    ///
    /// Returns `Ok(true)` if the key may exist in this table (or if no
    /// filter is available), `Ok(false)` if the key is definitely absent.
    ///
    /// Used by the point-read merge pipeline to pre-filter disk tables
    /// before building range iterators. For partitioned or TLI filter
    /// configurations, the underlying check returns `Ok(true)` conservatively,
    /// so pre-filtering is best-effort and configuration-dependent.
    pub(crate) fn bloom_may_contain_key_hash(&self, key_hash: u64) -> crate::Result<bool> {
        self.bloom_may_contain_hash(key_hash)
    }

    /// Checks the bloom filter for a key, with partition-aware seeking.
    ///
    /// Unlike [`bloom_may_contain_key_hash`](Self::bloom_may_contain_key_hash)
    /// which falls back to `Ok(true)` for partitioned filters, this method
    /// uses the user key to seek the partition index and check only the
    /// matching partition's bloom filter.
    ///
    /// `key_hash` must be the xxh3 hash of `key` (pre-computed by the caller
    /// to avoid redundant hashing — same pattern as [`Table::get`]).
    pub(crate) fn bloom_may_contain_key(&self, key: &[u8], key_hash: u64) -> crate::Result<bool> {
        self.key_filter_answer(key, key_hash)
            .map(|answer| answer == KeyFilterAnswer::MayContain)
    }

    /// [`Self::bloom_may_contain_key`], telling a filter's absent answer
    /// apart from a key the partition index alone rules out.
    pub(crate) fn key_filter_answer(
        &self,
        key: &[u8],
        key_hash: u64,
    ) -> crate::Result<KeyFilterAnswer> {
        debug_assert_eq!(
            crate::hash::hash64(key),
            key_hash,
            "bloom_may_contain_key: key_hash must be crate::hash::hash64(key)"
        );
        let by_hash = |may: bool| {
            if may {
                KeyFilterAnswer::MayContain
            } else {
                KeyFilterAnswer::Absent
            }
        };

        // Full (non-partitioned) filter — delegate to hash-only path.
        // A table has either pinned_filter_block (full) or pinned_filter_index
        // (partitioned), never both — checked at construction time.
        if self.pinned_filter_block.is_some() {
            return self.bloom_may_contain_hash(key_hash).map(by_hash);
        }

        // Partitioned filter with pinned TLI — seek to the matching partition
        if let Some(filter_idx) = &self.pinned_filter_index {
            let mut iter = filter_idx.iter(self.comparator.clone());
            iter.seek(key, crate::seqno::MAX_SEQNO);

            if let Some(filter_block_handle) = iter.next() {
                let filter_block_handle = filter_block_handle.materialize(filter_idx.as_slice());

                let block = self.load_block(
                    &filter_block_handle.into_inner(),
                    BlockType::Filter,
                    CompressionType::None,
                    #[cfg(zstd_any)]
                    None,
                    &LookupFd::default(),
                )?;
                let block = FilterBlock::new(block);
                return block.maybe_contains_hash(key_hash).map(by_hash);
            }

            // iter.next() == None means the key is beyond all partition
            // boundaries (seek found no ceiling entry in the TLI, which is
            // ordered by each partition's last user key). The key cannot
            // exist in this table, as in `check_bloom`.
            return Ok(KeyFilterAnswer::PastPartitions);
        }

        // Unpinned filter — fall through to hash-only path (handles both
        // unpinned full filters and the no-filter case)
        self.bloom_may_contain_hash(key_hash).map(by_hash)
    }

    /// Whether a key check answers from a filter rather than passing the key
    /// for want of one: [`Self::bloom_may_contain_key`] when `by_key`, which
    /// reaches a partitioned filter through its pinned index, otherwise
    /// [`Self::bloom_may_contain_key_hash`], which reaches only a full one.
    pub(crate) fn key_check_consults_filter(&self, by_key: bool) -> bool {
        self.pinned_filter_block.is_some()
            || (by_key && self.pinned_filter_index.is_some())
            || (self.regions.filter.is_some()
                && self.regions.filter_tli.is_none()
                && self.pinned_filter_index.is_none())
    }

    /// Returns the highest effective sequence number in the table.
    ///
    /// For tables produced by flush/compaction (`global_seqno == 0`), this
    /// returns the highest item seqno directly.
    ///
    /// For tables produced by bulk ingestion (`global_seqno > 0`), items
    /// are written with local seqno 0 and the table carries a global offset.
    /// The effective seqno of each item is `global_seqno + local_seqno`,
    /// which mirrors the translation in [`Table::get`].
    #[must_use]
    pub fn get_highest_seqno(&self) -> SeqNo {
        self.metadata.seqnos.1 + self.global_seqno()
    }

    /// The highest LOCAL (on-disk, pre-`global_seqno`) sequence number of any
    /// entry, `0` for an empty table. Unlike [`get_highest_seqno`], it does NOT
    /// add the offset. Manifest repair uses it as the LEGACY bulk-ingest
    /// signature: a table of unknown provenance whose entries all sit at local
    /// seqno 0 may itself be a legacy bulk-ingested table.
    ///
    /// [`get_highest_seqno`]: Self::get_highest_seqno
    #[must_use]
    pub(crate) fn max_local_seqno(&self) -> SeqNo {
        self.metadata.seqnos.1
    }

    /// The local seqno bounds the meta records: the lowest and highest over
    /// every entry and range tombstone, and the highest over the entries
    /// alone.
    #[cfg(feature = "std")]
    pub(crate) fn local_seqno_bounds(&self) -> ((SeqNo, SeqNo), SeqNo) {
        (self.metadata.seqnos, self.metadata.highest_kv_seqno)
    }

    /// Returns the highest sequence number from KV entries only,
    /// excluding range tombstone seqnos.
    ///
    /// This enables more aggressive table-skip: a covering RT stored
    /// in the same table can trigger skip because its seqno may exceed
    /// the KV-only max even though it doesn't exceed the overall max.
    ///
    /// For tables written before this field was introduced, falls back
    /// to `get_highest_seqno()` (conservative but correct).
    #[must_use]
    pub fn get_highest_kv_seqno(&self) -> SeqNo {
        self.metadata.highest_kv_seqno + self.global_seqno()
    }

    /// Returns the number of tombstone markers in the `Table`.
    #[must_use]
    #[doc(hidden)]
    pub fn tombstone_count(&self) -> u64 {
        self.metadata.tombstone_count
    }

    /// Returns the number of weak (single delete) tombstones in the `Table`.
    #[must_use]
    #[doc(hidden)]
    pub fn weak_tombstone_count(&self) -> u64 {
        self.metadata.weak_tombstone_count
    }

    /// Returns the number of value entries reclaimable once weak tombstones can be GC'd.
    #[must_use]
    #[doc(hidden)]
    pub fn weak_tombstone_reclaimable(&self) -> u64 {
        self.metadata.weak_tombstone_reclaimable
    }

    /// Returns the ratio of tombstone markers in the `Table`.
    #[must_use]
    #[doc(hidden)]
    pub fn tombstone_ratio(&self) -> f32 {
        todo!()

        //  self.metadata.tombstone_count as f32 / self.metadata.key_count as f32
    }
}