Annotate alternative uORF frames and initiation-context mutations alongside canonical UTR effects #583

Variants confined to the canonical 5-prime UTR currently receive FivePrimeUTR in effect_prediction.py and transcript_layout.py, even when they alter an experimentally supported upstream ORF. A uORF start loss, missense, frameshift or stop loss needs its own transcript/ORF-specific consequence alongside the canonical label. Likewise +4 can change both initiation context and a coding residue.

Proposed organization

Keep four independent layers:

1. Model identity: assembly, transcript + version/release, ORF ID, ordered coding blocks, start/stop positions and reference sequence.
2. Location: start-context positions (A of ATG = +1, no zero), start codon, coding body, stop codon, and splice path. Roles can overlap.
3. Sequence consequence: reference/alternate codons and proteins, start gained/lost/changed, synonymous/missense/stop gained/lost, frame change, and altered splice products. A start-codon loss does not prove translation absence; alternative/near-cognate initiation remains a hypothesis. Kozak context is a loose positional prior, never an exclusion criterion or calibrated probability.
4. Evidence: published Ribo-seq/MS mapped to the exact reference model/residues, patient RNA support, and observed mutant translation/HLA presentation. Missing evidence stays unknown. Native peptides cannot validate a new fusion tail. Downstream main-CDS regulation remains unassessed unless independently modeled.

Clean API and dependency direction

Add a small ORFModel / ORFModelProvider protocol or neutral JSON interchange in Varcode (or a shared lower-level package), without introducing a Varcode -> Isovar dependency. Isovar's offline catalogue can supply models/evidence to that protocol. Model lookups must pin assembly/annotation and resolve the entire spliced coding path + sequence, rather than transfer evidence by gene or unversioned transcript ID alone.

Expose additive per-ORF annotation (for example variant.orf_effects(provider=...)), preserving existing canonical effects. Return every compatible ORF and transcript outcome; retain model IDs in collection identity and export. Reuse the existing transcript-layout, MutantTranscript and effect-hypothesis pipeline with an explicit alternative ORF frame rather than a second annotation engine.

Implementation order / acceptance criteria

1. REF-validated SNVs/MNVs and indels in supplied ORF models; genomic forward-strand alleles converted into transcript orientation. Include separate Kozak/context annotations and permit partial/missing positions. +4 has both context and coding effects.
2. Translate affected coding paths, preserving start/stop/frame uncertainty and incomplete downstream sequence. Explicitly identify altered protein intervals and retained native intervals. Report unsupported events as unresolved, not generic silent/noncoding results.
3. Recompute contexts/frames on realized splice, fusion and rearranged transcript products using existing hypothesis machinery; retain source placements and unknown bases. Compose patient germline/somatic haplotypes and phased edits before translation. Separate model-supported starts from newly created sequence-only candidates.
4. Add start-gain discovery around changed sequence with explicit search bounds and unavailable/full-scan status; don't infer no uORF from an empty reference catalogue.
5. Export lossless JSON with model/source pins, reference/alternate products, alternative hypotheses, evidence overlays and why an annotation is unresolved.

Tests should cover minus strand, a start codon/context spanning exons, partial Kozak context, ATG at the first three supplied bases with unverified biological 5-prime completeness, REF mismatch, +4 dual effects, start/stop loss, frameshifts, splice/fusion products, ambiguous phase and compatible isoforms with conflicting effects.

Existing work and primary sources

Isovar #468 adds pinned reference initiation contexts, loose per-position preferences and REF-validated context SNVs: openvax/isovar#468
The evidence catalogue shipped in Isovar #467: openvax/isovar#467
Compose with Varcode #423 and #574 rather than creating an independent uncertainty/export path.

Primary sources:

• Mudge et al. 2022, GENCODE noncanonical ORF models: https://doi.org/10.1038/s41587-022-01369-0
• Kozak 1986, experimentally measured initiation-context effects: https://doi.org/10.1016/0092-8674(86)90762-2
• Kozak 1987, vertebrate initiation consensus: https://doi.org/10.1093/nar/15.20.8125
• Kozak 1991, short leaders and AUG bypass: https://pubmed.ncbi.nlm.nih.gov/1820208/