fix(index): position-bin placed-but-unmapped reads in the BAI

[tfenne]

What & why

A read with the UNMAPPED flag but a valid reference and position — the common "mate mapped, self unmapped" record, which carries its mate's tid/pos so it coordinate-sorts alongside its mate — was dropped from the BAI entirely: no bin, no chunk, no linear-index entry. htslib/samtools position-bin such reads, so region queries and idxstats over a fgumi index silently missed them (a "fetch everything in this window" would lose the unmapped mates, and the idxstats unmapped column disagreed with samtools).

What it does

extract_alignment_context now returns a binning context for any read that has a reference and position, binning it over a 1-base [pos, pos+1) span when it has no CIGAR (matching htslib's bam_endpos = pos + max(rlen, 1)); only a read with no reference/position is treated as unplaced. The is_mapped flag still records the read as unmapped, so it isn't miscounted as mapped — it just becomes queryable, matching htslib. Normal mapped reads (CIGAR span ≥ 1) bin identically to before, so the blast radius is limited to placed-unmapped reads.

This changes .bai content for both index paths (the pooled sort writer and IndexingBamWriter), which is the intent: both now match samtools on content.

Validation

• New unit test: a placed-but-unmapped record → binned over [pos, pos+1) with is_mapped=false; a mapped read → its CIGAR span; a truly-unplaced read → unplaced.
• The samtools cross-check (test_sort_write_index_matches_samtools_index) now compares ALL reads (dropping the previous -F 4 mapped-only workaround) and full idxstats — and matches.
• Full suite green: cargo ci-fmt, cargo ci-lint (clippy pedantic), and all tests including the samtools-gated ones.

Stacked on #650 (BAI compaction); merge that first.

Summary by CodeRabbit

• Bug Fixes
  • Improved BAM indexing for reads marked as unmapped but containing valid reference positions.
  • These reads are now included in the appropriate genomic regions and represented with their correct mapping status.
  • Corrected indexing for records without CIGAR-derived reference spans by treating them as covering one base.
  • Region queries and index statistics now more closely match samtools results, including placed-but-unmapped reads.

[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 Plus

Run ID: e7768404-0efc-4f2f-a034-f2edc1e52a9c

📥 Commits

Reviewing files that changed from the base of the PR and between 50372a6 and e35d4ca.

📒 Files selected for processing (2)

• crates/fgumi-bam-io/src/writer.rs
• tests/integration/test_sort_write_index.rs

---

Walkthrough

Placed-but-unmapped reads with valid coordinates are now indexed over a one-base span, while truly unplaced reads remain excluded. Unit and integration tests verify exact region records and full idxstats parity with samtools.

Changes

BAM indexing behavior

Layer / File(s)	Summary
Alignment context and unit coverage crates/fgumi-bam-io/src/writer.rs	Positioned reads are binned regardless of the UNMAPPED flag; mapping status is preserved, zero-length spans become one base, and unit tests cover mapped, placed-unmapped, and unplaced records.
Index query parity tests/integration/test_sort_write_index.rs	Integration tests compare exact region-query records and complete idxstats output between fgumi and samtools.
Estimated code review effort: 3 (Moderate)	~20 minutes

Possibly related PRs

• fulcrumgenomics/fgumi#647: Related BAI indexing refactor and --write-index test updates.

Suggested reviewers: nh13

🚥 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 accurately summarizes the main change: BAI indexing now position-bins placed-but-unmapped reads.
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 tf_bai_placed_unmapped

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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.57%. Comparing base (50372a6) to head (e35d4ca).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #651   +/-   ##
=======================================
  Coverage   93.57%   93.57%           
=======================================
  Files         175      175           
  Lines      106764   106803   +39     
=======================================
+ Hits        99904    99944   +40     
+ Misses       6860     6859    -1     

☔ 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.

[nh13]

Thank-you @tfenne!!!