genome: --genomeTransformOutput SAM reports original coordinates

[BenjaminDEMAILLE]

--genomeTransformOutput SAM: report alignments in the original genome's coordinates.

What changed

--genomeTransformType Haploid bakes a VCF's variants into the genome sequence, so reads carrying those alleles align without mismatches. The price is that every reported coordinate then refers to a genome nobody else has. This pays it back.

Three steps, STAR's order (Transcript_transformGenome.cpp):

1. Remap. Each exon goes through the conversion blocks written at build time, split wherever it straddles a boundary — the two halves land at unrelated original coordinates.
2. Merge. Splits that are seamless in the original genome collapse again, and an uneven gap has its shared part folded into the neighbouring exon. What survives as a gap is a real indel, so an indel baked into the sequence reappears as an I/D CIGAR operation.
3. Reclassify. Junction motifs and annotation flags are recomputed against the original genome. A junction canonical in the transformed genome need not be canonical in the original, and STAR reports what the original says.

GenomeIndex gains transform_out, loaded only when the flag is set: the untransformed genome from OriginalGenome/, its annotated junctions, and the parsed block map. A missing OriginalGenome/ or transformGenomeBlocks.tsv is an error, not a fallback — falling back would report transformed coordinates while claiming they are original.

Where the conversion happens, and why it matters

Transcripts are converted immediately after alignment, before anything reads them, so records, junction counts and statistics share one coordinate space. Converting at the writer instead would leave SJ.out.tab and the counters describing a genome the SAM file does not.

The SAM header comes from the original genome as well. Original coordinates under transformed reference lengths would produce a file no downstream tool could read correctly.

A paired result converts as a unit: if one mate fails to convert the pair is dropped whole, rather than reported as a half-mapped read that never existed. Insert size is recomputed from the converted mates, since the transform can change the distance between them.

What is refused rather than half-done

--genomeTransformOutput SJ and Quant are unimplemented and rejected. So are the combinations whose other outputs would remain in transformed space: --quantMode, --soloType, --outWigType. A file mixing the two coordinate spaces is worse than no file.

Verification

End to end (test_genome_transform_output_sam_reports_original_coordinates): a genome with a 5-base deletion at position 5001, one read at 6000. Without the flag the reported POS is 5996; with it, 6001 — the original coordinate — and the CIGAR is unchanged, since the read spans no variant.

Unit tests in src/genome/transform_align.rs:

• an exon inside one block is shifted by that block
• an exon straddling a boundary comes back out as 10M5D10M
• a seamless split is merged back
• soft clips are carried through
• a junction motif is read from the original genome
• a junction canonical only in the transformed genome becomes non-canonical
• a gap shorter than --alignIntronMin stays a deletion
• an alignment outside the block map is dropped rather than guessed at

Plus block_map_round_trips_through_the_tsv and a malformed-header rejection.

Gate: 571 lib + 22 integration tests, cargo clippy --all-targets -- -D warnings, cargo fmt --check, MSRV 1.89 — all green.

Output-neutral unless the flag is passed: output_genome() returns the searched genome when there is no transform, so every existing run takes the same path it did.

Output neutrality, measured

10k yeast SE reads (CONTRIBUTING's dataset) through this branch and through origin/main, both at default flags: the SAM records are byte-identical (9724 each; the two files differ only in the @PG CL: line, which records the binary path).

Split out of #109 following the one-theme rule in CONTRIBUTING.md; that PR keeps the libsais suffix-array builder.