Rename Outcome -> EffectCandidate; document purpose; drop description field

[iskandr]

Re-creating PR #380, which auto-closed when its base branch (#379's generic-phasing-api) was deleted on merge. Rebased onto current main.

Summary

Three cleanups on the multi-outcome wrapper:

1. Rename Outcome → EffectCandidate. The class wraps an Effect with provenance — "candidate effect with metadata" reads honestly. Module varcode.outcomes → varcode.effect_candidates; helper outcomes_from_candidates → candidates_from_effects; test file renamed in lockstep.

2. Drop EffectCandidate.description. Pure passthrough to effect.short_description; producers wanting a richer narrative attach it to the underlying Effect, not the wrapper. make_rna_outcome(description=...) kwarg also removed.

3. Module docstring explains why the wrapper exists. Previously framed as "minimal type for unifying multi-outcome shapes" with the actual rationale buried. Now leads with: the same MutationEffect instance can appear in multiple multi-outcome contexts with different metadata per context (e.g. a splice candidate re-surfaced by the SV annotator with a different source tag and sv_type in evidence). Without the wrapper, the alternatives are copy-everywhere, metadata-on-Effect (wrong: forces one labeling across contexts), or sidecar id() dicts. Documents that the wrapper is the cheapest answer.

Also: scrub aspirational "isovar" / "exacto" / "longread_assembly" example tags from varcode docstrings — those integrations don't exist yet; naming them as canonical examples implied a dependency that hadn't shipped.

What didn't change

• MultiOutcomeEffect.candidates and .outcomes are kept as two complementary first-class accessors (raw tuple[MutationEffect, ...] vs wrapped tuple[EffectCandidate, ...]). The misleading "back-compat for 2.x" framing on .candidates is dropped — both serve distinct, legitimate needs.

  I tried collapsing to a single accessor (.candidates returning wrapped, .effects for raw) and reverted. The migration broke ~30 splice/RNA tests because SpliceOutcomeSet.candidates has deep history of returning SpliceCandidate (a different domain-specific type) and serialization round-trips depend on the shape. Collapsing requires either widespread test migration or back-compat shims that defeat the cleanup. Kept the pragmatic landing — documented sharply.

Test plan

• pytest tests/ — 1188 pass, 2 pre-existing skips.
• New test pins pytest.raises(TypeError) on the removed description= kwarg so it can't slip back via copy/paste.
• tests/test_outcomes.py → tests/test_effect_candidates.py (git rename + test method names updated test_outcome_* → test_effect_candidate_*).
• No remaining Outcome or outcomes_from_candidates references anywhere.
• No "isovar" / "exacto" / "longread_assembly" strings in varcode source.

References

• Supersedes Rename Outcome -> EffectCandidate; document its purpose #380 (auto-closed by Generalize phasing API; remove Isovar-named identifiers #379's base-branch deletion).
• Unified MultiOutcomeEffect / OutcomeSet generalization across splice, readthrough, germline, and RNA evidence #299 — original Outcome introduction (whose "harmonized interface" framing this PR replaces).
• Generalize phasing API; remove Isovar-named identifiers #379 — generic phasing API (merged; this PR builds on the cleanup pattern).