feat!: name the unknown key, expose tail probabilities, flag short fits

Three issues from two downstream consumers, all small, all sharing a
theme: the crate had the information and would not hand it over.

#44 — `UnknownKey { team: 0, member: 0 }` did not say which key. A
consumer upgrading 0.1.2 -> 0.4.1 had every one of 5591 predictions
return this error, fell back to a neutral 0.5, and lost its entire
metadata model for a day. Nothing crashed and nothing logged; it was
found by sweeping an unrelated parameter and noticing the output did not
move. The 0.4.0 change that made unknown keys an error was right — the
error was just too anonymous to act on. It now carries the key's `Debug`
rendering, and its `Display` says what to do about it. The precondition
is documented on every prediction entry point, which the reporter said
would alone have saved the day.

#43 — `cdf` was `pub(crate)`, so a consumer asking "is this competitor
below the cutoff" approximated it with a `mu + z * sigma` band and had no
way to say what confidence any `z` bought. Adds
`Gaussian::probability_below` / `probability_above`. The second is
separate on purpose: `1 - cdf` collapses to exactly zero past ~8.3
sigma, and a stopping rule is evaluated precisely there. Both route
through the survival function added in 0.4.1, so this is visibility
rather than new numerics.

#50 — `ConvergenceReport` was not `#[must_use]`, so the one signal that
a fit stopped short was trivially discarded. It now is, and that
immediately found 78 sites doing exactly that — including this crate's
own ATP example, which was capped at 10 sweeps when the history needs
30. The example now reads the report and says so.

`ITERATIONS = 30` is documented as the floor it is, with the three
measurements to hand: 400 events over 100 competitors already stops
there at ~7e-3 against a 1e-6 tolerance, the ATP example needs 30 at a
much looser one, and a consumer's 2000-node model needs 76 to 161.

BREAKING CHANGE: `InferenceError::UnknownKey` gains a `key` field, and
the prediction methods now require `K: Debug` in order to fill it.

Closes #43, #50. Refs #44 — its third ask, an opt-in `UnknownKeys::Skip`
mode, is a live API question and deliberately not answered here.

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

tests/api_shape.rs

@@ -65,7 +65,7 @@ fn add_events_draw() {
         outcome: Outcome::draw(2),
     }];
     h.add_events(events).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 }
 
 #[test]
@@ -123,7 +123,7 @@ fn fluent_event_builder_winner_convenience() {
         .winner(0)
         .commit()
         .unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 }
 
 #[test]
@@ -141,7 +141,7 @@ fn fluent_event_builder_draw() {
         .draw()
         .commit()
         .unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 }
 
 #[test]
@@ -155,7 +155,7 @@ fn current_skill_and_learning_curve() {
         .build();
     h.record_winner(&"a", &"b", 1).unwrap();
     h.record_winner(&"a", &"b", 2).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let a = h.current_skill(&"a").unwrap();
     assert!(a.mu() > 25.0);
@@ -201,7 +201,7 @@ fn predict_quality_two_teams() {
         .p_draw(0.0)
         .build();
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let q = h.predict_quality(&[&[&"a"], &[&"b"]]).unwrap();
     assert!(q > 0.0 && q <= 1.0);
@@ -217,7 +217,7 @@ fn predict_outcome_two_teams_sums_to_one() {
         .p_draw(0.0)
         .build();
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let p = h.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap();
     let wins = p.win_probabilities();
@@ -245,7 +245,7 @@ fn fluent_event_builder_scores() {
         .scores([12.0, 4.0])
         .commit()
         .unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let a = h.current_skill(&"alice").unwrap();
     let b = h.current_skill(&"bob").unwrap();

tests/competitor_config.rs

@@ -64,13 +64,13 @@ fn a_prior_applies_to_a_new_competitor() {
     let mut with = history();
     with.add_events(vec![bout("a", "b", 0, Some(seeded), None)])
         .unwrap();
-    with.converge().unwrap();
+    let _ = with.converge().unwrap();
 
     let mut without = history();
     without
         .add_events(vec![bout("a", "b", 0, None, None)])
         .unwrap();
-    without.converge().unwrap();
+    let _ = without.converge().unwrap();
 
     assert!(
         (skill_of(&with, "a").mu() - skill_of(&without, "a").mu()).abs() > 1.0,
@@ -91,7 +91,7 @@ fn a_prior_applies_to_a_competitor_the_history_already_knows() {
     // "a" now exists. Configuring it here used to do nothing whatsoever.
     late.add_events(vec![bout("a", "b", 1, Some(seeded), None)])
         .unwrap();
-    late.converge().unwrap();
+    let _ = late.converge().unwrap();
 
     let mut never = history();
     never
@@ -100,7 +100,7 @@ fn a_prior_applies_to_a_competitor_the_history_already_knows() {
             bout("a", "b", 1, None, None),
         ])
         .unwrap();
-    never.converge().unwrap();
+    let _ = never.converge().unwrap();
 
     assert!(
         (skill_of(&late, "a").mu() - skill_of(&never, "a").mu()).abs() > 1.0,
@@ -122,7 +122,7 @@ fn a_prior_is_whole_history_scoped_not_per_event() {
         .unwrap();
     late.add_events(vec![bout("a", "b", 1, Some(seeded), None)])
         .unwrap();
-    late.converge().unwrap();
+    let _ = late.converge().unwrap();
 
     let mut early = history();
     early
@@ -131,7 +131,7 @@ fn a_prior_is_whole_history_scoped_not_per_event() {
             bout("a", "b", 1, Some(seeded), None),
         ])
         .unwrap();
-    early.converge().unwrap();
+    let _ = early.converge().unwrap();
 
     let (l, e) = (skill_of(&late, "a"), skill_of(&early, "a"));
     assert!(
@@ -150,7 +150,7 @@ fn repeating_the_same_prior_is_inert() {
         bout("a", "b", 1, None, None),
     ])
     .unwrap();
-    once.converge().unwrap();
+    let _ = once.converge().unwrap();
 
     let mut every_time = history();
     every_time
@@ -159,7 +159,7 @@ fn repeating_the_same_prior_is_inert() {
             bout("a", "b", 1, Some(seeded), None),
         ])
         .unwrap();
-    every_time.converge().unwrap();
+    let _ = every_time.converge().unwrap();
 
     let (o, e) = (skill_of(&once, "a"), skill_of(&every_time, "a"));
     assert!(
@@ -203,7 +203,7 @@ fn setting_one_field_late_leaves_the_other_alone() {
     // Only the scale this time — the prior above must survive.
     h.add_events(vec![bout("a", "b", 1, None, Some(0.5))])
         .unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let mut both_upfront = history();
     both_upfront
@@ -212,7 +212,7 @@ fn setting_one_field_late_leaves_the_other_alone() {
             bout("a", "b", 1, None, None),
         ])
         .unwrap();
-    both_upfront.converge().unwrap();
+    let _ = both_upfront.converge().unwrap();
 
     let (a, b) = (skill_of(&h, "a"), skill_of(&both_upfront, "a"));
     assert!(

tests/degenerate_inputs.rs

@@ -351,7 +351,7 @@ fn zero_weight_does_not_produce_a_non_finite_posterior() {
         .commit()
         .expect("a zero weight is accepted today; update this test if that changes");
 
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     assert_curve_finite(&h, &["a", "b"], "zero weight");
 }
@@ -368,7 +368,7 @@ fn negative_weight_does_not_produce_a_non_finite_posterior() {
         .commit()
         .expect("a negative weight is accepted today; update this test if that changes");
 
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     assert_curve_finite(&h, &["a", "b"], "negative weight");
 }
@@ -389,7 +389,7 @@ fn out_of_order_timestamps_converge_to_the_same_answer() {
             h.record_winner(&"a", &"b", time).unwrap();
         }
 
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
         h
     }
 
@@ -416,7 +416,7 @@ fn extreme_beta_and_sigma_stay_finite() {
 
         h.record_winner(&"a", &"b", 1).unwrap();
         h.record_winner(&"a", &"b", 2).unwrap();
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
 
         assert_curve_finite(&h, &["a", "b"], &format!("beta={beta} sigma={sigma}"));
     }

tests/determinism.rs

@@ -47,7 +47,7 @@ fn build_and_converge(seed: u64) -> Vec<(i64, trueskill_tt::Gaussian)> {
         });
     }
     h.add_events(events).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
     // Sample one competitor's curve for the comparison.
     h.learning_curve("p0")
 }

tests/drift_scale.rs

@@ -58,7 +58,7 @@ fn fit(events: Vec<Event<i64, &'static str>>, gamma: f64) -> Fit {
         .build();
 
     h.add_events(events).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
     h
 }
 
@@ -385,7 +385,7 @@ fn drift_scale_applies_when_set_after_first_appearance() {
         outcome: Outcome::winner(1, 2),
     }])
     .unwrap();
-    late.converge().unwrap();
+    let _ = late.converge().unwrap();
 
     let applied = curve(&late, "anchor");
     let pinned_from_the_start = curve(&fit(distant_pair(Some(0.0)), 25.0 / 300.0), "anchor");

tests/filtered.rs

@@ -47,7 +47,7 @@ fn tight() -> ConvergenceOptions {
 fn filtered_evidence_sits_between_coin_flip_and_batch() {
     let mut history = repeated_winner(5);
 
-    history.converge().unwrap();
+    let _ = history.converge().unwrap();
 
     let coin_flip = 5.0 * 0.5f64.ln();
     let batch = history.log_evidence();
@@ -71,7 +71,7 @@ fn filtered_evidence_sits_between_coin_flip_and_batch() {
 fn filtered_first_point_is_less_certain_than_smoothed() {
     let mut history = repeated_winner(12);
 
-    history.converge().unwrap();
+    let _ = history.converge().unwrap();
 
     let smoothed = history.learning_curve("a");
     let filtered = history.filtered_learning_curve("a");
@@ -121,7 +121,7 @@ fn filtered_first_point_is_less_certain_than_smoothed() {
 fn filtered_curves_plural_agrees_with_singular() {
     let mut history = repeated_winner(4);
 
-    history.converge().unwrap();
+    let _ = history.converge().unwrap();
 
     let curves = history.filtered_learning_curves();
 
@@ -180,7 +180,7 @@ fn single_slice_filtered_matches_smoothed() {
         ])
         .unwrap();
 
-    history.converge().unwrap();
+    let _ = history.converge().unwrap();
 
     let smoothed = history.learning_curve("a");
     let filtered = history.filtered_learning_curve("a");
@@ -223,13 +223,13 @@ fn filtered_curves_do_not_depend_on_ingestion_order() {
 
     let mut batched = History::builder().convergence(tight()).build();
     batched.add_events(all.clone()).unwrap();
-    batched.converge().unwrap();
+    let _ = batched.converge().unwrap();
 
     let mut incremental = History::builder().convergence(tight()).build();
     for event in all {
         incremental.add_events([event]).unwrap();
     }
-    incremental.converge().unwrap();
+    let _ = incremental.converge().unwrap();
 
     let from_batched = batched.filtered_learning_curve("a");
     let from_incremental = incremental.filtered_learning_curve("a");

tests/large_history_converges_finite.rs

@@ -46,7 +46,7 @@ fn nan_after_fit(players: usize) -> usize {
         let (w, l) = if rng.coin() { (a, b) } else { (b, a) };
         h.record_winner(&ids[w], &ids[l], 0).unwrap();
     }
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     ids.iter()
         .filter(|id| {

tests/observer.rs

@@ -42,7 +42,7 @@ fn every_observer_callback_fires() {
     h.record_winner(&"a", &"b", 1).unwrap();
     h.record_winner(&"b", &"c", 2).unwrap();
     h.record_winner(&"c", &"a", 3).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     assert!(
         !recorder.iterations.lock().unwrap().is_empty(),
@@ -65,7 +65,7 @@ fn slice_callbacks_report_the_slice_they_swept() {
 
     h.record_winner(&"a", &"b", 10).unwrap();
     h.record_winner(&"a", &"b", 20).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let slices = recorder.slices.lock().unwrap();
 
@@ -93,7 +93,7 @@ fn a_single_slice_history_still_reports_its_sweep() {
     let mut h = History::builder().observer(Arc::clone(&recorder)).build();
 
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let slices = recorder.slices.lock().unwrap();
     assert!(
@@ -112,7 +112,7 @@ fn a_shared_observer_reaches_the_callers_handle() {
     let mut h = History::builder().observer(Arc::clone(&recorder)).build();
 
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     assert!(!recorder.iterations.lock().unwrap().is_empty());
     assert!(!recorder.slices.lock().unwrap().is_empty());
@@ -125,12 +125,12 @@ fn a_trait_object_observer_works() {
     let boxed: Box<dyn Observer<i64>> = Box::new(Recorder::default());
     let mut h = History::builder().observer(boxed).build();
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let shared: Arc<dyn Observer<i64>> = Arc::new(Recorder::default());
     let mut h = History::builder().observer(Arc::clone(&shared)).build();
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 }
 
 /// A non-shared observer can be reclaimed after convergence instead.
@@ -138,7 +138,7 @@ fn a_trait_object_observer_works() {
 fn into_observer_returns_the_accumulated_state() {
     let mut h = History::builder().observer(Recorder::default()).build();
     h.record_winner(&"a", &"b", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     // Readable in place...
     assert!(!h.observer().iterations.lock().unwrap().is_empty());
@@ -155,7 +155,7 @@ fn a_borrowed_observer_works() {
     {
         let mut h = History::builder().observer(&recorder).build();
         h.record_winner(&"a", &"b", 1).unwrap();
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
     }
     assert!(!recorder.iterations.lock().unwrap().is_empty());
 }

tests/prediction.rs

@@ -9,7 +9,7 @@ fn history_with(names: &[&'static str], p_draw: f64) -> History {
     for pair in names.windows(2) {
         h.record_winner(&pair[0], &pair[1], 1).unwrap();
     }
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
     h
 }
 
@@ -20,7 +20,14 @@ fn unknown_keys_are_reported_not_silently_dropped() {
     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 });
+    assert_eq!(
+        err,
+        InferenceError::UnknownKey {
+            team: 1,
+            member: 0,
+            key: "\"ghost\"".to_owned(),
+        }
+    );
 
     // Every prediction entry point, not just one.
     assert!(
@@ -35,7 +42,14 @@ fn unknown_keys_are_reported_not_silently_dropped() {
 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 });
+    assert_eq!(
+        err,
+        InferenceError::UnknownKey {
+            team: 1,
+            member: 0,
+            key: "\"x\"".to_owned(),
+        }
+    );
 }
 
 #[test]
@@ -184,7 +198,7 @@ fn the_stronger_competitor_is_favoured() {
     for t in 1..=10 {
         h.record_winner(&"strong", &"weak", t).unwrap();
     }
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let p = h.predict_outcome(&[&[&"strong"], &[&"weak"]]).unwrap();
     let (best, _) = p.most_likely().expect("a most likely outcome");
@@ -206,7 +220,7 @@ fn team_size_affects_the_prediction() {
         .winner(0)
         .commit()
         .unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let p = h.predict_outcome(&[&[&"a", &"b"], &[&"c"]]).unwrap();
     assert!((p.total() - 1.0).abs() < 1e-6, "total = {}", p.total());
@@ -229,7 +243,7 @@ fn information_gain_prefers_the_uncertain_pairing() {
         h.record_winner(&"rival", &"known", t + 100).unwrap();
     }
     h.record_winner(&"known", &"newcomer", 500).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let settled = h
         .expected_information_gain(&[&[&"known"], &[&"rival"]])
@@ -271,7 +285,11 @@ fn information_gain_reports_unknown_keys() {
     assert_eq!(
         h.expected_information_gain(&[&[&"a"], &[&"ghost"]])
             .unwrap_err(),
-        InferenceError::UnknownKey { team: 1, member: 0 }
+        InferenceError::UnknownKey {
+            team: 1,
+            member: 0,
+            key: "\"ghost\"".to_owned(),
+        }
     );
 }
 
@@ -289,3 +307,33 @@ fn information_gain_accounts_for_draws() {
     let dist = with_draws.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap();
     assert!(dist.probability_of(&[0, 0]) > 0.0);
 }
+
+/// The defect that cost a consumer a day: `UnknownKey { team: 0, member: 0 }`
+/// says nothing about *which* key is unknown, so the natural handling — log it,
+/// fall back to a neutral value — converts a total miss into a plausible
+/// constant. The key has to be in the error, and in its `Display`.
+#[test]
+fn unknown_key_names_the_key_it_could_not_find() {
+    let h = history_with(&["a", "b"], 0.0);
+    let err = h.predict_outcome(&[&[&"a"], &[&"never_seen"]]).unwrap_err();
+
+    match &err {
+        InferenceError::UnknownKey { key, .. } => {
+            assert!(
+                key.contains("never_seen"),
+                "the error should name the key, got {key}"
+            );
+        }
+        other => panic!("expected UnknownKey, got {other:?}"),
+    }
+
+    let rendered = err.to_string();
+    assert!(
+        rendered.contains("never_seen"),
+        "Display should name the key: {rendered}"
+    );
+    assert!(
+        rendered.contains("pre-filter"),
+        "Display should say what to do about it: {rendered}"
+    );
+}

tests/properties.rs

@@ -61,7 +61,7 @@ proptest! {
     fn converged_posteriors_are_always_finite(games in pairs()) {
         let mut h = history_from(&games);
 
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
 
         for key in KEYS {
             for (time, g) in h.learning_curve(key) {
@@ -79,7 +79,7 @@ proptest! {
     fn log_evidence_is_a_finite_log_probability(games in pairs()) {
         let mut h = history_from(&games);
 
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
 
         let batch = h.log_evidence();
         let filtered = h.filtered_log_evidence();
@@ -98,7 +98,7 @@ proptest! {
 
         let before = h.filtered_log_evidence();
 
-        h.converge().unwrap();
+        let _ = h.converge().unwrap();
 
         let after = h.filtered_log_evidence();
 
@@ -114,7 +114,7 @@ proptest! {
     fn ingestion_order_does_not_change_the_answer(games in pairs()) {
         let batched = {
             let mut h = history_from(&games);
-            h.converge().unwrap();
+            let _ = h.converge().unwrap();
             h
         };
 
@@ -139,7 +139,7 @@ proptest! {
                 .unwrap();
             }
 
-            h.converge().unwrap();
+            let _ = h.converge().unwrap();
             h
         };
 

tests/quality.rs

@@ -108,7 +108,7 @@ fn history_predict_quality_supports_three_teams() {
     let mut h = History::default();
     h.record_winner(&"a", &"b", 1).unwrap();
     h.record_winner(&"b", &"c", 2).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let q = h.predict_quality(&[&[&"a"], &[&"b"], &[&"c"]]).unwrap();
     assert!(

tests/record_winner.rs

@@ -15,7 +15,7 @@ fn record_winner_builds_history() {
         .build();
 
     h.record_winner(&"alice", &"bob", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     let a_idx = h.lookup(&"alice").unwrap();
     let b_idx = h.lookup(&"bob").unwrap();
@@ -48,7 +48,7 @@ fn record_draw_with_p_draw_set() {
         .build();
 
     h.record_draw(&"alice", &"bob", 1).unwrap();
-    h.converge().unwrap();
+    let _ = h.converge().unwrap();
 
     assert!(h.lookup(&"alice").is_some());
     assert!(h.lookup(&"bob").is_some());