feat!: N-team outcome prediction with draw mass, replacing the 2-team panic

`predict_outcome` asserted `teams.len() == 2` and returned `[p, 1 - p]`,
allocating no probability to a draw even with `p_draw > 0`. For a
draw-enabled model the numbers were simply wrong, at any team count.

It now returns `Result<Prediction, InferenceError>` and supports N teams.

Two algorithms, both deterministic:

- Who finishes first. Performances are independent Gaussians, so this
  separates into a one-dimensional integral per team rather than a
  multivariate orthant probability. Adaptive Gauss-Kronrod evaluates it
  to ~1e-15, matching the exact two-team closed form.
- A specific finishing order. The factor graph only constrains
  rank-adjacent teams, so a full order is a chain of local constraints,
  not a general orthant integral. That chain collapses into a sequential
  recursion over cumulative integrals: O(teams * grid) per order.

Fixed-node Gauss-Hermite is the obvious tool for the first and is a trap:
when a rival's sigma is small the CDF product becomes a step narrower
than the node spacing, and the nodes step over it. Measured 4.4e-4 off
the closed form on a mildly skewed matchup and 1.7e-2 on a small-sigma
one, while still returning something that looks like a probability.
Adaptive refinement is what makes that case safe, and
`win_probabilities_survive_a_rival_with_a_tiny_sigma` pins it down.

The acceptance test is an identity rather than a golden: the outcome
space is exhaustive and disjoint, so the probabilities sum to one. Any
drift is integration error and nothing else. Gauss-Hermite failed it at
4.4e-4; this holds to ~1e-9.

Also from #21: unknown keys are now reported rather than dropped, so a
team of strangers can no longer produce a confident-looking prediction.
`predict_quality` returns `Result` for the same reason.

BREAKING CHANGE: `predict_outcome` returns `Result<Prediction, _>`
instead of `Vec<f64>`; `predict_quality` returns `Result<f64, _>`.

Refs #21, #39

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011hcFjNDmHXZF8URGLku5zZ

tests/prediction.rs

@@ -0,0 +1,214 @@
+//! Prediction API: N-team outcomes, draw mass, and the error paths that used
+//! to be panics or silent wrong answers.
+
+use trueskill_tt::{History, InferenceError, MAX_PREDICTED_TEAMS};
+
+fn history_with(names: &[&'static str], p_draw: f64) -> History {
+    let mut h = History::builder().p_draw(p_draw).build();
+    // Give every competitor a recorded skill by playing a small round robin.
+    for pair in names.windows(2) {
+        h.record_winner(&pair[0], &pair[1], 1).unwrap();
+    }
+    h.converge().unwrap();
+    h
+}
+
+#[test]
+fn unknown_keys_are_reported_not_silently_dropped() {
+    let h = history_with(&["a", "b"], 0.0);
+
+    let err = h
+        .predict_outcome(&[&[&"a"], &[&"ghost"]])
+        .expect_err("an unknown key must not yield a confident prediction");
+    assert_eq!(err, InferenceError::UnknownKey { team: 1, member: 0 });
+
+    // Every prediction entry point, not just one.
+    assert!(
+        h.predict_win_probabilities(&[&[&"a"], &[&"ghost"]])
+            .is_err()
+    );
+    assert!(h.predict_quality(&[&[&"a"], &[&"ghost"]]).is_err());
+    assert!(h.predict_ranking(&[&[&"a"], &[&"ghost"]], &[0, 1]).is_err());
+}
+
+#[test]
+fn an_entirely_unknown_team_is_an_error() {
+    let h = history_with(&["a", "b"], 0.0);
+    let err = h.predict_outcome(&[&[&"a"], &[&"x", &"y"]]).unwrap_err();
+    assert_eq!(err, InferenceError::UnknownKey { team: 1, member: 0 });
+}
+
+#[test]
+fn degenerate_team_shapes_are_errors_rather_than_panics() {
+    let h = history_with(&["a", "b"], 0.0);
+
+    assert_eq!(
+        h.predict_outcome(&[&[&"a"]]).unwrap_err(),
+        InferenceError::NotEnoughTeams { got: 1 }
+    );
+    assert_eq!(
+        h.predict_outcome(&[]).unwrap_err(),
+        InferenceError::NotEnoughTeams { got: 0 }
+    );
+    assert_eq!(
+        h.predict_outcome(&[&[&"a"], &[]]).unwrap_err(),
+        InferenceError::EmptyTeam { team: 1 }
+    );
+}
+
+#[test]
+fn more_than_two_teams_no_longer_panics() {
+    let h = history_with(&["a", "b", "c"], 0.0);
+    let p = h
+        .predict_outcome(&[&[&"a"], &[&"b"], &[&"c"]])
+        .expect("three teams must be supported");
+    assert!((p.total() - 1.0).abs() < 1e-6, "total = {}", p.total());
+    // Three teams, no draws possible: exactly the six strict orderings.
+    assert_eq!(p.outcomes().len(), 6);
+}
+
+#[test]
+fn the_outcome_space_is_capped_rather_than_hanging() {
+    let names: Vec<&'static str> = vec!["a", "b", "c", "d", "e", "f", "g", "h"];
+    let h = history_with(&names, 0.0);
+
+    let teams: Vec<&[&&'static str]> = Vec::new();
+    let _ = teams;
+
+    let too_many: Vec<Vec<&&str>> = names.iter().map(|n| vec![n]).collect();
+    let refs: Vec<&[&&str]> = too_many.iter().map(Vec::as_slice).collect();
+
+    let err = h.predict_outcome(&refs).unwrap_err();
+    assert_eq!(
+        err,
+        InferenceError::TooManyTeams {
+            got: 8,
+            max: MAX_PREDICTED_TEAMS
+        }
+    );
+
+    // The cheap paths stay available at any size.
+    let wins = h.predict_win_probabilities(&refs).unwrap();
+    assert_eq!(wins.len(), 8);
+    assert!(
+        (wins.iter().sum::<f64>() - 1.0).abs() < 1e-6,
+        "win probabilities must still sum to one: {wins:?}"
+    );
+}
+
+/// The defect that made every draw-enabled prediction wrong: `[p, 1 - p]`
+/// allocated no mass to a draw even with `p_draw > 0`.
+#[test]
+fn a_draw_carries_probability_mass_when_p_draw_is_positive() {
+    let h = history_with(&["a", "b"], 0.25);
+    let p = h.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap();
+
+    let draw = p.probability_of(&[0, 0]);
+    assert!(draw > 0.0, "a draw-enabled model must give draws mass");
+    assert!((p.total() - 1.0).abs() < 1e-6, "total = {}", p.total());
+
+    let wins = p.win_probabilities();
+    assert!(
+        (wins.iter().sum::<f64>() + draw - 1.0).abs() < 1e-6,
+        "wins {wins:?} plus draw {draw} must be the whole space"
+    );
+    assert!(
+        (p.shared_first_place() - draw).abs() < 1e-12,
+        "a two-team draw is a shared first place"
+    );
+}
+
+#[test]
+fn a_zero_draw_probability_admits_no_ties() {
+    let h = history_with(&["a", "b"], 0.0);
+    let p = h.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap();
+    assert_eq!(p.probability_of(&[0, 0]), 0.0);
+    assert!(p.shared_first_place() < 1e-12);
+}
+
+/// The two routes to a win probability run through entirely different
+/// algorithms — adaptive quadrature versus the enumerated chain recursion —
+/// so agreement between them is a real cross-check, not a tautology.
+#[test]
+fn the_cheap_and_exhaustive_paths_agree() {
+    for p_draw in [0.0, 0.1] {
+        let h = history_with(&["a", "b", "c"], p_draw);
+        let teams: &[&[&&str]] = &[&[&"a"], &[&"b"], &[&"c"]];
+
+        let cheap = h.predict_win_probabilities(teams).unwrap();
+        let exhaustive = h.predict_outcome(teams).unwrap().win_probabilities();
+
+        for (i, (a, b)) in cheap.iter().zip(&exhaustive).enumerate() {
+            assert!(
+                (a - b).abs() < 1e-6,
+                "p_draw={p_draw} team {i}: quadrature {a} vs enumeration {b}"
+            );
+        }
+    }
+}
+
+#[test]
+fn predict_ranking_agrees_with_the_distribution() {
+    let h = history_with(&["a", "b", "c"], 0.1);
+    let teams: &[&[&&str]] = &[&[&"a"], &[&"b"], &[&"c"]];
+    let dist = h.predict_outcome(teams).unwrap();
+
+    for (ranks, expected) in dist.outcomes() {
+        let direct = h.predict_ranking(teams, ranks).unwrap();
+        assert!(
+            (direct - expected).abs() < 1e-9,
+            "ranks {ranks:?}: {direct} vs {expected}"
+        );
+    }
+}
+
+#[test]
+fn predict_ranking_checks_its_shape() {
+    let h = history_with(&["a", "b"], 0.0);
+    let err = h
+        .predict_ranking(&[&[&"a"], &[&"b"]], &[0, 1, 2])
+        .unwrap_err();
+    assert!(matches!(
+        err,
+        InferenceError::MismatchedShape {
+            expected: 2,
+            got: 3,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn the_stronger_competitor_is_favoured() {
+    let mut h = History::builder().build();
+    for t in 1..=10 {
+        h.record_winner(&"strong", &"weak", t).unwrap();
+    }
+    h.converge().unwrap();
+
+    let p = h.predict_outcome(&[&[&"strong"], &[&"weak"]]).unwrap();
+    let (best, _) = p.most_likely().expect("a most likely outcome");
+    assert_eq!(best, &[0, 1], "the winner should be favoured");
+
+    let wins = p.win_probabilities();
+    assert!(wins[0] > wins[1], "{wins:?}");
+}
+
+/// Unequal team sizes change the draw margin, because inference derives it
+/// from the teams' betas. Prediction has to follow, or it describes a
+/// different model than the one that will be fitted.
+#[test]
+fn team_size_affects_the_prediction() {
+    let mut h = History::builder().p_draw(0.2).build();
+    h.event(1)
+        .team(["a", "b"])
+        .team(["c"])
+        .winner(0)
+        .commit()
+        .unwrap();
+    h.converge().unwrap();
+
+    let p = h.predict_outcome(&[&[&"a", &"b"], &[&"c"]]).unwrap();
+    assert!((p.total() - 1.0).abs() < 1e-6, "total = {}", p.total());
+    assert!(p.probability_of(&[0, 0]) > 0.0);
+}