feat!: keep nuc/MSP/FIRE calls on hard-clipped alignments, drop only their m6A, never panic

[mrvollger]

Fixes #136. Third round of the same class (#31 in 2023, the BamChunk guard narrowing in 2025, #136 now), so this PR is built to end it, not only to stop the panic.

Cause

Aligners that hard-clip supplementary alignments (minimap2 and dorado aligner without -Y) copy the full-length read's tags onto the clipped record. ft fire sliced SEQ with those coordinates and panicked; ft extract printed misplaced positions for forward reads and u32-wrapped ones for reverse reads; ft convert-tags wrote them into an MA tag.

The design

MA-family annotations (nuc, msp, fire, fiberseq_callable) are molecular coordinates of the full read, so on a hard-clipped record they are still correct. Only the liftover has to know that SEQ starts H_lead bases into that frame. MM/ML encode positions as skips over specific bases, so without the clipped bases they cannot be recovered.

Frame rule, decided from the record before anything is parsed (ma_io::record_frame):

• MA read length equal to SEQ plus both hard clips: full-read frame. Keep the tag as is, lift with the offset, drop MM/ML.
• MA read length equal to SEQ: clipped frame, tags computed after clipping. Lift as before; the MA tag vouches for the MM/ML next to it. If an MN tag disagrees with SEQ anyway, only the base mods are dropped.
• Legacy ns/nl/as/al on any hard clip: full-read frame, read length taken as SEQ plus clips (no producer writes them after clipping). Without SEQ, stale.
• Anything else that matches neither SEQ nor the full read: stale, annotations dropped, record kept, every stale tag stripped on write.
• SEQ-less records are judged by their CIGAR query span, so a SEQ-less supplementary with a full-read MA tag still gets the offset lift.

Liftover. AlignedBlocks in molecular-annotation carries a query offset; from_record sets it from the rule above; reference lifts subtract it and SEQ-relative projections (ft center) subtract it too. The reverse-strand flip already uses the tag's read length, so both strands come out right with no special case. pyMA mirrors the rule in pysam_utils.from_record and set_aligned_blocks(query_offset=).

No m6A means NotCallable. ft fire cannot score these reads and writes them back unscored; add-nucleosomes and footprint skip them; qc counts them; pileup --callable-fibers excludes them from FIRE denominators. Default pileup counts them in coverage exactly as it counts any Untagged read today.

Writers. In the full-read frame the MA tag is rewritten with the full read length and MM/ML/MN are stripped, so a second run over ft's own output is silent. write_record_with_basemods now writes MN, the SAM spec's frame for MM/ML, so ft predict-m6a, ft ddda-to-m6a and ft strip-basemods output carries the signal other tools use to detect a later hard clip. That adds one tag to those outputs for everyone; it is the one judgement call here.

Telling the user. One warning per run, only when m6A is actually dropped, plus a total at exit:

WARN some hard-clipped records carry Fiber-seq tags computed on the full-length read (supplementary alignments; the aligner copied them from the primary). Their nucleosome/MSP/FIRE calls are kept and lifted with the hard-clip offset; their m6A (MM/ML) describes bases this record does not carry and was dropped, so these reads are not fiberseq-callable. Realign with soft clipping: pbmm2 align (PacBio; it never hard-clips), dorado aligner --mm2-opts "-Y", or minimap2 -Y -y. Or drop supplementary alignments with -F 2048.
WARN kept nucleosome/MSP calls on 3 hard-clipped records whose Fiber-seq tags describe the full-length read; they have no m6A and are not fiberseq-callable. Realign with soft clipping: ...

Stale records get a parallel pair of messages. ft qc says the same instead of suggesting ft add-nucleosomes. README and the input BAM --help text state the requirement. The old guard in bio_io.rs that deleted hard-clipped MM/ML records outright is gone.

Breaking

• Hard-clipped supplementary alignments now keep their nucleosome/MSP/FIRE calls, lifted correctly, and lose only m6A. Before, ft fire panicked or passed stale tags through, ft extract printed wrong coordinates, and records with MM/ML were deleted from output with a per-record warning.
• extract --all reports fiber_length in the annotation frame (the full read on such records), matching the molecular columns and molecular-mode BED12.
• MM/ML producers write MN.
• molecular-annotation: AlignedBlocks::with_query_offset, MolecularAnnotations::query_offset, hard_clips, query_span, full_read_query_offset; pyMA set_aligned_blocks gains query_offset.

Tests

• molecular-annotation: liftover with an offset, forward and reverse, and from_record in every frame. pyMA: TestFullReadFrame.
• ma_io.rs unit tests for each branch of the frame rule, the legacy assignment, the callable marker, MN disagreement, SEQ-less hard clips, and the writers.
• Fixtures: ont_hardclip_supplementary.bam (legacy tags, dorado shape), ont_hardclip_mmml.bam (MM/ML/MN copied, no MA, the plain minimap2 shape: stale), and new ont_hardclip_full_frame.bam (MA-tagged primaries plus forward and reverse hard-clipped supplementaries with expected reference coordinates computed independently with pysam).
• Regression tests on those for extract (molecular and lifted coordinates, fiber_length), fire (kept calls, stripped MM/ML, silent second run), convert-tags, qc (NotCallable counts), pileup (nucleosome coverage includes them, FIRE coverage does not under --callable-fibers), center, and add-nucleosomes.

Follow-ups (separate PRs)

• ft qc: a distinct row for full-frame and stale-frame reads rather than folding into NotCallable/Untagged.
• ft validate: report hard-clipped records and their frames.
• The fibertools book's ONT quick start should say -Y and why; the bug template should ask for the alignment command.
• Found while testing: MM without ML panics in the MM/ML parser.
• Full-frame reads and default pileup coverage: decide whether to skip them there too.

Order

Merge into main after #149 and #141 (both merged). release-plz refreshes the 0.14.0 release PR #152 with this entry marked breaking; molecular-annotation goes to 0.0.4 in the same release.

Reviewed by three adversarial agent panels (46, 45 and 36 agents); the last one's confirmed findings are in the final commit.