feat(bam-io): unify the single-threaded raw-BAM reader onto fgumi-bgzf (#800)

[nh13]

Closes #800. Supersedes #801 (auto-closed when its base branch 786/nhomer/perf-bgzf-crc-skip was deleted by the #798 squash-merge; GitHub cannot reopen a PR whose base branch was deleted). Same head branch, rebased onto main — the one now-redundant doc commit dropped as already upstream, leaving the single substantive change.

Problem

fgumi-bam-io had two BGZF decoder stacks. The single-threaded raw-BAM reader (create_raw_bam_reader[_with_opts]) decoded via noodles-bgzf, which always verifies CRC32 and has no skip knob — so the --check-crc/--no-check-crc policy from #798 (backed by our own fgumi-bgzf) never reached the single-threaded fast paths, and PipelineReaderOpts.verify_crc was a dead carrier field.

Change

Add FgumiBgzfReader, a safe streaming Read/BufRead adapter over fgumi-bgzf's read_raw_blocks + decompress_block_into_opts (no unsafe; one block decoded per refill, so a CRC/size error is tied to the bytes the caller actually reads), and route the single-threaded raw reader through it via a new BgzfReaderEnum::Fgumi arm. PipelineReaderOpts.verify_crc is now live.

Coverage after this change (--check-crc/--no-check-crc):

• clip/codec/duplex/simplex/downsample — honored single- or multi-threaded (their single-threaded reader now decodes through fgumi-bgzf).
• correct/group — honored only with --threads N; their single-threaded mode reads through create_bam_reader_for_pipeline_with_opts + a manual noodles decode, so they keep the noodles path (help text says so).
• threads > 1 still uses noodles' multithreaded decoder (a threaded fgumi-bgzf raw reader is out of scope).

fgumi-sort and extract have their own reader stacks and remain follow-ups.

Tests

TDD: the reader-level verify_crc test (corrupted-CRC file accepted with verify_crc=false, rejected with true) was written first and confirmed red against the noodles path before implementing. Plus a multi-block roundtrip test (exercises block-boundary buffering) and three end-to-end downsample CRC tests (--no-check-crc accepts a corrupted file; default and --check-crc reject it). The reader also gains a sticky-poison test: after a mid-stream decode failure both read and fill_buf stay in error. All 228 fgumi-bam-io + fgumi-bgzf tests green on the rebased tree.

[coderabbitai]

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6fa17c4e-3436-4c07-992a-afe05525ba95

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[nh13]

@coderabbitai pause

[codecov]

Codecov Report

❌ Patch coverage is 95.87302% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.46%. Comparing base (e51dc4b) to head (c222506).

Files with missing lines	Patch %	Lines
crates/fgumi-bam-io/src/reader.rs	95.10%	12 Missing ⚠️
src/lib/commands/clip.rs	83.33%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #842    +/-   ##
========================================
  Coverage   94.46%   94.46%            
========================================
  Files         187      187            
  Lines      115301   115597   +296     
========================================
+ Hits       108921   109201   +280     
- Misses       6380     6396    +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.

[coderabbitai]

✅ Action performed

Reviews paused.