Record Store

Each SlimRecord MUST store the following fixed fields: tid (reference ID), pos, end_pos, flags, mapq, n_cigar_ops, seq_len, matching_bases, indel_bases, next_ref_id (mate reference ID), next_pos (mate position), template_len (signed insert size). The tid, next_ref_id, next_pos, and template_len fields are required for BAM write-back after local realignment.

On construction, the store MUST pre-allocate all six vectors with estimated capacities to avoid reallocation during push_raw. Estimates SHOULD be based on the number of compressed bytes loaded for the region: a typical BAM compression ratio of ~3:1, an average record size of ~400 bytes, ~25 bytes per read name, ~20 bytes per record of CIGAR data, ~150 bytes per record of quality data, and the remaining bytes budgeted for aux. The store MUST accept a byte-count hint for this purpose.

push_raw(raw_bytes) MUST decode a BAM record's fixed fields and append its variable-length data directly into the slabs, without allocating intermediate Box<[u8]> or Vec<u8> per field. The 4-bit packed sequence MUST be decoded (via SIMD when available) to Base enum values in the bases slab.

Slab offsets (name_off, bases_off, cigar_off, qual_off, aux_off) MUST be checked for u32 overflow before storing in both push_raw and push_fields. If any slab exceeds u32::MAX bytes, the store MUST return an error rather than silently truncating the offset.

push_fields(...) MUST accept pre-parsed record fields for SAM and CRAM readers: pos, end_pos, flags, mapq, matching_bases, indel_bases, qname bytes, CIGAR as &[CigarOp], sequence as &[Base], quality bytes, and aux tag bytes in BAM binary format. This avoids encoding to BAM binary only to immediately decode it again. SAM and CRAM parsers convert their native representations to these types before pushing.

The store MUST provide methods to access each variable-length field for a given record index: qname(idx), cigar(idx), seq(idx), seq_at(idx, pos), qual(idx), aux(idx). These return borrowed slices into the slabs.

The store MUST expose records() -> impl ExactSizeIterator<Item = &SlimRecord> yielding records in store order. Iteration MUST visit every live record exactly once and MUST NOT borrow the store mutably, so callers MAY use SlimRecord::cigar(&store) / qname(&store) / seq(&store) / qual(&store) / aux(&store) getters inside the loop body. Callers that need the position of a record within the store MAY use records().enumerate().

Clearing the store for a new region MUST retain the allocated capacity of all six vectors, so that subsequent regions reuse the same memory without reallocation.

All records in the store MUST remain valid and accessible until the store is cleared.

set_alignment(idx, new_pos, new_cigar_ops: &[CigarOp]) MUST replace a record's alignment by appending the new ops to the end of the cigar slab and updating the record's cigar_off, n_cigar_ops, pos, end_pos, matching_bases, and indel_bases. The old CIGAR ops MUST be left in place as dead data (append-only mutation). The sequence, quality, aux, and name slabs MUST NOT be modified. After calling set_alignment on one or more records, the caller MUST call sort_by_pos() before using the store for pileup iteration.

set_alignment MUST validate that the new CIGAR's query-consuming length equals the record's seq_len and that the CIGAR op count fits in u16. All validation MUST complete before any slab mutation. If validation fails, the method MUST return an error without modifying the store.

RecordStore MUST accept a type parameter U (default ()) for per-record user data. A Vec<U> slab MUST grow alongside the existing slabs. When U is (), Vec<()> is a ZST vector with no heap allocation for elements — the extras slab MUST be zero-cost.

push_raw and push_fields on any RecordStore<U> MUST accept &mut E (E: CustomizeRecordStore<Extra = U>) as their last argument and return Result<Option<u32>, DecodeError>. After parsing and writing the record's slab data they MUST call customize.keep_record(rec, &self); if it returns false, the record just pushed MUST be rolled back so that every slab (names/bases/cigar/qual/aux/records/extras) is byte-identical to its pre-push state. Rollback uses the just-pushed SlimRecord's *_off offsets as pre-push slab lengths, since push is append-only. The returned Option<u32> is Some(idx) when kept, None when rejected — rejected records MUST NOT consume an index. Passing &mut () (whose default keep_record is true) is the no-filter form. A proptest verifies that pushing a mixed accept/reject sequence produces byte-identical state to pushing only the accepted inputs with no filter.

SlimRecord MUST provide getter methods seq(&store) -> Result<&[Base]>, qual(&store) -> Result<&[BaseQuality]>, cigar(&store) -> Result<&[CigarOp]>, and aux(&store) -> Result<&[u8]> that take &RecordStore<U> for any U and return slab-backed slices using the record's offset fields. They MUST validate offsets and return a typed RecordAccessError on overflow rather than panic. extra(&store) -> Result<&U> follows the same shape but reads the extras slab. These getters are the canonical way for CustomizeRecordStore impls to access a record's variable-length data without going through RecordStore::record(idx) first.

clear() on RecordStore<U> MUST also clear the extras slab, retaining its allocated capacity.

sort_by_pos and dedup MUST be available on RecordStore<U> for any U. Each SlimRecord carries an extras_idx field that indexes into the extras slab, so reordering or removing records does not invalidate the extras mapping. Dead extras entries from dedup are left in place (minor waste, same as dead slab data for names, cigar, etc.).

The pileup engine MUST NOT use Rc for record sharing. PileupAlignment carries pre-extracted flat fields (base, qual, mapq, flags, etc.), and ActiveRecord stores a record index into the store. The store is either owned by or borrowed by the engine for the duration of iteration.