Phase 3: write-path correctness, CRAM-writer hardening, contract docs

[mbreese]

Summary

Third QC pass, covering valid-input correctness and cross-implementation consistency that Phases 1–2 (cosmetic cleanups; malformed-input hardening) didn't address. Theme continues the prior phases: turn silent corruption/loss into explicit errors, and make SAM/BAM/CRAM behave consistently.

Write-path error handling

• BAM encodeRecord now checks the return of every variable-length write (name/cigar/seq/qual/aux) — previously only the fixed fields were checked, so a mid-stream I/O error was silently swallowed and the writer kept emitting onto a failed sink.
• Propagate the final gzip flush error in CRAM encodeBlock, and the gzip Close error in the SAM text reader's Close.

CRAM writer correctness & contract

• Close() is now idempotent (matches BAM): a double-close no longer writes a second EOF container or double-closes the file; Write after Close errors.
• New htsio.CigarQueryLen / htsio.ValidateCigarSeq; the CRAM writer rejects a record whose CIGAR query length ≠ SEQ length instead of silently dropping inserted/soft-clipped bases (it reconstructs SEQ from the CIGAR). The BAM writer stores SEQ verbatim, so it intentionally stays lenient.
• Copy WriterOpts at construction so caller mutation can't change writer behavior mid-stream.
• Clarifying comment on the RR flag (investigated — confirmed correct).

Concurrency audit (verify-then-fix)

The sorted BAM writer and parallel BGZF writer were reviewed and confirmed race-free (go test -race clean) and leak-free — no code changes needed. Documented the Semaphore.Close() contract. (Reporting this explicitly so the "no change" is a deliberate, verified outcome, not an omission.)

API contracts

Aligned and documented Close() semantics (idempotent, flushes, writes trailer) across all three writers — the SAM writer is now idempotent too — and documented SamReader's single-pass / shared-header / freshly-allocated-record semantics on the interface.

Tests

CIGAR query-length + validation; CRAM double-Close, write-after-close, CIGAR/SEQ-mismatch rejection; BAM mismatch leniency + failing-sink error propagation; SAM double-Close idempotency.

Verification

go build ./..., go vet ./..., go test ./... all green (with samtools 1.21), plus go test -race clean on the bgzf/bam/ontcmd/align packages.

🤖 Generated with Claude Code