feat(genomics/index/view): ReferenceView — zero-copy reference access from the index

A borrowed ReferenceView over the persisted Reference2bit section (base_at + decode_window, on-demand 2-bit decode mirroring CompressedDNA::base_at, no full-reference Vec), via ReferenceIndex::reference_view(). Gated by base_at/decode_window == the original reference over an N-bearing multi-contig index. The shared reference-access foundation B4b (aligner DP window) and B4c (variants ref_base) consume.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logannye

src/genomics/index/io.rs

@@ -73,6 +73,13 @@ impl ReferenceIndex {
             &self.contigs,
         ))
     }
+
+    /// Borrow a zero-copy view over the persisted 2-bit reference (`Reference2bit`).
+    pub fn reference_view(
+        &self,
+    ) -> Result<crate::genomics::index::view::ReferenceView<'_>, IndexIoError> {
+        crate::genomics::index::view::ReferenceView::new(self.mmap.as_bytes(), &self.sections)
+    }
 }
 
 /// Writes a new index file.
@@ -835,6 +842,46 @@ mod tests {
         let _ = std::fs::remove_file(corrupt);
     }
 
+    #[test]
+    fn reference_view_decodes_bytes_identical_to_in_ram() {
+        let idx = sample_index();
+        let path = temp_path("refview");
+        IndexWriter::create(&path)
+            .unwrap()
+            .write_genome_index(&idx)
+            .unwrap();
+        let loaded = IndexReader::open(&path).unwrap();
+        let rv = loaded.reference_view().unwrap();
+        let reference = idx.reference();
+
+        assert_eq!(rv.len(), reference.len());
+        assert!(!rv.is_empty());
+        for i in 0..rv.len() {
+            assert_eq!(rv.base_at(i), reference[i], "base_at mismatch @ {i}");
+        }
+
+        let mut buf = Vec::new();
+        let n = reference.len();
+        for (s, e) in [(0usize, 10usize), (6, 14), (12, 22), (0, n), (n - 3, n + 5)] {
+            rv.decode_window(s, e, &mut buf);
+            assert_eq!(
+                buf.as_slice(),
+                &reference[s..e.min(n)],
+                "decode_window {s}..{e}"
+            );
+        }
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn reference_view_is_a_small_borrow() {
+        assert!(
+            std::mem::size_of::<crate::genomics::ReferenceView<'_>>() <= 64,
+            "ReferenceView must be a small borrow, got {}",
+            std::mem::size_of::<crate::genomics::ReferenceView<'_>>()
+        );
+    }
+
     #[test]
     fn open_rejects_a_misaligned_block_offset() {
         // A block-record offset that is in-bounds but not 8-aligned must be rejected

src/genomics/index/mod.rs

@@ -13,4 +13,4 @@ mod view;
 pub use format::IndexHeader;
 pub use io::{IndexReader, IndexWriter, ReferenceIndex};
 pub use report::{estimate_build_working_set, render_plan_line, IndexBuildReport};
-pub use view::{FmIndexView, GenomeIndexView};
+pub use view::{FmIndexView, GenomeIndexView, ReferenceView};

src/genomics/index/view.rs

@@ -322,6 +322,83 @@ impl<'a> GenomeIndexView<'a> {
     }
 }
 
+/// A borrowed, zero-copy view over the persisted 2-bit forward reference
+/// (`Reference2bit`). Decodes bases on demand from the mmap — no full-reference
+/// allocation — so consumers (the aligner DP window in B4b, variants' `ref_base`
+/// in B4c) read the reference from the `.idx` alone. Uses **global** (concatenated)
+/// coordinates; `(contig, pos)` mapping stays with `ContigSet`. The little-endian
+/// host requirement is the same as `FmIndexView` (checked in `new`).
+#[derive(Debug)]
+pub struct ReferenceView<'a> {
+    len: usize,
+    /// 2-bit packed bases, 32 per `u64` word (A/C/G/T = 0/1/2/3).
+    data: &'a [u64],
+    /// Ambiguity bits, one per base (a set bit marks `N`).
+    amb: &'a [u64],
+}
+
+impl<'a> ReferenceView<'a> {
+    /// Parse + validate the `Reference2bit` section into a borrowed view.
+    pub(crate) fn new(bytes: &'a [u8], sections: &[SectionEntry]) -> Result<Self, IndexIoError> {
+        if cfg!(target_endian = "big") {
+            return Err(IndexIoError::Invalid(
+                "zero-copy reference view requires a little-endian host".to_string(),
+            ));
+        }
+        let section = section_bytes(bytes, sections, SectionKind::Reference2bit)?;
+        let mut o = 0usize;
+        let len = read_u64(section, &mut o)? as usize;
+        let data_words = read_u64(section, &mut o)? as usize;
+        let amb_words = read_u64(section, &mut o)? as usize;
+        let data = as_u64_slice(slice_exact(section, &mut o, data_words.saturating_mul(8))?)?;
+        let amb = as_u64_slice(slice_exact(section, &mut o, amb_words.saturating_mul(8))?)?;
+        // The slices must cover `len` bases so `base_at` cannot index out of bounds.
+        if data.len().saturating_mul(32) < len || amb.len().saturating_mul(64) < len {
+            return Err(IndexIoError::Invalid(
+                "Reference2bit section too small for the declared length".to_string(),
+            ));
+        }
+        Ok(Self { len, data, amb })
+    }
+
+    /// Number of reference bases.
+    pub fn len(&self) -> usize {
+        self.len
+    }
+
+    /// Whether the reference is empty.
+    pub fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    /// The ASCII base at global position `global`. Mirrors `CompressedDNA::base_at`:
+    /// a set ambiguity bit decodes to `N`, otherwise the 2-bit code maps to A/C/G/T.
+    pub fn base_at(&self, global: usize) -> u8 {
+        debug_assert!(global < self.len, "reference index out of range");
+        if self.amb[global / 64] & (1u64 << (global % 64)) != 0 {
+            return b'N';
+        }
+        let code = ((self.data[global / 32] >> ((global % 32) * 2)) & 0b11) as u8;
+        match code {
+            0 => b'A',
+            1 => b'C',
+            2 => b'G',
+            _ => b'T',
+        }
+    }
+
+    /// Decode `[start, end.min(len))` into `out` (cleared first). `end` is clamped
+    /// to `len`, so an over-range request never panics; `start <= end` is the
+    /// caller's contract. Bounded by the window size — never the whole genome.
+    pub fn decode_window(&self, start: usize, end: usize, out: &mut Vec<u8>) {
+        out.clear();
+        let end = end.min(self.len);
+        for i in start..end {
+            out.push(self.base_at(i));
+        }
+    }
+}
+
 /// Validate that every block record (at the directory's offsets) lies fully
 /// within the `Blocks` section, using checked arithmetic so a corrupt word-count
 /// can never overflow into an in-bounds-but-wrong slice. Lets `block()` use

src/genomics/mod.rs

@@ -35,7 +35,7 @@ pub use fm_index::{
 pub use genome_index::{GenomeIndex, GenomeIndexError, MAX_GENOME_LEN};
 pub use index::{
     estimate_build_working_set, render_plan_line, FmIndexView, GenomeIndexView, IndexBuildReport,
-    IndexHeader, IndexReader, IndexWriter, ReferenceIndex,
+    IndexHeader, IndexReader, IndexWriter, ReferenceIndex, ReferenceView,
 };
 pub use io::create_bam_writer;
 pub use pileup::{PileupNode, PileupProcessor, PileupSummary, PileupWorkload};