fix: recompute the BAM bin field after raw POS/CIGAR mutations (clip, zipper)

[nh13]

Summary

fgumi clip (and, in a narrower case, fgumi zipper) emitted a stale BAM bin field. The raw pipelines mutate an already-encoded BAM record in place and write the bytes verbatim, so — unlike the noodles/htsjdk encoders, which recompute the indexing bin on write — there is no serialization step to refresh bin (bytes 10–11) after POS or the CIGAR changes. Any clip that moved a read into a different bin shipped the pre-clip value, diverging from fgbio.

Reproduction

A read placed at 16300 with 200M straddles the 16 kb bin boundary (level-4 bin 585). A 116-base 5′ soft-clip moves it to pos 16416, 116S84M, whose correct bin is 4682:

Tool	resulting alignment	bin
fgbio ClipBam	pos 16417, 116S84M	4682 ✓
fgumi clip (before)	pos 16417, 116S84M	585 ✗ (stale)

The same class of bug affected zipper's mate reconciliation: a read relocated to its mapped mate's coordinate kept the stale unmapped bin (4680) instead of its placed position's bin.

Note: fgumi's own BAI/CSI writer recomputes start/end from POS+CIGAR and ignores the record's bin, so its own index was unaffected. The stale bin hurt external consumers (htsjdk/samtools-based tools reading fgumi output) and broke byte-parity with fgbio.

What changed

• fgumi-raw-bam::bin (new module): the canonical SAM spec §5.3 reg2bin, the UNMAPPED_BIN constant, and bin_from_raw_bam / set_bin_from_raw_bam, which compute a record's bin from its POS and CIGAR reference span (unmapped POS < 0 → 4680, keying off the alignment start like htsjdk computeIndexingBin, not the unmapped flag). Plus a RawRecord::recompute_bin() wrapper.
• clip: recompute the bin at the three raw mutation primitives (clip_start_of_alignment, clip_end_of_alignment, make_read_unmapped_raw) so a clipped record is always self-consistent, and in set_mate_info_raw when a clipped-unmapped read is relocated or a pair is cleared to unmapped. upgrade_clipping only converts clip type (no POS/span move), so it correctly needs no recompute.
• zipper (Template::fix_mate_info): recompute after relocating an unmapped mate to its mate's coordinate and after clearing a pair to unmapped.
• simulate: region_to_bin now delegates to the shared reg2bin instead of duplicating the spec code; the private UNMAPPED_BIN in builder.rs also shares the constant.

Testing

• Unit tests at every mutation site (clip start/end/unmap, set_mate_info_raw relocation, fix_mate_info relocation), each asserting the emitted bin equals reg2bin of the post-op coordinates — TDD, each written failing first.
• reg2bin is covered by the full authoritative vector table ported from htsjdk GenomicIndexUtilTest.testRegionToBinDataProvider, exercising every binning level (16 kb through the whole-window bin 0).
• End-to-end: rebuilt binary re-run on the reproductions above — every previously-stale case now matches reg2bin of the post-op coordinates, and directly matches fgbio ClipBam / ZipperBams output bins.
• Full workspace suite (5243 tests), cargo ci-fmt, and cargo ci-lint all pass.

Reading order

1. crates/fgumi-raw-bam/src/bin.rs — the shared helper and its semantics.
2. crates/fgumi-sam/src/clipper.rs and src/lib/commands/clip.rs — the clip fix.
3. src/lib/template.rs — the zipper fix.
4. src/lib/commands/simulate/mod.rs — the delegation refactor.

Summary by CodeRabbit

• New Features

  • Added BAM bin calculation and update support based on alignment position and CIGAR span.
  • Added APIs to compute or refresh bins for raw BAM records.
  • Added automatic bin updates when clipping reads or modifying mate information.

• Bug Fixes

  • Prevented stale bin values after coordinate, CIGAR, or mapping-status changes.
  • Correctly handles unmapped and zero-reference-span reads.

• Tests

  • Added coverage for bin boundaries, clipping, unmapped reads, and coordinate mutations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a2f8bd2d-da4d-4d41-a05a-8c4ac457fb94

📥 Commits

Reviewing files that changed from the base of the PR and between 602fd60 and c65673e.

📒 Files selected for processing (8)

• crates/fgumi-raw-bam/src/bin.rs
• crates/fgumi-raw-bam/src/builder.rs
• crates/fgumi-raw-bam/src/lib.rs
• crates/fgumi-raw-bam/src/raw_bam_record.rs
• crates/fgumi-sam/src/clipper.rs
• src/lib/commands/clip.rs
• src/lib/commands/simulate/mod.rs
• src/lib/template.rs

---

Walkthrough

Changes

BAM bin calculation is centralized in fgumi-raw-bam, exported publicly, and applied after raw POS/CIGAR or mate-coordinate mutations. Clipping, mate fixing, template updates, and simulated-region binning now maintain consistent bin values, with boundary and unmapped cases covered by tests.

BAM bin recomputation

Layer / File(s)	Summary
Shared bin calculation contract crates/fgumi-raw-bam/src/bin.rs, crates/fgumi-raw-bam/src/builder.rs, crates/fgumi-raw-bam/src/lib.rs	Adds SAM-compatible reg2bin, raw BAM bin extraction and in-place writing, exports the APIs, and centralizes UNMAPPED_BIN.
RawRecord bin refresh crates/fgumi-raw-bam/src/raw_bam_record.rs	Adds RawRecord::recompute_bin and tests updates after POS, CIGAR, and unmapped-state mutations.
Raw clipping updates crates/fgumi-sam/src/clipper.rs	Recomputes bins after start clipping, end clipping, and conversion to unmapped records, with boundary tests.
Coordinate update integrations src/lib/commands/clip.rs, src/lib/commands/simulate/mod.rs, src/lib/template.rs	Refreshes bins after mate relocation or unmapping and delegates simulated region binning to the shared implementation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RawMutation
  participant RawRecord
  participant BinAPI
  participant BAMBytes
  RawMutation->>RawRecord: change POS, CIGAR, or mapping state
  RawRecord->>BinAPI: recompute current raw record bin
  BinAPI->>BAMBytes: write little-endian bin bytes
  BAMBytes-->>RawRecord: updated BAM bin

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: recomputing BAM bin fields after raw POS/CIGAR mutations.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nh/fix-stale-bam-bin

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.02%. Comparing base (f577f55) to head (c65673e).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #591      +/-   ##
==========================================
- Coverage   93.03%   93.02%   -0.01%     
==========================================
  Files         167      168       +1     
  Lines      103266   103429     +163     
==========================================
+ Hits        96070    96217     +147     
- Misses       7196     7212      +16     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.