Owned BAM Record

CIGAR operations MUST be represented as a typed CigarOp struct with an op: CigarOpType field (using the existing CigarOpType enum defined in r[io.typed_cigar_ops]) and a len: u32 field. Conversion to/from the BAM packed u32 format (len << 4 | op_code) MUST be provided.

The qname (without NUL terminator) MUST NOT exceed 254 bytes. The l_read_name field in the BAM 32-byte header is a u8 that stores the length including NUL, so the maximum stored length is 255. The builder and to_bam_bytes MUST reject qnames exceeding this limit with a typed error.

BamRecord MUST support replacing the alignment by setting a new pos and cigar simultaneously. For mapped reads (flags & 0x4 == 0), the implementation MUST validate that the CIGAR's query-consuming length equals seq.len(), returning an error on mismatch. For unmapped reads (flags & 0x4 != 0), a zero-operation CIGAR with non-empty seq MUST be allowed.

BamRecord MUST provide an aligned_pairs() iterator yielding (Option<usize>, Option<i64>) tuples: (query_pos, ref_pos). The iterator handles each CIGAR operation as follows:

• M/=/X (alignment match, sequence match, mismatch): both values are Some, one tuple per base.
• I (insertion to reference): ref_pos = None, one tuple per inserted base.
• D (deletion from reference): query_pos = None, one tuple per deleted base.
• N (reference skip / intron): query_pos = None, one tuple per skipped reference base. N consumes reference but not query, like D. This is important for RNA-seq BAMs where introns appear as N operations spanning thousands of reference bases.
• S (soft clip): MUST be skipped entirely. Soft-clipped bases are present in the sequence but not aligned to the reference.
• H (hard clip): MUST be skipped entirely. Hard-clipped bases are not present in the sequence.
• P (padding): MUST be skipped entirely. Padding is used for padded-reference alignment and consumes neither query nor reference.

BamRecord MUST provide end_pos() -> i64 computing the rightmost reference position from pos + CIGAR reference-consuming operations. This uses the same logic as r[bam.record.end_pos], but MUST be recomputed from the current CIGAR state (not cached from a stale value).

BamRecord MUST serialize to BAM binary format by appending into a caller-provided &mut Vec<u8> (the method appends; clearing the buffer is the caller's responsibility — see r[bam_writer.reuse_buffers]). The layout MUST follow [SAM1] §4.2: 32-byte fixed fields (refID, pos, bin_mq_nl, flag_nc, l_seq, next_refID, next_pos, tlen), NUL-terminated qname, packed CIGAR (u32 per op), 4-bit packed sequence, quality scores, and raw auxiliary bytes. The method MUST NOT include the 4-byte block_size prefix — that is the caller's (writer's) responsibility, since the caller needs to know the total byte count to write the prefix.

The BAM binary format stores pos and next_pos as i32, and ref_id and next_ref_id as i32. The BamRecord stores pos and next_pos as i64 for internal flexibility (e.g., arithmetic without overflow risk). to_bam_bytes MUST validate that pos is in [-1, i32::MAX] and next_pos is in [-1, i32::MAX], returning a typed error on overflow. The value -1 is the canonical sentinel for unmapped/unavailable. This validation catches bugs where CIGAR-based position calculations produce values exceeding the BAM coordinate space.

The BAM bin value in the serialized bin_mq_nl field MUST be computed from the current pos and end_pos at serialization time, not stored as a persistent field. This ensures the bin is always consistent with the current alignment, even after modification.

AuxData MUST store auxiliary tags in BAM binary format (packed bytes). Tag lookup via get() MUST delegate to the existing aux::find_tag implementation (see r[bam.record.aux_parse]). Mutation methods MUST be provided:

• set_string(tag, value) — add or replace a Z-type string tag
• set_int(tag, value: i64) — add or replace an integer tag
• set_float(tag, value) — add or replace an f-type float tag
• set_array_u8(tag, values) — add or replace a B:C array tag
• remove(tag) — remove a tag if present
• as_bytes() -> &[u8] — raw bytes for serialization

Tag names MUST be unique within a record (per [SAM1] §1.5). set_* methods MUST enforce this: if a tag with the given name already exists, it MUST be replaced, not duplicated. get() MUST be unambiguous.

set_int(tag, value: i64) MUST auto-select the smallest BAM integer type that fits the value. For values where both signed and unsigned types could apply (e.g. 42 fits in both i8 and u8), the unsigned type MUST be preferred — this matches htslib behavior and produces more compact encodings for the common case of non-negative values. The selection order is:

1. Non-negative values: C (u8, 0..=255), S (u16, 256..=65535), I (u32, 65536..=2^32-1)
2. Negative values: c (i8, -128..=-1), s (i16, -32768..=-129), i (i32, -2^31..=-32769)

Values outside the union of i32 and u32 ranges MUST return a typed error — BAM auxiliary tags have no 64-bit integer type per [SAM1] §4.2.5.

set_array_u8(tag, values) MUST encode the tag in BAM B-type array format: 2-byte tag name, type byte B, subtype byte C, 4-byte little-endian element count, followed by the raw u8 values. This is used for the ML (modification likelihood) tag in SAM 4.5 methylation annotations.

When extracting a record from RecordStore, the auxiliary data MUST be copied verbatim from the data slab into AuxData. No parsing or re-encoding is needed — the slab already stores tags in BAM binary format.