refactor!: close the remaining API gaps from #21

Three unrelated small defects, all requiring signature changes:

- `Game::one_v_one` hardcoded `GameOptions::default()`, so a 1v1 could
  never set `p_draw` or convergence options — and a drawn 1v1 was
  therefore unreachable through it, since the default `p_draw` is zero.
  It now takes `&GameOptions` like every other constructor.

- `Observer::on_batch_processed` was declared on the trait and never
  called from anywhere: implementors wired up a callback that could not
  fire. It is now called after each slice sweep, and renamed
  `on_slice_processed` to match the vocabulary the codebase adopted in
  T2 — the unit of work is a `TimeSlice`, not a batch. A slice is swept
  once travelling backward and once forward, so a multi-slice history
  fires it twice per slice per iteration; the doc comment says so.

- `pub mod factors` sat beside `pub(crate) mod factor`, two module paths
  differing by one character with only one of them importable. The
  public facade is now `graph`.

Tests cover each as a behaviour rather than a compile check: a drawn 1v1
succeeds only when p_draw is supplied, and the observer tests fail if
any callback stops firing.

BREAKING CHANGE: `Game::one_v_one` takes a fourth `&GameOptions`
argument; `Observer::on_batch_processed` is renamed
`on_slice_processed`; the `factors` module is renamed `graph`.

Closes #21

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

.gitignore

@@ -7,3 +7,4 @@
 NOTEPAD.md
 
 /.claude
+proptest-regressions/

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.3.0 - 2026-09-01
+
+### Breaking Changes
+
+- refactor!: make Competitor::message an Option, and compute_elapsed loud
+- refactor!: replace emptiness-as-sentinel with Option for results and weights
+- refactor!: remove ConvergenceReport::slices_skipped
+
+### Bug Fixes
+
+- fix: enforce EventBuilder weight/team length in release
+
+### Documentation
+
+- docs: complete the public API documentation contract
+
+### Features
+
+- feat: allow drift to vary per competitor via Member::with_drift_scale
+
+### Miscellaneous Tasks
+
+- chore: ignore proptest regression seed files
+
+### Performance
+
+- perf: stop cloning inference inputs in OwnedGame and ingestion
+- perf: make the per-slice SkillStore compact instead of dense
+
+### Testing
+
+- test: add property-based tests, a shared finiteness helper, and boundary inputs
+
 ## 0.2.0 - 2026-08-27
 
 ### Breaking Changes
@@ -36,6 +69,7 @@ All notable changes to this project will be documented in this file.
 - chore: target releases at the private kellnr registry
 - chore: keep the 48 MB ATP dataset out of the published crate
 - chore: dual-license MIT OR Apache-2.0
+- chore: Release trueskill-tt version 0.2.0
 
 ### Performance
 

CLAUDE.md

@@ -32,10 +32,19 @@ evidence both forward and backward across a history.
 
 ### Data flow
 
+Ingestion (public types, `event.rs`):
+
 ```
-History  →  TimeSlice[]  →  Event[]  →  Team[] → Item[]
+Event<T, K>  →  Team<K>[]  →  Member<K>[]
-                                  ↓
+```
-                     Game (factor graph) → Schedule → BuiltinFactor[]
+
+`History::add_events` flattens that into indices; teams survive only as
+grouping, not as a value. Inference then runs on the internal shapes:
+
+```
+History  →  TimeSlice[]  →  Event[]  →  Item[]
+                                ↓
+                   Game (factor graph) → Schedule → BuiltinFactor[]
 ```
 
 - **`History`** (`history.rs`) — top level. Interns keys, groups events into
@@ -45,9 +54,12 @@ History  →  TimeSlice[]  →  Event[]  →  Team[] → Item[]
 - **`TimeSlice`** (`time_slice.rs`) — all events at one time. Owns a
   `SkillStore` and a `ScratchArena`; `iteration()` sweeps its events, using
   `ColorGroups` to partition independent ones.
-- **`Event`** (`time_slice.rs`) — one match. `compute()` runs inference reading
+- **`Event`** — two distinct types, do not confuse them. The *public* ingestion
-  skills immutably; `apply()` folds the result back. The split is what lets a
+  `Event<T, K>` is in `event.rs` (with `Team`/`Member`); the *internal*
-  color group run in parallel with no `unsafe`.
+  `pub(crate) Event` in `time_slice.rs` is one match during inference, where
+  `compute()` runs inference reading skills immutably and `apply()` folds the
+  result back. That split is what lets a color group run in parallel with no
+  `unsafe`.
 - **`Game`** (`game.rs`) — a single match's factor graph. `run_chain` builds the
   diff chain between rank-adjacent teams and drives it to convergence.
 - **`Gaussian`** (`gaussian.rs`) — natural parameters (`pi = 1/sigma²`,
@@ -61,14 +73,16 @@ History  →  TimeSlice[]  →  Event[]  →  Team[] → Item[]
   the only implementation.
 - **`Competitor`** (`competitor.rs`) — per-history temporal state (`message`,
   `last_time`). **`Rating`** (`rating.rs`) — static config (prior, `beta`, drift).
-- **`storage/`** — `SkillStore` (per slice) and `CompetitorStore` (per history),
+- **`storage/`** — `SkillStore` (per slice, `pub(crate)`) and `CompetitorStore`
-  both dense `Vec`s indexed by `Index`.
+  (per history, public), both indexed by `Index`. The module is `pub`, but only
+  `CompetitorStore` is reachable from outside the crate.
 - **`KeyTable`** (`key_table.rs`) — user key ↔ `Index`, both directions O(1).
 - **`Drift`** (`drift.rs`) / **`Time`** (`time.rs`) — traits. `Time` is a *trait*
   (`i64`, `Untimed`), not an enum.
 - **`lib.rs`** — public exports, global defaults (`MU`, `SIGMA`, `BETA`,
-  `GAMMA`, `P_DRAW`, `EPSILON`, `ITERATIONS`), and the standalone `quality()`,
+  `GAMMA`, `P_DRAW`, `EPSILON`, `ITERATIONS`), and the standalone `quality()`.
-  `cdf()`, `erfc()`.
+  The `cdf()` / `erfc()` helpers live here too but are `pub(crate)` and private
+  respectively — not public API.
 
 ### Invariants worth knowing
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trueskill-tt"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 description = "TrueSkill Through Time: Bayesian skill rating that tracks how skill evolves over time, via Gaussian message passing"
@@ -62,9 +62,14 @@ rayon = ["dep:rayon"]
 criterion = "0.5"
 plotters = { version = "0.3", default-features = false, features = ["svg_backend", "all_elements", "all_series"] }
 plotters-backend = "0.3"
+proptest = "1.11.0"
 time = { version = "0.3", features = ["parsing"] }
 trueskill-tt = { path = ".", features = ["approx"] }
 
+# Debug symbols in release are for `just flame` (cargo-flamegraph), which needs
+# them to symbolicate. Profile settings in a library are ignored by downstream
+# consumers, so these only affect local builds — this is deliberate, not an
+# oversight.
 [profile.release]
 debug = true
 

README.md

@@ -13,64 +13,136 @@ Rust port of [TrueSkillThroughTime.py](https://github.com/glandfried/TrueSkillTh
 
 ## Drift
 
-Skill drift models how a player's true skill can change between appearances. Each time a player reappears after a gap, their skill uncertainty is widened by the drift model before the new evidence is incorporated.
+Skill drift models how a competitor's true skill can change between appearances.
+Each time they reappear after a gap, their skill uncertainty is widened by the
+drift model before the new evidence is incorporated.
 
-Drift is represented by the `Drift` trait:
+Drift is represented by the `Drift` trait (`src/drift.rs`), generic over the
+history's time type:
 
-```rust
+```text
-pub trait Drift: Copy + Debug {
+pub trait Drift<T: Time>: Copy + Debug + Send + Sync {
-    fn variance_delta(&self, elapsed: i64) -> f64;
+    fn variance_delta(&self, from: &T, to: &T) -> f64;
+    fn variance_for_elapsed(&self, elapsed: i64) -> f64;
 }
 ```
 
-`variance_delta` returns the amount to add to `σ²` given the elapsed time since the player last played. Internally, `Gaussian::forget` uses this to compute the new sigma: `σ_new = sqrt(σ² + variance_delta)`.
+Both methods return the amount to add to `σ²`, not to `σ`. `variance_delta`
+works from two timestamps; `variance_for_elapsed` takes an already-computed
+elapsed count, and is used on the paths that cache it. `Gaussian::forget`
+applies the result entirely in variance space — `from_mv(mu, variance() +
+variance_delta)` — taking no square root.
+
+That block is a quotation rather than a doctest. The custom-drift example below
+is compiled by CI, so it is what actually pins the signature.
 
 ### ConstantDrift
 
-The built-in `ConstantDrift` implements a linear random walk — skill uncertainty grows proportionally to time:
+The built-in `ConstantDrift` implements a linear random walk — skill uncertainty
+grows proportionally to time:
 
-```
+```text
 variance_delta = elapsed * γ²
 ```
 
-This is the standard TrueSkill Through Time model. Use it by passing a `ConstantDrift(gamma)` when constructing a `Player`:
+This is the standard TrueSkill Through Time model. Pass a `ConstantDrift(gamma)`
+when constructing a `Rating`:
 
 ```rust
-use trueskill_tt::{Player, Gaussian, drift::ConstantDrift};
+use trueskill_tt::{ConstantDrift, Gaussian, Rating};
 
-// gamma = 0.1 means skill can shift ~0.1 per time unit
+// gamma = 0.1 means skill can shift ~0.1 per time unit.
-let player = Player::new(Gaussian::from_ms(0.0, 6.0), 1.0, ConstantDrift(0.1));
+let rating: Rating<i64, ConstantDrift> =
+    Rating::new(Gaussian::from_ms(0.0, 6.0), 1.0, ConstantDrift(0.1));
+
+assert_eq!(rating.drift().0, 0.1);
 ```
 
+The type annotation is load-bearing: `ConstantDrift` implements `Drift<T>` for
+every `T: Time`, so without it `T` is ambiguous.
+
 ### Custom drift
 
-Implement `Drift` to express any other model. For example, a drift that saturates after a long absence (uncertainty grows with the square root of elapsed time instead of linearly):
+Implement `Drift<T>` to express any other model. For example, a drift that
+saturates after a long absence, with uncertainty growing as the square root of
+elapsed time instead of linearly:
 
 ```rust
-use trueskill_tt::drift::Drift;
+use trueskill_tt::{Drift, Gaussian, History, Rating, Time};
 
 #[derive(Clone, Copy, Debug)]
 struct SqrtDrift {
     gamma: f64,
 }
 
-impl Drift for SqrtDrift {
+impl<T: Time> Drift<T> for SqrtDrift {
-    fn variance_delta(&self, elapsed: i64) -> f64 {
+    fn variance_delta(&self, from: &T, to: &T) -> f64 {
-        (elapsed as f64).sqrt() * self.gamma * self.gamma
+        let elapsed = from.elapsed_to(to).max(0) as f64;
+        elapsed.sqrt() * self.gamma * self.gamma
+    }
+
+    fn variance_for_elapsed(&self, elapsed: i64) -> f64 {
+        (elapsed.max(0) as f64).sqrt() * self.gamma * self.gamma
     }
 }
 
-let player = Player::new(Gaussian::from_ms(0.0, 6.0), 1.0, SqrtDrift { gamma: 0.5 });
+// On a single Rating:
+let rating: Rating<i64, SqrtDrift> =
+    Rating::new(Gaussian::from_ms(0.0, 6.0), 1.0, SqrtDrift { gamma: 0.5 });
+
+// Or for a whole History, via the builder:
+let history = History::builder().drift(SqrtDrift { gamma: 0.5 }).build();
+
+assert_eq!(rating.beta(), 1.0);
+assert_eq!(history.log_evidence(), 0.0);
 ```
 
-To use a custom drift type with `History`, use the `.drift()` builder method instead of `.gamma()`:
+`HistoryBuilder::drift` is the only way to set a history's drift model; there is
+no `gamma()` shorthand. The default is `ConstantDrift(GAMMA)`.
+
+### Per-competitor drift
+
+A `History` has one drift model, but individual competitors can scale it.
+`Member::with_drift_scale(s)` multiplies the drift *variance* that competitor
+accumulates, so `s` is in the same units as `gamma`: `ConstantDrift(g)` at
+scale `s` behaves exactly as `ConstantDrift(g * s)` would, for that competitor
+alone.
+
+`0.0` pins a competitor still. That is what makes a **fixed reference point**
+expressible in the same graph as moving competitors — a bot at a known
+strength, a rating floor, a course difficulty:
 
 ```rust
-let h = History::builder()
+use trueskill_tt::{ConstantDrift, Event, History, Member, Outcome, Team};
-    .drift(SqrtDrift { gamma: 0.5 })
+
-    .build();
+let mut h = History::builder().drift(ConstantDrift(0.1)).build();
+
+h.add_events(vec![Event {
+    time: 0,
+    teams: [
+        Team::with_members([Member::new("player")]),
+        // A course does not improve. Pin it, and the round's evidence
+        // lands on the player instead of being split between the two.
+        Team::with_members([Member::new("layout_7").with_drift_scale(0.0)]),
+    ]
+    .into_iter()
+    .collect(),
+    outcome: Outcome::winner(0, 2),
+}])
+.unwrap();
+
+h.converge().unwrap();
 ```
 
+Like `with_prior`, the scale is **competitor configuration captured at first
+appearance** — setting it on a key the history already knows has no effect. It
+must be finite and non-negative; ingestion otherwise fails with
+`InferenceError::InvalidParameter`.
+
+Note that the fluent `EventBuilder` (`h.event(t).team([...])`) sets weights but
+not `drift_scale` or `prior`; those need the typed `Event` / `Team` / `Member`
+shape shown above.
+
 ## Scored outcomes
 
 Use `Outcome::scores([...])` when you have continuous per-team scores rather
@@ -80,7 +152,7 @@ soft Gaussian evidence about the latent performance diff. Configure
 (smaller σ = more trust).
 
 ```rust
-use trueskill_tt::{History, Outcome};
+use trueskill_tt::History;
 
 let mut h = History::builder().score_sigma(2.0).build();
 h.event(1)

benches/batch.rs

@@ -36,7 +36,7 @@ fn criterion_benchmark(criterion: &mut Criterion) {
     let kinds = vec![EventKind::Ranked; composition.len()];
 
     let mut time_slice = TimeSlice::new(1, P_DRAW, ConvergenceOptions::default());
-    time_slice.add_events(composition, results, weights, kinds, &agents);
+    time_slice.add_events(composition, Some(results), Some(weights), kinds, &agents);
 
     criterion.bench_function("Batch::iteration", |b| {
         b.iter(|| time_slice.iteration(0, &agents))

release.toml

@@ -3,4 +3,12 @@ publish = true
 # Hold off pushing until tags and publish have both succeeded; `just release`
 # pushes last.
 push = false
-pre-release-hook = ["sh", "-c", "git cliff -o CHANGELOG.md --tag {{version}} && git add CHANGELOG.md"]
+# Regenerate the changelog and stage it so it lands in the release commit.
+#
+# Guarded on DRY_RUN because cargo-release runs pre-release hooks during a dry
+# run too (verified against cargo-release 1.1.5, which exports DRY_RUN=true,
+# CRATE_NAME, PREV_VERSION and NEW_VERSION to the hook). Without the guard,
+# `just release-plan` — documented as a preview that writes nothing — writes and
+# `git add`s CHANGELOG.md, and the clean-tree check in `just release` then
+# refuses to run. That check is load-bearing: publishing is irreversible.
+pre-release-hook = ["sh", "-c", '[ "$DRY_RUN" = "true" ] || (git cliff -o CHANGELOG.md --tag {{version}} && git add CHANGELOG.md)']

src/competitor.rs

@@ -1,5 +1,4 @@
 use crate::{
-    N_INF,
     drift::{ConstantDrift, Drift},
     gaussian::Gaussian,
     rating::Rating,
@@ -8,12 +7,19 @@ use crate::{
 
 /// Per-history, temporal state for someone competing.
 ///
-/// Renamed from `Agent` in T2; the former `.player` field is now
+/// The mutable half of a competitor: `Rating` holds their static
-/// `.rating` to match the `Player → Rating` rename.
+/// configuration, this holds what inference learns as it sweeps.
 #[derive(Debug)]
 pub struct Competitor<T: Time = i64, D: Drift<T> = ConstantDrift> {
     pub rating: Rating<T, D>,
-    pub message: Gaussian,
+    /// The forward message carried from this competitor's last appearance, or
+    /// `None` before they have appeared anywhere.
+    ///
+    /// Previously an improper `N_INF` served as the unset sentinel, which made
+    /// "no message yet" indistinguishable from "a legitimately improper
+    /// message" at the type level and required every reader to know the
+    /// convention.
+    pub message: Option<Gaussian>,
     pub last_time: Option<T>,
 }
 
@@ -21,14 +27,16 @@ impl<T: Time, D: Drift<T>> Competitor<T, D> {
     /// Compute the message received at time `now`, with drift accumulated
     /// from `self.last_time` (if any) to `now`.
     pub(crate) fn receive(&self, now: &T) -> Gaussian {
-        if self.message != N_INF {
+        match self.message {
-            let elapsed_variance = match &self.last_time {
+            Some(message) => {
-                Some(last) => self.rating.drift.variance_delta(last, now),
+                let elapsed_variance = match &self.last_time {
-                None => 0.0,
+                    Some(last) => self.rating.drift_variance_delta(last, now),
-            };
+                    None => 0.0,
-            self.message.forget(elapsed_variance)
+                };
-        } else {
+
-            self.rating.prior
+                message.forget(elapsed_variance)
+            }
+            None => self.rating.prior,
         }
     }
 
@@ -37,11 +45,9 @@ impl<T: Time, D: Drift<T>> Competitor<T, D> {
     /// Used in convergence sweeps where the elapsed was cached at slice-construction time
     /// and should not be recomputed from `last_time` (which may have shifted).
     pub(crate) fn receive_for_elapsed(&self, elapsed: i64) -> Gaussian {
-        if self.message != N_INF {
+        match self.message {
-            self.message
+            Some(message) => message.forget(self.rating.drift_variance_for_elapsed(elapsed)),
-                .forget(self.rating.drift.variance_for_elapsed(elapsed))
+            None => self.rating.prior,
-        } else {
-            self.rating.prior
         }
     }
 }
@@ -50,7 +56,7 @@ impl Default for Competitor<i64, ConstantDrift> {
     fn default() -> Self {
         Self {
             rating: Rating::default(),
-            message: N_INF,
+            message: None,
             last_time: None,
         }
     }
@@ -63,7 +69,7 @@ where
     C: Iterator<Item = &'a mut Competitor<T, D>>,
 {
     for c in competitors {
-        c.message = N_INF;
+        c.message = None;
         if last_time {
             c.last_time = None;
         }

src/convergence.rs

@@ -38,7 +38,6 @@ pub struct ConvergenceReport {
     pub log_evidence: f64,
     pub converged: bool,
     pub per_iteration_time: SmallVec<[Duration; 32]>,
-    pub slices_skipped: usize,
 }
 
 #[cfg(test)]

src/error.rs

@@ -40,6 +40,24 @@ pub enum InferenceError {
     },
     /// Negative precision: a Gaussian with `pi < 0` slipped into an API call.
     NegativePrecision { pi: f64 },
+    /// A prediction referenced a key the history has no skill for.
+    ///
+    /// Reported rather than skipped: dropping unknown keys turns a team of
+    /// strangers into a confident-looking probability about nobody.
+    UnknownKey { team: usize, member: usize },
+    /// A prediction was given a team with no members.
+    EmptyTeam { team: usize },
+    /// Fewer than two teams were supplied to a prediction.
+    NotEnoughTeams { got: usize },
+    /// The full outcome distribution was requested for too many teams.
+    ///
+    /// Each realisation sorts into exactly one (order, tie-pattern) event, so
+    /// the space holds `n! * 2^(n-1)` members — 1_920 at five teams, 23_040 at
+    /// six, 322_560 at seven. Past `max` this stops being something to
+    /// enumerate on a caller's behalf; ask for individual rankings with
+    /// `predict_ranking`, or for `predict_win_probabilities`, both of which
+    /// stay cheap at any team count.
+    TooManyTeams { got: usize, max: usize },
 }
 
 impl fmt::Display for InferenceError {
@@ -90,6 +108,25 @@ impl fmt::Display for InferenceError {
             Self::NegativePrecision { pi } => {
                 write!(f, "precision must be non-negative; got {pi}")
             }
+            Self::UnknownKey { team, member } => {
+                write!(
+                    f,
+                    "team {team}, member {member}: no skill recorded for this key"
+                )
+            }
+            Self::EmptyTeam { team } => {
+                write!(f, "team {team} has no members")
+            }
+            Self::NotEnoughTeams { got } => {
+                write!(f, "prediction needs at least 2 teams, got {got}")
+            }
+            Self::TooManyTeams { got, max } => {
+                write!(
+                    f,
+                    "the outcome distribution over {got} teams is too large to enumerate (limit {max}); \
+                     use predict_ranking or predict_win_probabilities instead"
+                )
+            }
         }
     }
 }

src/event.rs

@@ -1,8 +1,10 @@
 //! Typed event description for bulk ingestion.
 //!
-//! `Event<T, K>` is the new public event shape (spec Section 4). Replaces
+//! `Event<T, K>` is the public event shape taken by `History::add_events`. It
-//! the nested `Vec<Vec<Vec<Index>>>`, `Vec<Vec<f64>>`, `Vec<Vec<Vec<f64>>>`
+//! is a typed front end, not a replacement: `add_events` flattens it into the
-//! that the old `add_events_with_prior` took.
+//! nested `Vec<Vec<Vec<Index>>>` / `Vec<Vec<f64>>` / `Vec<Vec<Vec<f64>>>` that
+//! the internal `add_events_with_prior` chokepoint still takes, and which
+//! `record_winner` and `record_draw` also route through.
 
 use smallvec::SmallVec;
 
@@ -23,6 +25,7 @@ pub struct Team<K> {
 }
 
 impl<K> Team<K> {
+    #[must_use]
     pub fn new() -> Self {
         Self {
             members: SmallVec::new(),
@@ -44,13 +47,20 @@ impl<K> Default for Team<K> {
 
 /// One member of a team, identified by user key `K`.
 ///
-/// `weight` defaults to 1.0; a per-event `prior` can override the competitor's
+/// `weight` applies per event and defaults to 1.0.
-/// current skill estimate for this event only.
+///
+/// `prior` and `drift_scale` are **competitor configuration**, not per-event
+/// values: both are captured when the competitor is first created and ignored
+/// on every later appearance. Setting either on a key the history already knows
+/// has no effect.
 #[derive(Clone, Debug)]
 pub struct Member<K> {
     pub key: K,
     pub weight: f64,
     pub prior: Option<Gaussian>,
+    /// Multiplier on the drift *variance* this competitor accumulates.
+    /// `None` means 1.0.
+    pub drift_scale: Option<f64>,
 }
 
 impl<K> Member<K> {
@@ -59,6 +69,7 @@ impl<K> Member<K> {
             key,
             weight: 1.0,
             prior: None,
+            drift_scale: None,
         }
     }
 
@@ -67,10 +78,31 @@ impl<K> Member<K> {
         self
     }
 
+    /// Set this competitor's starting skill estimate.
+    ///
+    /// Captured at the competitor's first appearance; see the type docs.
     pub fn with_prior(mut self, prior: Gaussian) -> Self {
         self.prior = Some(prior);
         self
     }
+
+    /// Scale how fast this competitor drifts, relative to the history's drift.
+    ///
+    /// The scale multiplies the drift *variance*, so it is in the same units as
+    /// `gamma`: `ConstantDrift(g)` at `scale = s` behaves exactly as
+    /// `ConstantDrift(g * s)` would for this competitor alone.
+    ///
+    /// `0.0` pins the competitor still — useful for a reference point that
+    /// shares a scale with moving competitors but should not itself move: a bot
+    /// at a known strength, a rating floor, a course difficulty.
+    ///
+    /// Captured at the competitor's first appearance; see the type docs.
+    /// Must be finite and non-negative, or ingestion fails with
+    /// [`InferenceError::InvalidParameter`](crate::InferenceError::InvalidParameter).
+    pub fn with_drift_scale(mut self, scale: f64) -> Self {
+        self.drift_scale = Some(scale);
+        self
+    }
 }
 
 /// Convenience: a member is a user key with default weight 1.0 and no prior.
@@ -91,15 +123,18 @@ mod tests {
         assert_eq!(m.key, "alice");
         assert_eq!(m.weight, 1.0);
         assert!(m.prior.is_none());
+        assert!(m.drift_scale.is_none());
     }
 
     #[test]
     fn member_builder_methods_chain() {
         let m = Member::new("alice")
             .with_weight(0.5)
-            .with_prior(Gaussian::from_ms(20.0, 5.0));
+            .with_prior(Gaussian::from_ms(20.0, 5.0))
+            .with_drift_scale(0.0);
         assert_eq!(m.weight, 0.5);
         assert!(m.prior.is_some());
+        assert_eq!(m.drift_scale, Some(0.0));
     }
 
     #[test]

src/event_builder.rs

@@ -19,6 +19,14 @@ where
     history: &'h mut History<T, D, O, K>,
     event: Event<T, K>,
     current_team_idx: Option<usize>,
+    /// First validation failure seen while building, surfaced by `commit`.
+    ///
+    /// The setters return `Self` so the chain stays fluent; they cannot return
+    /// a `Result` without breaking that. Recording the failure and reporting it
+    /// at `commit` keeps the check enforced in release, where the previous
+    /// `debug_assert!` was compiled out and a mismatched event was ingested
+    /// silently.
+    error: Option<InferenceError>,
 }
 
 impl<'h, T, D, O, K> EventBuilder<'h, T, D, O, K>
@@ -37,6 +45,7 @@ where
                 outcome: Outcome::Ranked(SmallVec::new()),
             },
             current_team_idx: None,
+            error: None,
         }
     }
 
@@ -50,22 +59,36 @@ where
 
     /// Set per-member weights for the most recently added team.
     ///
-    /// Panics in debug builds if called before `.team(...)` or if the length
+    /// A length mismatch is recorded and returned by [`EventBuilder::commit`]
-    /// doesn't match the team's member count.
+    /// as `InferenceError::MismatchedShape`, in both debug and release. The
+    /// weights are not applied in that case, so a partially-weighted team
+    /// cannot reach the history.
+    ///
+    /// # Panics
+    ///
+    /// Panics if called before any `.team(...)`.
     pub fn weights<I: IntoIterator<Item = f64>>(mut self, weights: I) -> Self {
         let idx = self
             .current_team_idx
             .expect(".weights(...) called before any .team(...)");
+
         let ws: Vec<f64> = weights.into_iter().collect();
         let team = &mut self.event.teams[idx];
-        debug_assert_eq!(
+
-            ws.len(),
+        if ws.len() != team.members.len() {
-            team.members.len(),
+            self.error.get_or_insert(InferenceError::MismatchedShape {
-            "weights length must match team size"
+                kind: "weights",
-        );
+                expected: team.members.len(),
+                got: ws.len(),
+            });
+
+            return self;
+        }
+
         for (m, w) in team.members.iter_mut().zip(ws) {
             m.weight = w;
         }
+
         self
     }
 
@@ -84,7 +107,10 @@ where
     /// Set explicit per-team continuous scores with a per-event noise override.
     ///
     /// `sigma` overrides `HistoryBuilder::score_sigma` for this event only.
-    /// Must be `> 0.0`; debug-asserts otherwise via `Outcome::scores_with_sigma`.
+    /// Must be `> 0.0`. Constructing the outcome with a non-positive or NaN
+    /// sigma is allowed; the value is rejected with
+    /// `InferenceError::InvalidParameter` when the event is ingested, so
+    /// callers get an error from `commit` rather than a panic.
     pub fn scores_with_sigma<I: IntoIterator<Item = f64>>(mut self, scores: I, sigma: f64) -> Self {
         self.event.outcome = crate::Outcome::scores_with_sigma(scores, sigma);
         self
@@ -103,7 +129,17 @@ where
     }
 
     /// Commit the event to the history.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first validation failure recorded while building — see
+    /// [`EventBuilder::weights`] — otherwise forwards to
+    /// [`History::add_events`] and returns its errors.
     pub fn commit(self) -> Result<(), InferenceError> {
+        if let Some(error) = self.error {
+            return Err(error);
+        }
+
         self.history.add_events(std::iter::once(self.event))
     }
 }

src/factor/margin.rs

@@ -20,6 +20,7 @@ pub struct MarginFactor {
 }
 
 impl MarginFactor {
+    #[must_use]
     pub fn new(diff: VarId, m_obs: f64, sigma: f64) -> Self {
         debug_assert!(sigma > 0.0, "score sigma must be positive");
         Self {

src/factor/mod.rs

@@ -20,6 +20,7 @@ pub struct VarStore {
 }
 
 impl VarStore {
+    #[must_use]
     pub fn new() -> Self {
         Self::default()
     }
@@ -28,10 +29,12 @@ impl VarStore {
         self.marginals.clear();
     }
 
+    #[must_use]
     pub fn len(&self) -> usize {
         self.marginals.len()
     }
 
+    #[must_use]
     pub fn is_empty(&self) -> bool {
         self.marginals.is_empty()
     }
@@ -42,6 +45,7 @@ impl VarStore {
         id
     }
 
+    #[must_use]
     pub fn get(&self, id: VarId) -> Gaussian {
         self.marginals[id.0 as usize]
     }

src/factor/rank_diff.rs

@@ -5,12 +5,12 @@ use crate::factor::{Factor, VarId, VarStore};
 /// On each propagation:
 /// - Reads marginals at `team_a` and `team_b` (which already incorporate any
 ///   incoming messages from neighboring factors).
-/// - Computes `new_diff = team_a - team_b` (variance addition; see Gaussian::Sub).
+/// - Computes `new_diff = team_a - team_b` (variance addition; see `Gaussian::Sub`).
 /// - Writes the new marginal to `diff`.
 /// - Returns the delta against the previous diff value.
 ///
 /// This factor does NOT store an outgoing message; the diff variable is
-/// effectively replaced on each propagation. The TruncFactor on the same diff
+/// effectively replaced on each propagation. The `TruncFactor` on the same diff
 /// var holds the EP-divide message that produces the cavity.
 #[derive(Debug)]
 pub struct RankDiffFactor {

src/factor/trunc.rs

@@ -15,13 +15,14 @@ pub struct TruncFactor {
     pub diff: VarId,
     pub margin: f64,
     pub tie: bool,
-    /// Outgoing message to the diff variable (initial: N_INF, the EP identity).
+    /// Outgoing message to the diff variable (initial: `N_INF`, the EP identity).
     pub(crate) msg: Gaussian,
     /// Cached evidence (linear, not log) computed from the cavity on first propagation.
     pub(crate) evidence_cached: Option<f64>,
 }
 
 impl TruncFactor {
+    #[must_use]
     pub fn new(diff: VarId, margin: f64, tie: bool) -> Self {
         Self {
             diff,

src/factors.rs

@@ -1,13 +0,0 @@
-//! Factor-graph public API.
-//!
-//! Power users can construct custom factor graphs via `Game::custom` (T2
-//! minimal; full ergonomics in T4) and drive them with custom `Schedule`
-//! implementations.
-
-pub use crate::{
-    factor::{
-        BuiltinFactor, Factor, VarId, VarStore, margin::MarginFactor, rank_diff::RankDiffFactor,
-        team_sum::TeamSumFactor, trunc::TruncFactor,
-    },
-    schedule::{EpsilonOrMax, Schedule, ScheduleReport},
-};

src/game.rs

@@ -107,16 +107,13 @@ impl<T: Time, D: Drift<T>> OwnedGame<T, D> {
         convergence: crate::ConvergenceOptions,
     ) -> Self {
         let mut arena = ScratchArena::new();
-        let g = Game::ranked_with_arena(
+
-            teams.clone(),
+        // `Game` takes the teams by value and is dropped here, so take the vec
-            &result,
+        // back out of it rather than handing it a clone.
-            &weights,
+        let g = Game::ranked_with_arena(teams, &result, &weights, p_draw, convergence, &mut arena);
-            p_draw,
+
-            convergence,
-            &mut arena,
-        );
         Self {
-            teams,
+            teams: g.teams,
             likelihoods: g.likelihoods,
             log_evidence: g.log_evidence,
         }
@@ -130,21 +127,24 @@ impl<T: Time, D: Drift<T>> OwnedGame<T, D> {
         convergence: crate::ConvergenceOptions,
     ) -> Self {
         let mut arena = ScratchArena::new();
+
         let g = Game::scored_with_arena(
-            teams.clone(),
+            teams,
             &scores,
             &weights,
             score_sigma,
             convergence,
             &mut arena,
         );
+
         Self {
-            teams,
+            teams: g.teams,
             likelihoods: g.likelihoods,
             log_evidence: g.log_evidence,
         }
     }
 
+    #[must_use]
     pub fn posteriors(&self) -> Vec<Vec<Gaussian>> {
         self.likelihoods
             .iter()
@@ -153,6 +153,7 @@ impl<T: Time, D: Drift<T>> OwnedGame<T, D> {
             .collect()
     }
 
+    #[must_use]
     pub fn log_evidence(&self) -> f64 {
         self.log_evidence
     }
@@ -409,6 +410,7 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
         self.likelihoods = likelihoods;
     }
 
+    #[must_use]
     pub fn posteriors(&self) -> Vec<Vec<Gaussian>> {
         self.likelihoods
             .iter()
@@ -422,12 +424,21 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
             .collect::<Vec<_>>()
     }
 
+    #[must_use]
     pub fn log_evidence(&self) -> f64 {
         self.log_evidence
     }
 }
 
 impl<T: Time, D: Drift<T>> Game<'_, T, D> {
+    /// # Errors
+    ///
+    /// - `InvalidProbability` if `options.p_draw` is outside `[0.0, 1.0)`.
+    /// - `MismatchedShape` if the outcome's rank count differs from `teams.len()`.
+    /// - `WrongOutcomeKind` if `outcome` is not `Outcome::Ranked`.
+    /// - `TieWithoutDrawProbability` if the outcome ties two teams while
+    ///   `p_draw` is zero: the truncation margin is then zero and the two-sided
+    ///   tie update evaluates `0/0`.
     pub fn ranked(
         teams: &[&[Rating<T, D>]],
         outcome: crate::Outcome,
@@ -478,6 +489,12 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
         ))
     }
 
+    /// # Errors
+    ///
+    /// - `InvalidParameter` if `options.score_sigma` is not strictly positive,
+    ///   or is NaN.
+    /// - `MismatchedShape` if the outcome's score count differs from `teams.len()`.
+    /// - `WrongOutcomeKind` if `outcome` is not `Outcome::Scored`.
     pub fn scored(
         teams: &[&[Rating<T, D>]],
         outcome: crate::Outcome,
@@ -515,16 +532,28 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
         ))
     }
 
+    /// Convenience wrapper over [`Game::ranked`] for two single-player teams.
+    ///
+    /// # Errors
+    ///
+    /// Delegates to [`Game::ranked`], so it returns the same errors — in
+    /// practice `WrongOutcomeKind` for a non-ranked outcome, or
+    /// `TieWithoutDrawProbability` for a draw when `options.p_draw` is zero.
     pub fn one_v_one(
         a: &Rating<T, D>,
         b: &Rating<T, D>,
         outcome: crate::Outcome,
+        options: &GameOptions,
     ) -> Result<(Gaussian, Gaussian), crate::InferenceError> {
-        let game = Self::ranked(&[&[*a], &[*b]], outcome, &GameOptions::default())?;
+        let game = Self::ranked(&[&[*a], &[*b]], outcome, options)?;
         let post = game.posteriors();
         Ok((post[0][0], post[1][0]))
     }
 
+    /// # Errors
+    ///
+    /// Wraps each player in a one-member team and delegates to
+    /// [`Game::ranked`], so it returns the same errors.
     pub fn free_for_all(
         players: &[&Rating<T, D>],
         outcome: crate::Outcome,
@@ -536,11 +565,11 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
     }
 
     #[doc(hidden)]
-    pub fn custom<S: crate::factors::Schedule>(
+    pub fn custom<S: crate::graph::Schedule>(
-        factors: &mut [crate::factors::BuiltinFactor],
+        factors: &mut [crate::graph::BuiltinFactor],
-        vars: &mut crate::factors::VarStore,
+        vars: &mut crate::graph::VarStore,
         schedule: &S,
-    ) -> crate::factors::ScheduleReport {
+    ) -> crate::graph::ScheduleReport {
         schedule.run(factors, vars)
     }
 }

src/gaussian.rs

@@ -18,6 +18,7 @@ pub struct Gaussian {
 
 impl Gaussian {
     /// Construct from mean and standard deviation.
+    #[must_use]
     pub const fn from_ms(mu: f64, sigma: f64) -> Self {
         if sigma == f64::INFINITY {
             Self { pi: 0.0, tau: 0.0 }
@@ -64,16 +65,19 @@ impl Gaussian {
     }
 
     #[inline]
+    #[must_use]
     pub fn pi(&self) -> f64 {
         self.pi
     }
 
     #[inline]
+    #[must_use]
     pub fn tau(&self) -> f64 {
         self.tau
     }
 
     #[inline]
+    #[must_use]
     pub fn mu(&self) -> f64 {
         // A non-positive precision is an improper (uninformative) Gaussian — its mean is
         // undefined. Treat it like `pi == 0` and return 0. EP message cancellation can land
@@ -102,6 +106,7 @@ impl Gaussian {
     }
 
     #[inline]
+    #[must_use]
     pub fn sigma(&self) -> f64 {
         // A non-positive precision is improper → infinite standard deviation. Guarding
         // `pi <= 0.0` (not just `== 0.0`) keeps `1.0 / pi.sqrt()` from returning NaN when EP
@@ -145,6 +150,7 @@ impl Gaussian {
     /// Used by within-game inference to stabilise oscillating fixed-point
     /// loops on hard graphs. `alpha = 1.0` returns `new` exactly;
     /// `alpha < 1.0` shrinks each per-step update.
+    #[must_use]
     pub fn damp_natural(self, new: Gaussian, alpha: f64) -> Gaussian {
         Gaussian::from_natural(
             alpha * new.pi() + (1.0 - alpha) * self.pi(),

src/graph.rs

@@ -0,0 +1,20 @@
+//! Factor-graph public API.
+//!
+//! Named `graph` rather than `factors` because the private implementation
+//! module beside it is `factor`: two module paths differing by one character,
+//! one public and one not, was a standing invitation to import the wrong one.
+//!
+//! The factor types, `VarStore` and the `Schedule` trait are public so custom
+//! schedules can be written against them.
+//!
+//! Building a factor graph by hand goes through `Game::custom`, which is
+//! deliberately `#[doc(hidden)]`: it works, but its signature is not yet
+//! considered stable API and so is not listed in these docs.
+
+pub use crate::{
+    factor::{
+        BuiltinFactor, Factor, VarId, VarStore, margin::MarginFactor, rank_diff::RankDiffFactor,
+        team_sum::TeamSumFactor, trunc::TruncFactor,
+    },
+    schedule::{EpsilonOrMax, Schedule, ScheduleReport},
+};

src/history.rs

@@ -1,7 +1,7 @@
 use std::{borrow::Borrow, collections::HashMap, hash::Hash, marker::PhantomData};
 
 use crate::{
-    BETA, GAMMA, Index, MU, N_INF, P_DRAW, SIGMA,
+    BETA, GAMMA, Index, MU, P_DRAW, SIGMA,
     competitor::{self, Competitor},
     convergence::{ConvergenceOptions, ConvergenceReport},
     drift::{ConstantDrift, Drift},
@@ -9,6 +9,7 @@ use crate::{
     gaussian::Gaussian,
     key_table::KeyTable,
     observer::{NullObserver, Observer},
+    predict::Prediction,
     rating::Rating,
     sort_time,
     storage::CompetitorStore,
@@ -198,6 +199,7 @@ impl Default for History<i64, ConstantDrift, NullObserver, &'static str> {
 }
 
 impl History<i64, ConstantDrift, NullObserver, &'static str> {
+    #[must_use]
     pub fn builder() -> HistoryBuilder<i64, ConstantDrift, NullObserver, &'static str> {
         HistoryBuilder::default()
     }
@@ -205,6 +207,7 @@ impl History<i64, ConstantDrift, NullObserver, &'static str> {
 
 impl<K: Eq + Hash + Clone> History<i64, ConstantDrift, NullObserver, K> {
     /// Like `builder()` but uses a custom key type `K` instead of the default `&'static str`.
+    #[must_use]
     pub fn builder_with_key() -> HistoryBuilder<i64, ConstantDrift, NullObserver, K> {
         HistoryBuilder {
             mu: MU,
@@ -252,12 +255,17 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         for j in (0..self.time_slices.len() - 1).rev() {
             for agent in self.time_slices[j + 1].skills.keys() {
                 self.agents.get_mut(agent).unwrap().message =
-                    self.time_slices[j + 1].backward_prior_out(&agent, &self.agents);
+                    Some(self.time_slices[j + 1].backward_prior_out(&agent, &self.agents));
             }
 
             let old = self.time_slices[j].posteriors();
 
             self.time_slices[j].new_backward_info(&self.agents);
+            self.observer.on_slice_processed(
+                &self.time_slices[j].time,
+                j,
+                self.time_slices[j].events.len(),
+            );
 
             let new = self.time_slices[j].posteriors();
 
@@ -271,12 +279,17 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         for j in 1..self.time_slices.len() {
             for agent in self.time_slices[j - 1].skills.keys() {
                 self.agents.get_mut(agent).unwrap().message =
-                    self.time_slices[j - 1].forward_prior_out(&agent);
+                    Some(self.time_slices[j - 1].forward_prior_out(&agent));
             }
 
             let old = self.time_slices[j].posteriors();
 
             self.time_slices[j].new_forward_info(&self.agents);
+            self.observer.on_slice_processed(
+                &self.time_slices[j].time,
+                j,
+                self.time_slices[j].events.len(),
+            );
 
             let new = self.time_slices[j].posteriors();
 
@@ -289,6 +302,11 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             let old = self.time_slices[0].posteriors();
 
             self.time_slices[0].iteration(0, &self.agents);
+            self.observer.on_slice_processed(
+                &self.time_slices[0].time,
+                0,
+                self.time_slices[0].events.len(),
+            );
 
             let new = self.time_slices[0].posteriors();
 
@@ -520,60 +538,225 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             .sum()
     }
 
-    /// Draw-probability quality metric for the given teams (key slices).
+    /// Each team's performance Gaussian, and its member count.
     ///
-    /// Values range roughly [0, 1]; 1 == perfectly matched. Supports any
+    /// Performance is skill inflated by `beta`: the question a prediction
-    /// number of teams.
+    /// answers is "how will they do today", not "how good are they".
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if fewer than two teams are supplied, or if a team resolves to
+    /// `NotEnoughTeams`, `EmptyTeam`, or `UnknownKey`. Unknown keys are
-    /// no known competitors — keys absent from the history, or competitors
+    /// reported rather than dropped — silently skipping them would turn a team
-    /// with no recorded skill, are dropped, so a team of entirely-unknown
+    /// of strangers into a confident-looking prediction about nobody, which is
-    /// keys becomes empty. Use `lookup` to check keys first.
+    /// the failure this replaced.
-    pub fn predict_quality(&self, teams: &[&[&K]]) -> f64 {
+    fn performances(&self, teams: &[&[&K]]) -> Result<(Vec<Gaussian>, Vec<usize>), InferenceError> {
-        let groups: Vec<Vec<Gaussian>> = teams
+        if teams.len() < 2 {
-            .iter()
+            return Err(InferenceError::NotEnoughTeams { got: teams.len() });
-            .map(|team| {
+        }
-                team.iter()
+
-                    .filter_map(|k| self.keys.get(*k))
+        let mut performances = Vec::with_capacity(teams.len());
-                    .filter_map(|idx| {
+        let mut sizes = Vec::with_capacity(teams.len());
-                        self.time_slices
+
-                            .iter()
+        for (team_idx, team) in teams.iter().enumerate() {
-                            .rev()
+            if team.is_empty() {
-                            .find_map(|ts| ts.skills.get(idx).map(|s| s.posterior()))
+                return Err(InferenceError::EmptyTeam { team: team_idx });
-                    })
+            }
-                    .collect()
+
-            })
+            let mut total = crate::N00;
-            .collect();
+            for (member_idx, key) in team.iter().enumerate() {
-        let group_refs: Vec<&[Gaussian]> = groups.iter().map(|g| g.as_slice()).collect();
+                let unknown = InferenceError::UnknownKey {
-        crate::quality(&group_refs, self.beta)
+                    team: team_idx,
+                    member: member_idx,
+                };
+                let index = self.keys.get(*key).ok_or(unknown.clone())?;
+                let skill = self
+                    .time_slices
+                    .iter()
+                    .rev()
+                    .find_map(|ts| ts.skills.get(index).map(|s| s.posterior()))
+                    .ok_or(unknown)?;
+                total = total + skill.forget(self.beta.powi(2));
+            }
+
+            performances.push(total);
+            sizes.push(team.len());
+        }
+
+        Ok((performances, sizes))
     }
 
-    /// 2-team win probability: returns `[P(team0 wins), P(team1 wins)]`.
+    /// Draw margins per team pair.
     ///
-    /// Panics if `teams.len() != 2`. N-team support lands in T4.
+    /// Inference derives the margin per rank-adjacent pair from those two
-    pub fn predict_outcome(&self, teams: &[&[&K]]) -> Vec<f64> {
+    /// teams' betas (`Game::likelihoods`), so prediction must too — a single
-        assert_eq!(teams.len(), 2, "predict_outcome T2: 2 teams only");
+    /// game-wide margin would describe a different model than the one that
-        let gather = |team: &[&K]| -> Gaussian {
+    /// will actually be fitted.
-            team.iter()
+    fn margins(&self, sizes: &[usize]) -> crate::predict::Margins {
-                .filter_map(|k| self.keys.get(*k))
+        let beta_sq = self.beta.powi(2);
-                .filter_map(|idx| {
+        let p_draw = self.p_draw;
+
+        crate::predict::Margins::new(sizes.len(), |i, j| {
+            if p_draw == 0.0 {
+                0.0
+            } else {
+                let sd = ((sizes[i] + sizes[j]) as f64 * beta_sq).sqrt();
+                crate::compute_margin(p_draw, sd)
+            }
+        })
+    }
+
+    /// Draw-probability quality metric for the given teams (key slices).
+    ///
+    /// Values range roughly `[0, 1]`; 1 == perfectly matched. Supports any
+    /// number of teams.
+    ///
+    /// Note this answers "is this matchup *fair*", which is not the same as
+    /// "is this matchup *informative*" — the two coincide for two evenly
+    /// matched teams and diverge elsewhere.
+    ///
+    /// # Errors
+    ///
+    /// `NotEnoughTeams`, `EmptyTeam`, or `UnknownKey`.
+    pub fn predict_quality(&self, teams: &[&[&K]]) -> Result<f64, InferenceError> {
+        let mut groups: Vec<Vec<Gaussian>> = Vec::with_capacity(teams.len());
+
+        for (team_idx, team) in teams.iter().enumerate() {
+            if team.is_empty() {
+                return Err(InferenceError::EmptyTeam { team: team_idx });
+            }
+            let mut members = Vec::with_capacity(team.len());
+            for (member_idx, key) in team.iter().enumerate() {
+                let unknown = InferenceError::UnknownKey {
+                    team: team_idx,
+                    member: member_idx,
+                };
+                let index = self.keys.get(*key).ok_or(unknown.clone())?;
+                members.push(
                     self.time_slices
                         .iter()
                         .rev()
-                        .find_map(|ts| ts.skills.get(idx).map(|s| s.posterior()))
+                        .find_map(|ts| ts.skills.get(index).map(|s| s.posterior()))
-                })
+                        .ok_or(unknown)?,
-                .fold(crate::N00, |acc, g| acc + g.forget(self.beta.powi(2)))
+                );
-        };
+            }
-        let a = gather(teams[0]);
+            groups.push(members);
-        let b = gather(teams[1]);
+        }
-        let diff = a - b;
+
-        let p_a = 1.0 - crate::cdf(0.0, diff.mu(), diff.sigma());
+        if groups.len() < 2 {
-        vec![p_a, 1.0 - p_a]
+            return Err(InferenceError::NotEnoughTeams { got: groups.len() });
+        }
+
+        let group_refs: Vec<&[Gaussian]> = groups.iter().map(Vec::as_slice).collect();
+        Ok(crate::quality(&group_refs, self.beta))
+    }
+
+    /// `P(team i finishes strictly first)`, for every team.
+    ///
+    /// Supports any number of teams. Because performances are independent
+    /// Gaussians, this separates into a one-dimensional integral per team —
+    /// no multivariate orthant probability is involved — and is evaluated by
+    /// adaptive quadrature to within the precision of the underlying normal
+    /// CDF (~1e-8).
+    ///
+    /// With a zero `p_draw` these sum to one. With a positive `p_draw` the
+    /// shortfall is the probability that the top place is shared.
+    ///
+    /// Cheap at any team count: cost grows as the square of the team count,
+    /// not factorially. Prefer this to [`History::predict_outcome`] when you
+    /// only need to know who wins.
+    ///
+    /// # Errors
+    ///
+    /// `NotEnoughTeams`, `EmptyTeam`, or `UnknownKey`.
+    pub fn predict_win_probabilities(&self, teams: &[&[&K]]) -> Result<Vec<f64>, InferenceError> {
+        let (performances, sizes) = self.performances(teams)?;
+        Ok(crate::predict::win_probabilities(
+            &performances,
+            &self.margins(&sizes),
+        ))
+    }
+
+    /// The full distribution over finishing orders.
+    ///
+    /// Every entry is a rank vector — the shape [`crate::Outcome::ranking`]
+    /// takes, equal ranks meaning a tie — paired with its probability. The
+    /// entries are exhaustive and disjoint, so they sum to one; that identity
+    /// is the strongest available check on the numerics and is worth asserting
+    /// in tests via [`Prediction::total`].
+    ///
+    /// Accounts for `p_draw`: with a positive draw probability, tied outcomes
+    /// carry real mass rather than being silently omitted.
+    ///
+    /// # Cost
+    ///
+    /// This enumerates the outcome space, which holds `n! * 2^(n-1)` events —
+    /// 24 at three teams, 192 at four, 1_920 at five, 23_040 at six. Each
+    /// costs one `O(teams * grid)` pass, so this is milliseconds at three or
+    /// four teams and seconds at six. Above
+    /// [`MAX_TEAMS_FOR_DISTRIBUTION`](crate::MAX_PREDICTED_TEAMS) it returns
+    /// `TooManyTeams` rather than hanging. When you need one specific ordering
+    /// use [`History::predict_ranking`], and when you only need the winner use
+    /// [`History::predict_win_probabilities`]; both stay cheap at any size.
+    ///
+    /// # Errors
+    ///
+    /// `NotEnoughTeams`, `EmptyTeam`, `UnknownKey`, or `TooManyTeams`.
+    pub fn predict_outcome(&self, teams: &[&[&K]]) -> Result<Prediction, InferenceError> {
+        if teams.len() > crate::MAX_PREDICTED_TEAMS {
+            return Err(InferenceError::TooManyTeams {
+                got: teams.len(),
+                max: crate::MAX_PREDICTED_TEAMS,
+            });
+        }
+
+        let (performances, sizes) = self.performances(teams)?;
+        Ok(Prediction::new(crate::predict::outcome_distribution(
+            &performances,
+            &self.margins(&sizes),
+        )))
+    }
+
+    /// Probability of one specific finishing order.
+    ///
+    /// `ranks` follows [`crate::Outcome::ranking`]: lower is better, and equal
+    /// values mean those teams tied. Teams sharing a rank may finish in any
+    /// internal order, so this sums over those orders rather than picking one.
+    ///
+    /// Unlike [`History::predict_outcome`] this does not enumerate the outcome
+    /// space, so it stays cheap at any team count — use it when you know which
+    /// orderings you care about.
+    ///
+    /// # Errors
+    ///
+    /// `NotEnoughTeams`, `EmptyTeam`, `UnknownKey`, or `MismatchedShape` if
+    /// `ranks` does not have one entry per team.
+    pub fn predict_ranking(&self, teams: &[&[&K]], ranks: &[u32]) -> Result<f64, InferenceError> {
+        if ranks.len() != teams.len() {
+            return Err(InferenceError::MismatchedShape {
+                kind: "ranks vs teams",
+                expected: teams.len(),
+                got: ranks.len(),
+            });
+        }
+
+        let (performances, sizes) = self.performances(teams)?;
+        Ok(crate::predict::ranking_probability(
+            &performances,
+            &self.margins(&sizes),
+            ranks,
+        ))
     }
 
     /// Run the full forward+backward convergence loop and return a summary.
+    ///
+    /// Failing to reach `epsilon` within `max_iter` is not an error: the
+    /// returned report carries `converged: false` and the final step.
+    ///
+    /// # Errors
+    ///
+    /// `NonFiniteResult` if a sweep produces a NaN or infinite step. EP has
+    /// broken down at that point and further iterations cannot recover, so the
+    /// loop stops rather than reporting a NaN step as convergence.
     pub fn converge(&mut self) -> Result<ConvergenceReport, InferenceError> {
         use std::time::Instant;
 
@@ -588,7 +771,6 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                 log_evidence: 0.0,
                 converged: true,
                 per_iteration_time: SmallVec::new(),
-                slices_skipped: 0,
             });
         }
 
@@ -627,7 +809,6 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             log_evidence,
             converged,
             per_iteration_time: per_iter,
-            slices_skipped: 0,
         })
     }
 }
@@ -635,18 +816,23 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
 impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O, K> {
     pub(crate) fn add_events_with_prior(
         &mut self,
-        composition: Vec<Vec<Vec<Index>>>,
+        mut composition: Vec<Vec<Vec<Index>>>,
-        results: Vec<Vec<f64>>,
+        mut results: Option<Vec<Vec<f64>>>,
         times: Vec<T>,
-        weights: Vec<Vec<Vec<f64>>>,
+        mut weights: Option<Vec<Vec<Vec<f64>>>>,
         kinds: Vec<EventKind>,
         mut priors: HashMap<Index, Rating<T, D>>,
     ) -> Result<(), InferenceError> {
-        if !results.is_empty() && results.len() != composition.len() {
+        if results
+            .as_ref()
+            .is_some_and(|r| r.len() != composition.len())
+        {
+            let got = results.as_ref().map_or(0, Vec::len);
+
             return Err(InferenceError::MismatchedShape {
                 kind: "results",
                 expected: composition.len(),
-                got: results.len(),
+                got,
             });
         }
         if times.len() != composition.len() {
@@ -656,11 +842,16 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                 got: times.len(),
             });
         }
-        if !weights.is_empty() && weights.len() != composition.len() {
+        if weights
+            .as_ref()
+            .is_some_and(|w| w.len() != composition.len())
+        {
+            let got = weights.as_ref().map_or(0, Vec::len);
+
             return Err(InferenceError::MismatchedShape {
                 kind: "weights",
                 expected: composition.len(),
-                got: weights.len(),
+                got,
             });
         }
         if kinds.len() != composition.len() {
@@ -675,7 +866,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         // including `record_draw`, which builds its results directly rather
         // than going through `Outcome`.
         if self.p_draw == 0.0 {
-            for (event_results, kind) in results.iter().zip(kinds.iter()) {
+            for (event_results, kind) in results.iter().flatten().zip(kinds.iter()) {
                 if !matches!(kind, EventKind::Ranked) {
                     continue;
                 }
@@ -708,7 +899,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                                 self.drift,
                             )
                         }),
-                        message: N_INF,
+                        message: None,
                         last_time: None,
                     },
                 );
@@ -718,6 +909,20 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         let n = composition.len();
         let o = sort_time(&times, false);
 
+        // The chunking loop below MOVES each event's data out of `composition`,
+        // `results` and `weights` instead of cloning it. That is only sound
+        // because `o` is a permutation, so every index is visited exactly once
+        // — visiting one twice would silently yield an empty event rather than
+        // failing.
+        debug_assert!(
+            {
+                let mut seen = vec![false; n];
+                o.iter()
+                    .all(|&idx| !std::mem::replace(&mut seen[idx], true))
+            },
+            "sort_time must return a permutation of 0..{n}"
+        );
+
         let mut i = 0;
         let mut k = 0;
 
@@ -746,7 +951,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                         let agent = self.agents.get_mut(*agent_idx).unwrap();
 
                         agent.last_time = Some(time_slice.time);
-                        agent.message = time_slice.forward_prior_out(agent_idx);
+                        agent.message = Some(time_slice.forward_prior_out(agent_idx));
                     }
                 }
 
@@ -754,20 +959,20 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             }
 
             let composition = (i..j)
-                .map(|e| composition[o[e]].clone())
+                .map(|e| std::mem::take(&mut composition[o[e]]))
                 .collect::<Vec<_>>();
 
-            let results = if results.is_empty() {
+            let results = results.as_mut().map(|results| {
-                Vec::new()
+                (i..j)
-            } else {
+                    .map(|e| std::mem::take(&mut results[o[e]]))
-                (i..j).map(|e| results[o[e]].clone()).collect::<Vec<_>>()
+                    .collect::<Vec<_>>()
-            };
+            });
 
-            let weights = if weights.is_empty() {
+            let weights = weights.as_mut().map(|weights| {
-                Vec::new()
+                (i..j)
-            } else {
+                    .map(|e| std::mem::take(&mut weights[o[e]]))
-                (i..j).map(|e| weights[o[e]].clone()).collect::<Vec<_>>()
+                    .collect::<Vec<_>>()
-            };
+            });
 
             let kinds_chunk: Vec<EventKind> = (i..j).map(|e| kinds[o[e]]).collect();
 
@@ -779,7 +984,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                     let agent = self.agents.get_mut(agent_idx).unwrap();
 
                     agent.last_time = Some(t);
-                    agent.message = time_slice.forward_prior_out(&agent_idx);
+                    agent.message = Some(time_slice.forward_prior_out(&agent_idx));
                 }
 
                 k += 1;
@@ -795,7 +1000,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                     let agent = self.agents.get_mut(agent_idx).unwrap();
 
                     agent.last_time = Some(t);
-                    agent.message = time_slice.forward_prior_out(&agent_idx);
+                    agent.message = Some(time_slice.forward_prior_out(&agent_idx));
                 }
 
                 k += 1;
@@ -819,7 +1024,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                     let agent = self.agents.get_mut(*agent_idx).unwrap();
 
                     agent.last_time = Some(time_slice.time);
-                    agent.message = time_slice.forward_prior_out(agent_idx);
+                    agent.message = Some(time_slice.forward_prior_out(agent_idx));
                 }
             }
 
@@ -830,6 +1035,13 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         Ok(())
     }
 
+    /// Record a single two-competitor event that `winner` won.
+    ///
+    /// # Errors
+    ///
+    /// Ingests through the same path as [`History::add_events`], so it returns
+    /// the same errors. A two-team decisive outcome cannot tie, so
+    /// `TieWithoutDrawProbability` is not reachable here.
     pub fn record_winner<Q>(&mut self, winner: &Q, loser: &Q, time: T) -> Result<(), InferenceError>
     where
         K: Borrow<Q>,
@@ -839,14 +1051,21 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         let l = self.intern(loser);
         self.add_events_with_prior(
             vec![vec![vec![w], vec![l]]],
-            vec![vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0]]),
             vec![time],
-            vec![],
+            None,
             vec![EventKind::Ranked],
             HashMap::new(),
         )
     }
 
+    /// Record a single two-competitor event that ended level.
+    ///
+    /// # Errors
+    ///
+    /// Ingests through the same path as [`History::add_events`]. Note
+    /// `TieWithoutDrawProbability` *is* reachable here: a draw needs a
+    /// positive `p_draw`.
     pub fn record_draw<Q>(&mut self, a: &Q, b: &Q, time: T) -> Result<(), InferenceError>
     where
         K: Borrow<Q>,
@@ -856,9 +1075,9 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         let b_idx = self.intern(b);
         self.add_events_with_prior(
             vec![vec![vec![a_idx], vec![b_idx]]],
-            vec![vec![0.0, 0.0]],
+            Some(vec![vec![0.0, 0.0]]),
             vec![time],
-            vec![],
+            None,
             vec![EventKind::Ranked],
             HashMap::new(),
         )
@@ -870,6 +1089,17 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     }
 
     /// Bulk-ingest typed events.
+    ///
+    /// # Errors
+    ///
+    /// - `MismatchedShape` if an event's outcome does not describe the same
+    ///   number of teams the event has, or if per-member weights do not match
+    ///   the team's membership.
+    /// - `InvalidParameter` if a per-event `score_sigma` override is not
+    ///   strictly positive.
+    /// - `TieWithoutDrawProbability` if an event ties two teams while the
+    ///   history's `p_draw` is zero. This includes `Outcome::winner(w, n)` for
+    ///   `n >= 3`, which ties every loser.
     pub fn add_events<I>(&mut self, events: I) -> Result<(), InferenceError>
     where
         I: IntoIterator<Item = crate::event::Event<T, K>>,
@@ -906,8 +1136,37 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
                     let idx = self.keys.get_or_create(&member.key);
                     team_indices.push(idx);
                     team_weights.push(member.weight);
-                    if let Some(prior) = member.prior {
+
-                        priors.insert(idx, Rating::new(prior, self.beta, self.drift));
+                    if let Some(scale) = member.drift_scale {
+                        // Squaring would make a negative scale behave as its
+                        // absolute value, so reject rather than silently
+                        // accept a sign the caller cannot have meant.
+                        if !scale.is_finite() || scale < 0.0 {
+                            return Err(InferenceError::InvalidParameter {
+                                name: "drift_scale",
+                                value: scale,
+                            });
+                        }
+                    }
+
+                    // `prior` and `drift_scale` are competitor configuration,
+                    // captured here and consumed at competitor creation. Both
+                    // land in the same entry so a member may set either alone.
+                    if member.prior.is_some() || member.drift_scale.is_some() {
+                        let rating = priors.entry(idx).or_insert_with(|| {
+                            Rating::new(
+                                Gaussian::from_ms(self.mu, self.sigma),
+                                self.beta,
+                                self.drift,
+                            )
+                        });
+
+                        if let Some(prior) = member.prior {
+                            rating.prior = prior;
+                        }
+                        if let Some(scale) = member.drift_scale {
+                            rating.drift_scale = scale;
+                        }
                     }
                 }
                 event_comp.push(team_indices);
@@ -941,7 +1200,13 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             times.push(ev.time);
         }
 
-        self.add_events_with_prior(composition, results, times, weights, kinds, priors)
+        let weights = if weights.is_empty() {
+            None
+        } else {
+            Some(weights)
+        };
+
+        self.add_events_with_prior(composition, Some(results), times, weights, kinds, priors)
     }
 }
 
@@ -956,6 +1221,49 @@ mod tests {
         arena::ScratchArena,
     };
 
+    /// #17: a slice's footprint must be O(competitors in the slice), not
+    /// O(largest global index it touches). The store used to be a dense
+    /// `Vec<Skill>` indexed by `Index.0`, so the same two-competitor games cost
+    /// 20,000 slots per slice when the competitors sat at the top of a large
+    /// roster. Measured end to end, peak RSS was 309 MB against 52 MB.
+    #[test]
+    fn per_slice_footprint_is_independent_of_index_magnitude() {
+        fn total_skill_slots(high_indices: bool) -> usize {
+            let mut h: History<i64, ConstantDrift, NullObserver, String> =
+                History::builder_with_key().build();
+
+            for i in 0..2_000 {
+                h.intern(&format!("k{i:05}"));
+            }
+
+            let (a, b) = if high_indices {
+                ("k01998".to_string(), "k01999".to_string())
+            } else {
+                ("k00000".to_string(), "k00001".to_string())
+            };
+
+            for time in 1..=20i64 {
+                h.record_winner(&a, &b, time).unwrap();
+            }
+
+            h.time_slices
+                .iter()
+                .map(|ts| ts.skills.allocated_slots())
+                .sum()
+        }
+
+        let low = total_skill_slots(false);
+        let high = total_skill_slots(true);
+
+        assert_eq!(low, high, "footprint must not depend on index magnitude");
+
+        // A dense store over a 2,000-key roster would allocate 20 x 2,000.
+        assert!(
+            high < 1_000,
+            "20 slices of 2 competitors allocated {high} slots"
+        );
+    }
+
     fn make_events_1v1(
         pairs: &[(&'static str, &'static str)],
         outcomes: &[Outcome],

src/key_table.rs

@@ -25,6 +25,7 @@ impl<K> KeyTable<K>
 where
     K: Eq + Hash + Clone,
 {
+    #[must_use]
     pub fn new() -> Self {
         Self {
             forward: HashMap::new(),
@@ -54,6 +55,7 @@ where
         }
     }
 
+    #[must_use]
     pub fn key(&self, idx: Index) -> Option<&K> {
         self.reverse.get(idx.0)
     }
@@ -62,10 +64,12 @@ where
         self.forward.keys()
     }
 
+    #[must_use]
     pub fn len(&self) -> usize {
         self.reverse.len()
     }
 
+    #[must_use]
     pub fn is_empty(&self) -> bool {
         self.reverse.is_empty()
     }

src/lib.rs

@@ -1,6 +1,6 @@
-//! TrueSkill Through Time — Bayesian skill rating over a time axis.
+//! `TrueSkill` Through Time — Bayesian skill rating over a time axis.
 //!
-//! Where plain TrueSkill gives each competitor one running estimate, TrueSkill
+//! Where plain `TrueSkill` gives each competitor one running estimate, `TrueSkill`
 //! Through Time treats a whole history as a single model and infers skill *at
 //! every point in time*. Evidence flows both directions: a result today
 //! sharpens the estimate of who someone was last year, so early estimates stop
@@ -86,6 +86,19 @@
 
 #![forbid(unsafe_code)]
 
+/// Compiles every `rust` block in `README.md` as a doctest.
+///
+/// The README is not the crate's front page — the module docs above are — so it
+/// is pulled in here rather than via a crate-level `#![doc = ...]`, purely so
+/// its examples are type-checked. Without this nothing compiled them, and they
+/// had drifted far enough that four blocks no longer built (#35). `cfg(doctest)`
+/// means this type exists only while collecting doctests.
+///
+/// Blocks that are illustrative rather than runnable are fenced as `text`.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+pub struct ReadmeDoctests;
+
 use std::{
     cmp::Reverse,
     f64::consts::{FRAC_1_SQRT_2, FRAC_2_SQRT_PI, SQRT_2},
@@ -105,14 +118,16 @@ mod error;
 mod event;
 mod event_builder;
 pub(crate) mod factor;
-pub mod factors;
 mod game;
 pub mod gaussian;
+pub mod graph;
 mod history;
 mod key_table;
 mod matrix;
 mod observer;
 mod outcome;
+mod predict;
+pub(crate) mod quadrature;
 mod rating;
 pub(crate) mod schedule;
 pub mod storage;
@@ -130,6 +145,7 @@ pub use key_table::KeyTable;
 use matrix::Matrix;
 pub use observer::{NullObserver, Observer};
 pub use outcome::Outcome;
+pub use predict::Prediction;
 pub use rating::Rating;
 pub use schedule::ScheduleReport;
 pub use time::{Time, Untimed};
@@ -142,6 +158,13 @@ pub const P_DRAW: f64 = 0.0;
 pub const EPSILON: f64 = 1e-6;
 pub const ITERATIONS: usize = 30;
 
+/// Largest team count `History::predict_outcome` will enumerate.
+///
+/// The outcome space holds `n! * 2^(n-1)` events, so it grows factorially:
+/// 1_920 at five teams, 23_040 at six, 322_560 at seven. Six is where
+/// enumerating on a caller's behalf stops being reasonable.
+pub const MAX_PREDICTED_TEAMS: usize = predict::MAX_TEAMS_FOR_DISTRIBUTION;
+
 const SQRT_TAU: f64 = 2.5066282746310002;
 
 pub const N01: Gaussian = Gaussian::from_ms(0.0, 1.0);
@@ -361,6 +384,7 @@ pub(crate) fn sort_time<T: Copy + Ord>(xs: &[T], reverse: bool) -> Vec<usize> {
 /// Panics if fewer than two rating groups are supplied, or if any group is
 /// empty — match quality is a property of a contest between at least two
 /// non-empty sides.
+#[must_use]
 pub fn quality(rating_groups: &[&[Gaussian]], beta: f64) -> f64 {
     assert!(
         rating_groups.len() >= 2,

src/observer.rs

@@ -14,8 +14,13 @@ pub trait Observer<T: Time>: Send + Sync {
     /// Called after each convergence iteration across the whole history.
     fn on_iteration_end(&self, _iter: usize, _max_step: (f64, f64)) {}
 
-    /// Called after each time slice is processed within an iteration.
+    /// Called after each time slice is swept within an iteration.
-    fn on_batch_processed(&self, _time: &T, _slice_idx: usize, _n_events: usize) {}
+    ///
+    /// A convergence iteration sweeps every slice twice — once travelling
+    /// backward through the history and once forward — so a multi-slice
+    /// history fires this twice per slice per iteration. A single-slice
+    /// history is swept once and fires once.
+    fn on_slice_processed(&self, _time: &T, _slice_idx: usize, _n_events: usize) {}
 
     /// Called once when convergence completes (or max iters is reached).
     fn on_converged(&self, _iters: usize, _final_step: (f64, f64), _converged: bool) {}
@@ -35,6 +40,7 @@ mod tests {
     fn null_observer_compiles_for_i64() {
         let o = NullObserver;
         <NullObserver as Observer<i64>>::on_iteration_end(&o, 1, (0.0, 0.0));
+        <NullObserver as Observer<i64>>::on_slice_processed(&o, &7, 0, 3);
         <NullObserver as Observer<i64>>::on_converged(&o, 5, (1e-6, 1e-6), true);
     }
 

src/outcome.rs

@@ -29,7 +29,13 @@ pub enum Outcome {
 impl Outcome {
     /// `n`-team outcome where team `winner` won and everyone else tied for last.
     ///
+    /// Note this ties every loser, so for `n >= 3` it needs a positive
+    /// `p_draw` — see `InferenceError::TieWithoutDrawProbability`.
+    ///
+    /// # Panics
+    ///
     /// Panics if `winner >= n`.
+    #[must_use]
     pub fn winner(winner: u32, n: u32) -> Self {
         assert!(winner < n, "winner index {winner} out of range 0..{n}");
         let ranks: SmallVec<[u32; 4]> = (0..n).map(|i| if i == winner { 0 } else { 1 }).collect();
@@ -37,6 +43,7 @@ impl Outcome {
     }
 
     /// All `n` teams tied.
+    #[must_use]
     pub fn draw(n: u32) -> Self {
         Self::Ranked(SmallVec::from_vec(vec![0; n as usize]))
     }
@@ -68,6 +75,7 @@ impl Outcome {
         }
     }
 
+    #[must_use]
     pub fn team_count(&self) -> usize {
         match self {
             Self::Ranked(r) => r.len(),

src/predict.rs

@@ -0,0 +1,723 @@
+//! Outcome prediction: who wins, and how likely is a given finishing order.
+//!
+//! Prediction runs on *performances*, not skills. A competitor's skill is
+//! inflated by their performance noise `beta` before any comparison, which is
+//! what separates "how good are they" from "how will they do today".
+//!
+//! Two questions, two algorithms:
+//!
+//! - **Who finishes first.** Because performances are independent Gaussians,
+//!   the probability that team `i` beats every other team separates into a
+//!   *one-dimensional* integral — no multivariate orthant integral is
+//!   involved. [`quadrature::integrate`] evaluates it to near machine
+//!   precision for a few hundred `cdf` calls.
+//! - **A specific finishing order.** The factor graph only ever constrains
+//!   rank-*adjacent* teams (see `Game::run_chain`), so the joint probability
+//!   of a full order is a chain of local constraints rather than a general
+//!   orthant probability. That chain collapses into a sequential recursion:
+//!   one cumulative integral per adjacent pair, `O(teams * grid)` overall.
+//!
+//! Both are deterministic. A sampler would have been easier to write and
+//! would have made every `predict_*` call return a slightly different number,
+//! which is not a property a rating library should have.
+
+use crate::{Gaussian, quadrature};
+
+/// Teams beyond this count make the outcome enumeration impractical.
+///
+/// Each realisation sorts into exactly one (permutation, tie-pattern) event,
+/// so the space has `n! * 2^(n-1)` members: 24 at 3 teams, 192 at 4, 1_920 at
+/// 5, 23_040 at 6. The jump to 322_560 at 7 is where enumerating stops being
+/// a reasonable thing to do on a caller's behalf.
+pub(crate) const MAX_TEAMS_FOR_DISTRIBUTION: usize = 6;
+
+/// Relative tolerance for the first-place integrals.
+///
+/// Tightening past this buys nothing: the underlying `cdf` is a rational
+/// approximation with fractional error ~1.2e-7, which contributes ~6e-9 to a
+/// finished probability and dominates any further quadrature refinement.
+const WIN_TOLERANCE: f64 = 1e-8;
+
+/// Nodes for the ranking grid, and the floor below which a grid is pointless.
+///
+/// The recursion converges as O(h^2). Measured against the exact two-team
+/// closed form, 2_048 nodes leave ~1.2e-6 of discretisation error while 8_192
+/// reach ~1e-7 — at which point the residual is the `cdf` rational
+/// approximation (~2.4e-8), not the grid, and refining further buys nothing.
+const MIN_GRID_POINTS: usize = 8_192;
+const MAX_GRID_POINTS: usize = 262_144;
+
+/// How many standard deviations of support the grid and integrals cover.
+///
+/// The normal density is below 1e-18 of its peak past nine sigma, far under
+/// the precision of everything else here.
+const SUPPORT_SIGMAS: f64 = 9.0;
+
+/// Standard normal CDF at `z`.
+fn phi(z: f64) -> f64 {
+    crate::cdf(z, 0.0, 1.0)
+}
+
+/// Normal density of `x` under `g`.
+fn density(g: Gaussian, x: f64) -> f64 {
+    let sigma = g.sigma();
+    let z = (x - g.mu()) / sigma;
+    (-0.5 * z * z).exp() / (sigma * (2.0 * std::f64::consts::PI).sqrt())
+}
+
+/// Per-pair draw margins.
+///
+/// The margin is *not* a single number for the whole game: inference derives
+/// it per rank-adjacent pair from those two teams' betas (`Game::likelihoods`).
+/// Prediction has to use the same per-pair values or it answers a question
+/// about a different model than the one that will actually be fitted.
+pub(crate) struct Margins {
+    n: usize,
+    values: Vec<f64>,
+}
+
+impl Margins {
+    /// Build from a per-pair margin function.
+    pub(crate) fn new<F: Fn(usize, usize) -> f64>(n: usize, f: F) -> Self {
+        let mut values = vec![0.0; n * n];
+        for i in 0..n {
+            for j in 0..n {
+                if i != j {
+                    values[i * n + j] = f(i, j);
+                }
+            }
+        }
+        Self { n, values }
+    }
+
+    fn get(&self, i: usize, j: usize) -> f64 {
+        self.values[i * self.n + j]
+    }
+
+    /// True when no pair can draw, so every tie has probability zero.
+    fn all_zero(&self) -> bool {
+        self.values.iter().all(|&v| v == 0.0)
+    }
+}
+
+/// `P(team i finishes strictly first)` for every team.
+///
+/// Strictly means beating each rival by more than that pair's draw margin, so
+/// with a non-zero margin these sum to less than one; the shortfall is the
+/// probability that the top place is shared.
+pub(crate) fn win_probabilities(perf: &[Gaussian], margins: &Margins) -> Vec<f64> {
+    (0..perf.len())
+        .map(|i| {
+            let (mu, sigma) = (perf[i].mu(), perf[i].sigma());
+            let (lo, hi) = (mu - SUPPORT_SIGMAS * sigma, mu + SUPPORT_SIGMAS * sigma);
+
+            // Each rival's CDF turns over near its own mean plus the margin.
+            // Seeding there is what keeps a rival with a tiny sigma — a step
+            // function in disguise — from being stepped over.
+            let mut seeds = Vec::with_capacity(3 * perf.len());
+            for (j, rival) in perf.iter().enumerate().filter(|&(j, _)| j != i) {
+                let centre = rival.mu() + margins.get(i, j);
+                seeds.extend_from_slice(&[centre - rival.sigma(), centre, centre + rival.sigma()]);
+            }
+
+            quadrature::integrate(
+                |x| {
+                    let d = density(perf[i], x);
+                    if d == 0.0 {
+                        return 0.0;
+                    }
+                    let beaten: f64 = (0..perf.len())
+                        .filter(|&j| j != i)
+                        .map(|j| phi((x - margins.get(i, j) - perf[j].mu()) / perf[j].sigma()))
+                        .product();
+                    d * beaten
+                },
+                lo,
+                hi,
+                &seeds,
+                WIN_TOLERANCE,
+            )
+        })
+        .collect()
+}
+
+/// Grid bounds and resolution covering every team's support.
+///
+/// Resolution is set by the *smallest* feature in play — the narrowest sigma,
+/// or a draw margin narrower still — because that is what the recursion has to
+/// resolve. A grid sized off the widest team would step over the narrow one.
+fn grid_shape(perf: &[Gaussian], margins: &Margins) -> (f64, f64, usize) {
+    let lo = perf
+        .iter()
+        .map(|g| g.mu() - SUPPORT_SIGMAS * g.sigma())
+        .fold(f64::INFINITY, f64::min);
+    let hi = perf
+        .iter()
+        .map(|g| g.mu() + SUPPORT_SIGMAS * g.sigma())
+        .fold(f64::NEG_INFINITY, f64::max);
+
+    let narrowest = perf
+        .iter()
+        .map(Gaussian::sigma)
+        .fold(f64::INFINITY, f64::min);
+    let smallest_margin = margins
+        .values
+        .iter()
+        .copied()
+        .filter(|&m| m > 0.0)
+        .fold(f64::INFINITY, f64::min);
+
+    let feature = narrowest.min(smallest_margin);
+    let wanted = if feature.is_finite() && feature > 0.0 {
+        ((hi - lo) / (feature / 12.0)).ceil()
+    } else {
+        MIN_GRID_POINTS as f64
+    };
+
+    let points = if wanted.is_finite() {
+        (wanted as usize).clamp(MIN_GRID_POINTS, MAX_GRID_POINTS)
+    } else {
+        MIN_GRID_POINTS
+    };
+
+    (lo, hi, points)
+}
+
+/// Densities of each team sampled on the shared grid.
+struct Sampled {
+    lo: f64,
+    step: f64,
+    points: usize,
+    density: Vec<Vec<f64>>,
+}
+
+impl Sampled {
+    fn new(perf: &[Gaussian], margins: &Margins) -> Self {
+        let (lo, hi, points) = grid_shape(perf, margins);
+        let step = (hi - lo) / (points - 1) as f64;
+        let density = perf
+            .iter()
+            .map(|&g| {
+                (0..points)
+                    .map(|i| density(g, lo + i as f64 * step))
+                    .collect()
+            })
+            .collect();
+        Self {
+            lo,
+            step,
+            points,
+            density,
+        }
+    }
+
+    fn node(&self, i: usize) -> f64 {
+        self.lo + i as f64 * self.step
+    }
+}
+
+/// `P(order[0] >= order[1] >= ... )` with the given adjacency pattern.
+///
+/// `tied[k]` says whether `order[k]` and `order[k + 1]` finish within that
+/// pair's draw margin. The recursion runs bottom-up: `carry` holds, for each
+/// grid node, the probability that everything *below* the current team holds
+/// given that team landed on that node. A strict gap reads a cumulative
+/// integral; a tie reads a window. Both are O(1) against one prefix array,
+/// so each level costs O(grid) and the whole order costs O(teams * grid).
+fn order_probability(margins: &Margins, sampled: &Sampled, order: &[usize], tied: &[bool]) -> f64 {
+    let mut carry = vec![1.0; sampled.points];
+
+    for k in (0..order.len() - 1).rev() {
+        let below = order[k + 1];
+        let above = order[k];
+        let margin = margins.get(above, below);
+
+        let integrand: Vec<f64> = (0..sampled.points)
+            .map(|i| sampled.density[below][i] * carry[i])
+            .collect();
+        let cumulative = quadrature::Grid::from_values(sampled.lo, sampled.step, integrand);
+
+        carry = (0..sampled.points)
+            .map(|i| {
+                let x = sampled.node(i);
+                if tied[k] {
+                    // Sorted order already implies `below <= above`, so the
+                    // tie window is one-sided: [x - margin, x].
+                    cumulative.integral_between(x - margin, x)
+                } else {
+                    cumulative.integral_to(x - margin)
+                }
+            })
+            .collect();
+    }
+
+    let top = order[0];
+    let integrand: Vec<f64> = (0..sampled.points)
+        .map(|i| sampled.density[top][i] * carry[i])
+        .collect();
+    quadrature::Grid::from_values(sampled.lo, sampled.step, integrand).total()
+}
+
+/// Dense ranks implied by a sorted order and its tie pattern.
+fn ranks_of(order: &[usize], tied: &[bool], n: usize) -> Vec<u32> {
+    let mut ranks = vec![0u32; n];
+    let mut rank = 0u32;
+    ranks[order[0]] = 0;
+    for k in 0..order.len() - 1 {
+        if !tied[k] {
+            rank += 1;
+        }
+        ranks[order[k + 1]] = rank;
+    }
+    ranks
+}
+
+/// Every (order, tie-pattern) event, or only the strict ones when no pair can
+/// draw — a tie then has probability exactly zero and is not worth integrating.
+fn events(n: usize, strict_only: bool) -> Vec<(Vec<usize>, Vec<bool>)> {
+    fn permute(current: &mut Vec<usize>, k: usize, out: &mut Vec<Vec<usize>>) {
+        if k == current.len() {
+            out.push(current.clone());
+            return;
+        }
+        for i in k..current.len() {
+            current.swap(k, i);
+            permute(current, k + 1, out);
+            current.swap(k, i);
+        }
+    }
+
+    let mut orders = Vec::new();
+    permute(&mut (0..n).collect(), 0, &mut orders);
+
+    let patterns: Vec<Vec<bool>> = if strict_only {
+        vec![vec![false; n - 1]]
+    } else {
+        (0..(1u32 << (n - 1)))
+            .map(|mask| (0..n - 1).map(|i| mask >> i & 1 == 1).collect())
+            .collect()
+    };
+
+    let mut out = Vec::with_capacity(orders.len() * patterns.len());
+    for order in orders {
+        for pattern in &patterns {
+            out.push((order.clone(), pattern.clone()));
+        }
+    }
+    out
+}
+
+/// The full distribution over finishing orders, aggregated by rank vector.
+///
+/// Orders that differ only *within* a tied group describe the same finishing
+/// order, so their probabilities are summed into one entry.
+pub(crate) fn outcome_distribution(perf: &[Gaussian], margins: &Margins) -> Vec<(Vec<u32>, f64)> {
+    let n = perf.len();
+    let sampled = Sampled::new(perf, margins);
+
+    let mut aggregated: Vec<(Vec<u32>, f64)> = Vec::new();
+    for (order, tied) in events(n, margins.all_zero()) {
+        let p = order_probability(margins, &sampled, &order, &tied);
+        let ranks = ranks_of(&order, &tied, n);
+        match aggregated.iter_mut().find(|(r, _)| *r == ranks) {
+            Some((_, acc)) => *acc += p,
+            None => aggregated.push((ranks, p)),
+        }
+    }
+
+    aggregated.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+    aggregated
+}
+
+/// All permutations of `items`.
+fn permutations(items: &[usize]) -> Vec<Vec<usize>> {
+    fn go(current: &mut Vec<usize>, k: usize, out: &mut Vec<Vec<usize>>) {
+        if k == current.len() {
+            out.push(current.clone());
+            return;
+        }
+        for i in k..current.len() {
+            current.swap(k, i);
+            go(current, k + 1, out);
+            current.swap(k, i);
+        }
+    }
+    let mut out = Vec::new();
+    go(&mut items.to_vec(), 0, &mut out);
+    out
+}
+
+/// Every (order, tie-pattern) event consistent with a grouping by rank.
+///
+/// Teams sharing a rank may finish in any internal order, so this is the
+/// product of each group's permutations. Adjacencies inside a group are ties;
+/// the adjacency joining one group to the next is not.
+fn orders_for_groups(groups: &[Vec<usize>]) -> Vec<(Vec<usize>, Vec<bool>)> {
+    let per_group: Vec<Vec<Vec<usize>>> = groups.iter().map(|g| permutations(g)).collect();
+
+    let mut out = Vec::new();
+    let mut choice = vec![0usize; groups.len()];
+
+    loop {
+        let mut order = Vec::new();
+        let mut tied = Vec::new();
+        for (gi, group) in per_group.iter().enumerate() {
+            for (offset, &member) in group[choice[gi]].iter().enumerate() {
+                if !order.is_empty() {
+                    tied.push(offset != 0);
+                }
+                order.push(member);
+            }
+        }
+        out.push((order, tied));
+
+        let mut k = 0;
+        loop {
+            if k == choice.len() {
+                return out;
+            }
+            choice[k] += 1;
+            if choice[k] < per_group[k].len() {
+                break;
+            }
+            choice[k] = 0;
+            k += 1;
+        }
+    }
+}
+
+/// Probability of one specific rank vector.
+///
+/// Ties in `ranks` mean the tied teams may finish in any internal order, so
+/// this sums the orders consistent with the requested ranking rather than
+/// picking one.
+pub(crate) fn ranking_probability(perf: &[Gaussian], margins: &Margins, ranks: &[u32]) -> f64 {
+    let n = perf.len();
+    let sampled = Sampled::new(perf, margins);
+
+    let mut distinct: Vec<u32> = ranks.to_vec();
+    distinct.sort_unstable();
+    distinct.dedup();
+
+    let groups: Vec<Vec<usize>> = distinct
+        .iter()
+        .map(|&r| (0..n).filter(|&i| ranks[i] == r).collect())
+        .collect();
+
+    orders_for_groups(&groups)
+        .iter()
+        .map(|(order, tied)| order_probability(margins, &sampled, order, tied))
+        .sum()
+}
+
+/// A distribution over the ways a contest could finish.
+///
+/// Each entry pairs a rank vector — the same shape [`crate::Outcome::ranking`]
+/// takes, with equal ranks meaning a tie — against its probability. Entries
+/// are ordered most likely first, and cover the whole outcome space, so the
+/// probabilities sum to one.
+///
+/// The rank vectors compose directly with inference: feeding one to
+/// `Game::ranked` asks "what would we believe if *this* happened", which is
+/// what an expected-information-gain calculation needs alongside the weight.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Prediction {
+    outcomes: Vec<(Vec<u32>, f64)>,
+}
+
+impl Prediction {
+    pub(crate) fn new(outcomes: Vec<(Vec<u32>, f64)>) -> Self {
+        Self { outcomes }
+    }
+
+    /// Every possible finishing order and its probability, most likely first.
+    pub fn outcomes(&self) -> impl ExactSizeIterator<Item = (&[u32], f64)> {
+        self.outcomes.iter().map(|(r, p)| (r.as_slice(), *p))
+    }
+
+    /// The single most likely finishing order.
+    #[must_use]
+    pub fn most_likely(&self) -> Option<(&[u32], f64)> {
+        self.outcomes.first().map(|(r, p)| (r.as_slice(), *p))
+    }
+
+    /// Probability of one specific finishing order, or zero if it cannot occur.
+    #[must_use]
+    pub fn probability_of(&self, ranks: &[u32]) -> f64 {
+        self.outcomes
+            .iter()
+            .find(|(r, _)| r.as_slice() == ranks)
+            .map_or(0.0, |(_, p)| *p)
+    }
+
+    /// `P(team i finishes strictly first)`, for each team.
+    ///
+    /// Sums to less than one exactly when the top place can be shared; the
+    /// shortfall is [`Prediction::shared_first_place`].
+    #[must_use]
+    pub fn win_probabilities(&self) -> Vec<f64> {
+        let n = self.outcomes.first().map_or(0, |(r, _)| r.len());
+        let mut wins = vec![0.0; n];
+        for (ranks, p) in &self.outcomes {
+            let leaders = ranks.iter().filter(|&&r| r == 0).count();
+            if leaders == 1 {
+                let winner = ranks.iter().position(|&r| r == 0).expect("a rank-0 team");
+                wins[winner] += p;
+            }
+        }
+        wins
+    }
+
+    /// Probability that two or more teams share first place.
+    #[must_use]
+    pub fn shared_first_place(&self) -> f64 {
+        self.outcomes
+            .iter()
+            .filter(|(r, _)| r.iter().filter(|&&x| x == 0).count() > 1)
+            .map(|(_, p)| p)
+            .sum()
+    }
+
+    /// Total probability mass, which should be one.
+    ///
+    /// Exposed because it is a genuine check on the numerics rather than a
+    /// formality: the outcome space is exhaustive and disjoint by construction,
+    /// so any drift from one is integration error and nothing else.
+    #[must_use]
+    pub fn total(&self) -> f64 {
+        self.outcomes.iter().map(|(_, p)| p).sum()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn g(mu: f64, sigma: f64) -> Gaussian {
+        Gaussian::from_ms(mu, sigma)
+    }
+
+    fn flat(n: usize, eps: f64) -> Margins {
+        Margins::new(n, |_, _| eps)
+    }
+
+    /// Exact two-team result: `P(a first) = Phi((mu_a - mu_b - eps) / sd)`.
+    fn closed_form_two(a: Gaussian, b: Gaussian, eps: f64) -> (f64, f64) {
+        let sd = (a.sigma().powi(2) + b.sigma().powi(2)).sqrt();
+        (
+            phi((a.mu() - b.mu() - eps) / sd),
+            phi((b.mu() - a.mu() - eps) / sd),
+        )
+    }
+
+    #[test]
+    fn two_team_win_probabilities_match_the_closed_form() {
+        for (ma, sa, mb, sb, eps) in [
+            (0.0, 6.0, 0.0, 6.0, 0.0),
+            (3.0, 6.0, -2.0, 1.0, 0.0),
+            (0.0, 6.0, 0.0, 6.0, 2.0),
+            (3.0, 6.0, -2.0, 1.0, 1.5),
+            (40.0, 1.0, 0.0, 1.0, 0.0),
+        ] {
+            let perf = [g(ma, sa), g(mb, sb)];
+            let got = win_probabilities(&perf, &flat(2, eps));
+            let (wa, wb) = closed_form_two(perf[0], perf[1], eps);
+            assert!(
+                (got[0] - wa).abs() < 1e-7 && (got[1] - wb).abs() < 1e-7,
+                "mu=({ma},{mb}) sigma=({sa},{sb}) eps={eps}: got {got:?}, want [{wa}, {wb}]"
+            );
+        }
+    }
+
+    /// The identity that a wrong-but-plausible implementation cannot fake:
+    /// with no draw margin, exactly one team finishes first.
+    #[test]
+    fn win_probabilities_sum_to_one_without_a_draw_margin() {
+        for perf in [
+            vec![g(0.0, 6.0), g(0.0, 6.0)],
+            vec![g(5.0, 6.0), g(0.0, 3.0), g(-5.0, 1.0)],
+            vec![
+                g(8.0, 2.0),
+                g(3.0, 6.0),
+                g(0.0, 1.0),
+                g(-3.0, 4.0),
+                g(-8.0, 6.0),
+            ],
+        ] {
+            let sum: f64 = win_probabilities(&perf, &flat(perf.len(), 0.0))
+                .iter()
+                .sum();
+            assert!(
+                (sum - 1.0).abs() < 1e-7,
+                "{} teams: sum = {sum}",
+                perf.len()
+            );
+        }
+    }
+
+    /// A rival with a tiny sigma is a step function in disguise. Fixed-node
+    /// quadrature steps over it and lands ~1e-2 out while still looking like a
+    /// probability; this is the case that rules that approach out.
+    #[test]
+    fn win_probabilities_survive_a_rival_with_a_tiny_sigma() {
+        let perf = [g(0.0, 0.001), g(0.5, 6.0), g(-0.5, 6.0)];
+        let got = win_probabilities(&perf, &flat(3, 0.0));
+        let sum: f64 = got.iter().sum();
+        assert!((sum - 1.0).abs() < 1e-6, "sum = {sum}, probs = {got:?}");
+    }
+
+    #[test]
+    fn a_stronger_team_is_more_likely_to_win() {
+        let perf = [g(10.0, 3.0), g(0.0, 3.0), g(-10.0, 3.0)];
+        let p = win_probabilities(&perf, &flat(3, 0.0));
+        assert!(p[0] > p[1] && p[1] > p[2], "not monotone: {p:?}");
+    }
+
+    #[test]
+    fn identical_teams_are_equally_likely_to_win() {
+        let perf = [g(1.0, 4.0), g(1.0, 4.0), g(1.0, 4.0)];
+        let p = win_probabilities(&perf, &flat(3, 0.0));
+        for probs in p.windows(2) {
+            assert!((probs[0] - probs[1]).abs() < 1e-9, "asymmetric: {p:?}");
+        }
+    }
+
+    /// Every realisation sorts into exactly one finishing order, so the whole
+    /// distribution must sum to one — with or without a draw margin.
+    #[test]
+    fn outcome_distribution_sums_to_one() {
+        for (perf, eps) in [
+            (vec![g(0.0, 6.0), g(0.0, 6.0)], 0.0),
+            (vec![g(0.0, 6.0), g(0.0, 6.0)], 2.0),
+            (vec![g(0.0, 6.0), g(0.0, 6.0), g(0.0, 6.0)], 0.0),
+            (vec![g(5.0, 6.0), g(0.0, 3.0), g(-5.0, 1.0)], 1.5),
+            (vec![g(0.0, 0.05), g(0.5, 6.0), g(-0.5, 6.0)], 1.0),
+            (
+                vec![g(6.0, 2.0), g(2.0, 6.0), g(-2.0, 1.0), g(-6.0, 4.0)],
+                1.0,
+            ),
+        ] {
+            let n = perf.len();
+            let dist = outcome_distribution(&perf, &flat(n, eps));
+            let sum: f64 = dist.iter().map(|(_, p)| p).sum();
+            assert!(
+                (sum - 1.0).abs() < 1e-6,
+                "{n} teams, eps={eps}: sum = {sum} over {} outcomes",
+                dist.len()
+            );
+            assert!(dist.iter().all(|(_, p)| *p >= 0.0), "negative probability");
+        }
+    }
+
+    /// With two teams the distribution is the exact win/draw/loss triple.
+    #[test]
+    fn two_team_distribution_matches_the_closed_form() {
+        let perf = [g(3.0, 6.0), g(-2.0, 1.0)];
+        let eps = 1.5;
+        let dist = outcome_distribution(&perf, &flat(2, eps));
+        let (wa, wb) = closed_form_two(perf[0], perf[1], eps);
+
+        let find = |ranks: &[u32]| {
+            dist.iter()
+                .find(|(r, _)| r == ranks)
+                .map_or(0.0, |(_, p)| *p)
+        };
+
+        assert!(
+            (find(&[0, 1]) - wa).abs() < 1e-6,
+            "a wins: {}",
+            find(&[0, 1])
+        );
+        assert!(
+            (find(&[1, 0]) - wb).abs() < 1e-6,
+            "b wins: {}",
+            find(&[1, 0])
+        );
+        assert!(
+            (find(&[0, 0]) - (1.0 - wa - wb)).abs() < 1e-6,
+            "draw: {}",
+            find(&[0, 0])
+        );
+    }
+
+    /// Asking for one ranking must agree with that ranking's entry in the
+    /// full distribution — the two use different code paths to the same value.
+    #[test]
+    fn ranking_probability_agrees_with_the_distribution() {
+        let perf = [g(5.0, 6.0), g(0.0, 3.0), g(-5.0, 1.0)];
+        let eps = 1.5;
+        let margins = flat(3, eps);
+        let dist = outcome_distribution(&perf, &margins);
+
+        for (ranks, expected) in &dist {
+            let direct = ranking_probability(&perf, &margins, ranks);
+            assert!(
+                (direct - expected).abs() < 1e-9,
+                "ranks {ranks:?}: direct {direct} vs distribution {expected}"
+            );
+        }
+    }
+
+    /// Tie mass is controlled by the draw margin. Only the *all-tied* outcome
+    /// is monotone in it: every one of its constraints is a window that widens
+    /// with the margin. A partially-tied outcome like `[0, 0, 1]` is not, and
+    /// must not be asserted to be — widening the margin makes its tie easier
+    /// but its "and the last team is strictly behind by more than the margin"
+    /// clause harder, so it peaks and then falls.
+    #[test]
+    fn all_tied_probability_grows_with_the_draw_margin() {
+        let perf = [g(0.0, 4.0), g(0.0, 4.0), g(-8.0, 2.0)];
+        let mut previous = 0.0;
+        for eps in [0.0, 0.5, 1.0, 2.0, 4.0, 8.0, 24.0] {
+            let p = ranking_probability(&perf, &flat(3, eps), &[0, 0, 0]);
+            assert!(p >= previous, "eps={eps}: {p} < {previous}");
+            if eps == 0.0 {
+                assert!(p < 1e-12, "a tie needs a margin, got {p}");
+            }
+            previous = p;
+        }
+        assert!(
+            previous > 0.9,
+            "a very wide margin ties everyone: {previous}"
+        );
+    }
+
+    /// The converse, stated as the non-property it is: a partially-tied
+    /// outcome is non-monotone in the margin. Pinning this down stops a future
+    /// change from "fixing" it into monotonicity and quietly breaking the model.
+    #[test]
+    fn a_partially_tied_outcome_peaks_in_the_middle() {
+        let perf = [g(0.0, 4.0), g(0.0, 4.0), g(-8.0, 2.0)];
+        let sweep: Vec<f64> = [0.5, 2.0, 4.0, 8.0, 16.0]
+            .iter()
+            .map(|&eps| ranking_probability(&perf, &flat(3, eps), &[0, 0, 1]))
+            .collect();
+        let peak = sweep
+            .iter()
+            .enumerate()
+            .fold(
+                (0, 0.0),
+                |(bi, bv), (i, &v)| if v > bv { (i, v) } else { (bi, bv) },
+            )
+            .0;
+        assert!(
+            peak > 0 && peak < sweep.len() - 1,
+            "expected an interior peak: {sweep:?}"
+        );
+    }
+
+    /// With no draw margin a tie has probability exactly zero, and the
+    /// enumeration must not waste work pretending otherwise.
+    #[test]
+    fn ties_are_impossible_without_a_draw_margin() {
+        let perf = [g(0.0, 4.0), g(0.0, 4.0), g(0.0, 4.0)];
+        let dist = outcome_distribution(&perf, &flat(3, 0.0));
+        assert_eq!(dist.len(), 6, "expected only the 6 strict orders: {dist:?}");
+        assert!(dist.iter().all(|(r, _)| {
+            let mut seen = r.clone();
+            seen.sort_unstable();
+            seen.dedup();
+            seen.len() == r.len()
+        }));
+    }
+}

src/quadrature.rs

@@ -0,0 +1,322 @@
+//! Deterministic numerical integration for the prediction paths.
+//!
+//! Prediction asks two questions that have no closed form beyond two teams:
+//! "who finishes first" and "how likely is this exact finishing order". Both
+//! reduce to integrals over a single performance variable, so neither needs a
+//! sampler — and that matters, because a Monte Carlo predictor would make
+//! `predict_*` non-reproducible and would answer a slightly different question
+//! on every call.
+//!
+//! Two routines live here:
+//!
+//! - [`integrate`], adaptive Gauss-Kronrod G7-K15, for the first-place
+//!   marginals. It carries its own error estimate, so it can refine where the
+//!   integrand actually bends instead of guessing a node count up front.
+//! - [`Grid`], a uniform grid with trapezoid prefix sums, for the ranking
+//!   chain recursion, where each level needs the *running* integral of the
+//!   level below at arbitrary points rather than one definite integral.
+//!
+//! Fixed-node Gauss-Hermite is the obvious tool for the first of these and is
+//! a trap: the integrand is a product of normal CDFs, and when one team's
+//! sigma is much smaller than the integrating team's, that product turns into
+//! a near-step function narrower than the node spacing. The nodes step over
+//! it and the result is wrong by ~1e-2 while still looking like a probability.
+//! Adaptive refinement is what makes the small-sigma case safe.
+
+/// Kronrod 15-point abscissae, non-negative half, descending.
+const XGK: [f64; 8] = [
+    0.991_455_371_120_813,
+    0.949_107_912_342_759,
+    0.864_864_423_359_769,
+    0.741_531_185_599_394,
+    0.586_087_235_467_691,
+    0.405_845_151_377_397,
+    0.207_784_955_007_898,
+    0.0,
+];
+
+/// Kronrod 15-point weights, matching [`XGK`].
+const WGK: [f64; 8] = [
+    0.022_935_322_010_529,
+    0.063_092_092_629_979,
+    0.104_790_010_322_250,
+    0.140_653_259_715_525,
+    0.169_004_726_639_267,
+    0.190_350_578_064_785,
+    0.204_432_940_075_298,
+    0.209_482_141_084_728,
+];
+
+/// Gauss 7-point weights, applying to the odd-indexed [`XGK`] entries.
+const WG: [f64; 4] = [
+    0.129_484_966_168_870,
+    0.279_705_391_489_277,
+    0.381_830_050_505_119,
+    0.417_959_183_673_469,
+];
+
+/// Panels are bisected worst-first; this bounds the work on a pathological
+/// integrand rather than letting it spin.
+const MAX_SUBDIVISIONS: usize = 200;
+
+/// One G7-K15 panel over `[a, b]`: `(integral, absolute error estimate)`.
+///
+/// The error estimate is the gap between the embedded 7-point Gauss rule and
+/// the 15-point Kronrod extension. It is the only reason this is preferable
+/// to a fixed rule: it tells the caller *where* the integrand is hard.
+fn gk15<F: Fn(f64) -> f64>(f: &F, a: f64, b: f64) -> (f64, f64) {
+    let centre = 0.5 * (a + b);
+    let half = 0.5 * (b - a);
+
+    let mut kronrod = 0.0;
+    let mut gauss = 0.0;
+
+    for i in 0..8 {
+        let offset = XGK[i] * half;
+        // XGK[7] is the centre node and must not be counted twice.
+        let sum = if i == 7 {
+            f(centre)
+        } else {
+            f(centre - offset) + f(centre + offset)
+        };
+        kronrod += WGK[i] * sum;
+        if i % 2 == 1 {
+            gauss += WG[i / 2] * sum;
+        }
+    }
+
+    (kronrod * half, ((kronrod - gauss) * half).abs())
+}
+
+/// Adaptively integrate `f` over `[a, b]` to relative tolerance `tol`.
+///
+/// `seeds` are interior points where the integrand is known to bend sharply —
+/// for a product of normal CDFs, each rival's transition centre. Splitting
+/// there up front costs nothing and saves the adaptive loop from having to
+/// discover a step by bisection.
+///
+/// Returns the integral. The error estimate is consumed internally rather
+/// than returned: callers here integrate probability densities, where the
+/// meaningful check is the sum-to-one identity over a whole outcome space,
+/// not a per-integral residual.
+pub(crate) fn integrate<F: Fn(f64) -> f64>(f: F, a: f64, b: f64, seeds: &[f64], tol: f64) -> f64 {
+    // Explicit rather than `!(b > a)`: a NaN bound must fall through to zero
+    // rather than being read as a valid ordering.
+    if a.partial_cmp(&b) != Some(std::cmp::Ordering::Less) {
+        return 0.0;
+    }
+
+    let mut edges: Vec<f64> = Vec::with_capacity(seeds.len() + 2);
+    edges.push(a);
+    edges.push(b);
+    for &s in seeds {
+        if s > a && s < b {
+            edges.push(s);
+        }
+    }
+    edges.sort_by(|p, q| p.partial_cmp(q).expect("integration bounds are finite"));
+    edges.dedup();
+
+    // (lo, hi, integral, error)
+    let mut panels: Vec<(f64, f64, f64, f64)> = edges
+        .windows(2)
+        .map(|w| {
+            let (v, e) = gk15(&f, w[0], w[1]);
+            (w[0], w[1], v, e)
+        })
+        .collect();
+
+    for _ in 0..MAX_SUBDIVISIONS {
+        let total: f64 = panels.iter().map(|p| p.2).sum();
+        let error: f64 = panels.iter().map(|p| p.3).sum();
+
+        // Absolute floor as well as relative: these integrands are
+        // probabilities, so an absolute 1e-15 is already past the useful
+        // precision of the underlying `cdf`.
+        if error <= tol * total.abs().max(1e-12) || error < 1e-15 {
+            break;
+        }
+
+        let worst = panels
+            .iter()
+            .enumerate()
+            .fold((0usize, f64::NEG_INFINITY), |(bi, be), (i, p)| {
+                if p.3 > be { (i, p.3) } else { (bi, be) }
+            })
+            .0;
+
+        let (lo, hi, _, _) = panels[worst];
+        let mid = 0.5 * (lo + hi);
+        // Bisection has hit the floating-point floor; refining further would
+        // loop without reducing the error.
+        if !(mid > lo && mid < hi) {
+            break;
+        }
+
+        let (v1, e1) = gk15(&f, lo, mid);
+        let (v2, e2) = gk15(&f, mid, hi);
+        panels[worst] = (lo, mid, v1, e1);
+        panels.push((mid, hi, v2, e2));
+    }
+
+    panels.iter().map(|p| p.2).sum()
+}
+
+/// A uniform grid carrying trapezoid prefix sums of one integrand.
+///
+/// The ranking recursion needs, at every level, the running integral of the
+/// level below evaluated at arbitrary points — a cumulative integral, not a
+/// definite one. Prefix sums give that in O(1) per query after an O(G) build,
+/// which is what keeps a full ranking probability linear in the team count.
+pub(crate) struct Grid {
+    lo: f64,
+    step: f64,
+    /// Integrand sampled at each node.
+    values: Vec<f64>,
+    /// `prefix[i]` is the integral from `lo` to node `i`.
+    prefix: Vec<f64>,
+}
+
+impl Grid {
+    /// Build directly from already-sampled values.
+    ///
+    /// The ranking recursion evaluates every level on the same nodes, so the
+    /// per-team densities are sampled once and reused; re-evaluating `exp`
+    /// per level would dominate the cost.
+    pub(crate) fn from_values(lo: f64, step: f64, values: Vec<f64>) -> Self {
+        let mut prefix = vec![0.0; values.len()];
+        for i in 1..values.len() {
+            prefix[i] = prefix[i - 1] + 0.5 * step * (values[i - 1] + values[i]);
+        }
+        Self {
+            lo,
+            step,
+            values,
+            prefix,
+        }
+    }
+
+    /// Integral from the grid's lower bound up to `x`.
+    ///
+    /// Clamped at both ends: the caller sizes the grid to cover the whole
+    /// support, so a query outside it is asking for a tail that is zero (below)
+    /// or the whole mass (above).
+    pub(crate) fn integral_to(&self, x: f64) -> f64 {
+        let last = self.values.len() - 1;
+        if x <= self.lo {
+            return 0.0;
+        }
+        if x >= self.lo + last as f64 * self.step {
+            return self.prefix[last];
+        }
+
+        let scaled = (x - self.lo) / self.step;
+        let i = scaled.floor() as usize;
+        let frac = scaled - i as f64;
+
+        // Whole cells, plus the trapezoid over the partial cell. The integrand
+        // is linear within a cell under the trapezoid rule, so the partial
+        // piece is exact with respect to that same approximation.
+        self.prefix[i]
+            + frac
+                * self.step
+                * (self.values[i] + 0.5 * frac * (self.values[i + 1] - self.values[i]))
+    }
+
+    /// Integral over `[from, to]`.
+    pub(crate) fn integral_between(&self, from: f64, to: f64) -> f64 {
+        (self.integral_to(to) - self.integral_to(from)).max(0.0)
+    }
+
+    /// Total integral over the whole grid.
+    pub(crate) fn total(&self) -> f64 {
+        self.prefix[self.values.len() - 1]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const TOL: f64 = 1e-10;
+
+    /// Sample `f` over `[lo, hi]` at `points` nodes.
+    fn sample<F: FnMut(f64) -> f64>(lo: f64, hi: f64, points: usize, mut f: F) -> Grid {
+        let step = (hi - lo) / (points - 1) as f64;
+        Grid::from_values(
+            lo,
+            step,
+            (0..points).map(|i| f(lo + i as f64 * step)).collect(),
+        )
+    }
+
+    #[test]
+    fn integrates_a_polynomial_exactly() {
+        // G7-K15 is exact for polynomials well past cubic, so a single panel
+        // should already be at round-off.
+        let v = integrate(|x| 3.0 * x * x + 2.0 * x + 1.0, 0.0, 2.0, &[], TOL);
+        assert!((v - 14.0).abs() < 1e-12, "got {v}");
+    }
+
+    #[test]
+    fn integrates_a_gaussian_density_to_one() {
+        let f = |x: f64| (-0.5 * x * x).exp() / (2.0 * std::f64::consts::PI).sqrt();
+        let v = integrate(f, -10.0, 10.0, &[], TOL);
+        assert!((v - 1.0).abs() < 1e-12, "got {v}");
+    }
+
+    #[test]
+    fn resolves_a_step_far_narrower_than_the_initial_panel() {
+        // The failure mode that rules out fixed-node quadrature: a transition
+        // 1e-4 wide inside a range of 20. A fixed rule steps over it.
+        let f = |x: f64| if x < 0.5 { 0.0 } else { 1.0 };
+        let v = integrate(f, -10.0, 10.0, &[0.5], TOL);
+        assert!((v - 9.5).abs() < 1e-6, "got {v}");
+    }
+
+    #[test]
+    fn seeds_do_not_change_the_value_of_a_smooth_integrand() {
+        let f = |x: f64| (-0.5 * x * x).exp();
+        let plain = integrate(f, -8.0, 8.0, &[], TOL);
+        let seeded = integrate(f, -8.0, 8.0, &[-3.0, 0.25, 5.5], TOL);
+        assert!((plain - seeded).abs() < 1e-12, "{plain} vs {seeded}");
+    }
+
+    #[test]
+    fn empty_or_inverted_range_integrates_to_zero() {
+        assert_eq!(integrate(|_| 1.0, 1.0, 1.0, &[], TOL), 0.0);
+        assert_eq!(integrate(|_| 1.0, 2.0, 1.0, &[], TOL), 0.0);
+    }
+
+    #[test]
+    fn grid_prefix_matches_a_known_cumulative_integral() {
+        // f(x) = x over [0, 4]; integral to x is x^2/2.
+        let g = sample(0.0, 4.0, 4001, |x| x);
+        for probe in [0.0, 0.5, 1.0, 2.5, 3.75, 4.0] {
+            let want = probe * probe / 2.0;
+            let got = g.integral_to(probe);
+            assert!(
+                (got - want).abs() < 1e-9,
+                "at {probe}: got {got}, want {want}"
+            );
+        }
+        assert!((g.total() - 8.0).abs() < 1e-9);
+    }
+
+    #[test]
+    fn grid_between_is_the_difference_of_two_prefixes() {
+        let g = sample(-5.0, 5.0, 8001, |x| (-0.5 * x * x).exp());
+        let whole = g.integral_between(-5.0, 5.0);
+        let split = g.integral_between(-5.0, 0.3) + g.integral_between(0.3, 5.0);
+        assert!((whole - split).abs() < 1e-12, "{whole} vs {split}");
+    }
+
+    #[test]
+    fn grid_clamps_queries_outside_its_support() {
+        let g = sample(0.0, 1.0, 101, |_| 1.0);
+        assert_eq!(g.integral_to(-3.0), 0.0);
+        assert!((g.integral_to(9.0) - 1.0).abs() < 1e-12);
+        // Reversed bounds must not produce negative probability mass.
+        assert_eq!(g.integral_between(0.8, 0.2), 0.0);
+    }
+}

src/rating.rs

@@ -9,13 +9,16 @@ use crate::{
 
 /// Static rating configuration: prior skill, performance noise `beta`, drift.
 ///
-/// Renamed from `Player` in T2; `Rating` better describes the data
+/// A configuration rather than a person: the per-history temporal state
-/// (a configuration) vs. a person (who's a `Competitor` with state).
+/// (messages, last appearance) lives on `Competitor`.
 #[derive(Clone, Copy, Debug)]
 pub struct Rating<T: Time = i64, D: Drift<T> = ConstantDrift> {
     pub(crate) prior: Gaussian,
     pub(crate) beta: f64,
     pub(crate) drift: D,
+    /// Multiplier on the drift *variance* this competitor accumulates; 1.0 is
+    /// the neutral default. Set per competitor via `Member::with_drift_scale`.
+    pub(crate) drift_scale: f64,
     pub(crate) _time: PhantomData<T>,
 }
 
@@ -25,10 +28,21 @@ impl<T: Time, D: Drift<T>> Rating<T, D> {
             prior,
             beta,
             drift,
+            drift_scale: 1.0,
             _time: PhantomData,
         }
     }
 
+    /// Scale how fast this competitor drifts, relative to `drift`.
+    ///
+    /// Multiplies the drift *variance*, so the scale is in the same units as
+    /// `gamma`. `0.0` pins the competitor still.
+    #[must_use]
+    pub fn with_drift_scale(mut self, drift_scale: f64) -> Self {
+        self.drift_scale = drift_scale;
+        self
+    }
+
     /// The configured prior skill estimate.
     #[must_use]
     pub fn prior(&self) -> Gaussian {
@@ -47,6 +61,28 @@ impl<T: Time, D: Drift<T>> Rating<T, D> {
         self.drift
     }
 
+    /// This competitor's multiplier on the drift variance; 1.0 is neutral.
+    #[must_use]
+    pub fn drift_scale(&self) -> f64 {
+        self.drift_scale
+    }
+
+    /// Drift variance accumulated over `from -> to`, scaled for this competitor.
+    ///
+    /// The single place the scale is applied for a `Time`-typed span. Callers
+    /// must go through this rather than `self.drift` directly, so a competitor's
+    /// scale cannot be silently skipped.
+    pub(crate) fn drift_variance_delta(&self, from: &T, to: &T) -> f64 {
+        self.drift.variance_delta(from, to) * self.drift_scale * self.drift_scale
+    }
+
+    /// Drift variance for a cached elapsed count, scaled for this competitor.
+    ///
+    /// The counterpart of `drift_variance_delta` for the cached-elapsed paths.
+    pub(crate) fn drift_variance_for_elapsed(&self, elapsed: i64) -> f64 {
+        self.drift.variance_for_elapsed(elapsed) * self.drift_scale * self.drift_scale
+    }
+
     pub(crate) fn performance(&self) -> Gaussian {
         self.prior.forget(self.beta.powi(2))
     }
@@ -58,6 +94,7 @@ impl Default for Rating<i64, ConstantDrift> {
             prior: Gaussian::default(),
             beta: BETA,
             drift: ConstantDrift(GAMMA),
+            drift_scale: 1.0,
             _time: PhantomData,
         }
     }

src/schedule.rs

@@ -1,7 +1,7 @@
 //! Schedule trait and built-in implementations.
 //!
 //! A schedule drives factor propagation to convergence. The default
-//! `EpsilonOrMax` performs one TeamSum sweep (setup) then alternating
+//! `EpsilonOrMax` performs one `TeamSum` sweep (setup) then alternating
 //! forward/backward sweeps over the iterating factors until the max
 //! delta drops below epsilon or `max` iterations is reached.
 
@@ -23,7 +23,7 @@ pub trait Schedule: Send + Sync {
 /// Default schedule: sweep forward then backward until step ≤ eps or iter == max.
 ///
 /// Matches the existing `Game::likelihoods` loop bit-for-bit when given the
-/// same factor layout (TeamSums first, then alternating RankDiff/Trunc pairs).
+/// same factor layout (`TeamSums` first, then alternating RankDiff/Trunc pairs).
 #[derive(Debug, Clone, Copy)]
 pub struct EpsilonOrMax {
     pub eps: f64,

src/storage/competitor_store.rs

@@ -2,7 +2,7 @@ use crate::{Index, competitor::Competitor, drift::Drift, time::Time};
 
 /// Dense Vec-backed store for competitor state in History.
 ///
-/// Indexed directly by Index.0, eliminating HashMap hashing in the
+/// Indexed directly by Index.0, eliminating `HashMap` hashing in the
 /// forward/backward sweep. Uses `Vec<Option<Competitor<T, D>>>` so slots can be
 /// absent without an explicit present mask.
 #[derive(Debug)]
@@ -21,6 +21,7 @@ impl<T: Time, D: Drift<T>> Default for CompetitorStore<T, D> {
 }
 
 impl<T: Time, D: Drift<T>> CompetitorStore<T, D> {
+    #[must_use]
     pub fn new() -> Self {
         Self::default()
     }
@@ -39,6 +40,7 @@ impl<T: Time, D: Drift<T>> CompetitorStore<T, D> {
         self.competitors[idx.0] = Some(competitor);
     }
 
+    #[must_use]
     pub fn get(&self, idx: Index) -> Option<&Competitor<T, D>> {
         self.competitors.get(idx.0).and_then(|slot| slot.as_ref())
     }
@@ -49,14 +51,17 @@ impl<T: Time, D: Drift<T>> CompetitorStore<T, D> {
             .and_then(|slot| slot.as_mut())
     }
 
+    #[must_use]
     pub fn contains(&self, idx: Index) -> bool {
         self.get(idx).is_some()
     }
 
+    #[must_use]
     pub fn len(&self) -> usize {
         self.n_present
     }
 
+    #[must_use]
     pub fn is_empty(&self) -> bool {
         self.n_present == 0
     }

src/storage/skill_store.rs

@@ -1,15 +1,27 @@
+use std::collections::HashMap;
+
 use crate::{Index, time_slice::Skill};
 
-/// Dense Vec-backed store for per-agent skill state within a TimeSlice.
+/// Compact per-slice store for skill state, addressed by a slice-local slot.
 ///
-/// Indexed directly by Index.0, eliminating HashMap hashing in the inner
+/// `skills` holds one entry per competitor **in this slice**, so memory is
-/// convergence loop. Uses a parallel `present` mask so iteration skips
+/// O(competitors in the slice). It used to be a dense `Vec<Skill>` indexed by
-/// absent slots without incurring per-slot Option overhead in the hot path.
+/// the global `Index.0`, which made a slice's footprint O(largest index it
+/// touches): a single 1v1 game between competitors 19998 and 19999 reserved
+/// 20,000 slots.
+///
+/// The dense layout existed to keep `HashMap` hashing out of the inner
+/// convergence loop, and that property is preserved. `slots` is consulted only
+/// while building a slice; every hot-path access goes through
+/// [`SkillStore::at`] / [`SkillStore::at_mut`] with a slot resolved once at
+/// ingestion and cached on the event's `Item`.
 #[derive(Debug, Default)]
 pub struct SkillStore {
     skills: Vec<Skill>,
-    present: Vec<bool>,
+    /// Slot -> global index, parallel to `skills`, so iteration can report the
-    n_present: usize,
+    /// global index without a reverse lookup.
+    indices: Vec<Index>,
+    slots: HashMap<Index, u32>,
 }
 
 impl SkillStore {
@@ -17,73 +29,99 @@ impl SkillStore {
         Self::default()
     }
 
-    fn ensure_capacity(&mut self, idx: usize) {
+    /// Resolve a global index to this slice's slot, if the competitor is here.
-        if idx >= self.skills.len() {
+    ///
-            self.skills.resize_with(idx + 1, Skill::default);
+    /// This hashes. Call it at ingestion and cache the result; do not call it
-            self.present.resize(idx + 1, false);
+    /// from the convergence loop.
-        }
+    pub fn slot_of(&self, idx: Index) -> Option<u32> {
+        self.slots.get(&idx).copied()
     }
 
-    pub fn insert(&mut self, idx: Index, skill: Skill) {
+    /// Skill at a slot resolved earlier by [`SkillStore::slot_of`].
-        self.ensure_capacity(idx.0);
+    ///
-        if !self.present[idx.0] {
+    /// # Panics
-            self.n_present += 1;
+    ///
+    /// Panics if `slot` is out of range, which means it came from a different
+    /// slice's store.
+    pub fn at(&self, slot: u32) -> &Skill {
+        &self.skills[slot as usize]
+    }
+
+    /// Mutable counterpart to [`SkillStore::at`].
+    ///
+    /// # Panics
+    ///
+    /// Panics if `slot` is out of range.
+    pub fn at_mut(&mut self, slot: u32) -> &mut Skill {
+        &mut self.skills[slot as usize]
+    }
+
+    /// Insert or overwrite a competitor's skill, returning its slot.
+    pub fn insert(&mut self, idx: Index, skill: Skill) -> u32 {
+        match self.slots.get(&idx) {
+            Some(&slot) => {
+                self.skills[slot as usize] = skill;
+                slot
+            }
+            None => {
+                let slot = u32::try_from(self.skills.len())
+                    .expect("a time slice cannot hold more than u32::MAX competitors");
+
+                self.skills.push(skill);
+                self.indices.push(idx);
+                self.slots.insert(idx, slot);
+
+                slot
+            }
         }
-        self.skills[idx.0] = skill;
-        self.present[idx.0] = true;
     }
 
     pub fn get(&self, idx: Index) -> Option<&Skill> {
-        if idx.0 < self.present.len() && self.present[idx.0] {
+        self.slot_of(idx).map(|slot| self.at(slot))
-            Some(&self.skills[idx.0])
-        } else {
-            None
-        }
-    }
-
-    /// Whether a slot is occupied. Test-only.
-    #[cfg(test)]
-    pub fn contains(&self, idx: Index) -> bool {
-        idx.0 < self.present.len() && self.present[idx.0]
-    }
-
-    /// Number of occupied slots. Test-only.
-    #[cfg(test)]
-    pub fn len(&self) -> usize {
-        self.n_present
     }
 
     pub fn get_mut(&mut self, idx: Index) -> Option<&mut Skill> {
-        if idx.0 < self.present.len() && self.present[idx.0] {
+        self.slot_of(idx)
-            Some(&mut self.skills[idx.0])
+            .map(|slot| &mut self.skills[slot as usize])
-        } else {
-            None
-        }
     }
 
+    /// Whether a competitor is present in this slice. Test-only.
+    #[cfg(test)]
+    pub fn contains(&self, idx: Index) -> bool {
+        self.slots.contains_key(&idx)
+    }
+
+    /// Number of competitors in this slice. Test-only.
+    #[cfg(test)]
+    pub fn len(&self) -> usize {
+        self.skills.len()
+    }
+
+    /// Slots actually allocated — the quantity #17 is about, and NOT the same
+    /// as `len` for every possible implementation.
+    ///
+    /// A store indexed by the global `Index` must report `max_index + 1` here
+    /// while reporting the true competitor count from `len`, which is exactly
+    /// how the original defect hid. Tests that mean to pin the footprint must
+    /// assert on this.
+    #[cfg(test)]
+    pub fn allocated_slots(&self) -> usize {
+        self.skills.len()
+    }
+
+    /// Iterate in slot order — the order competitors were first seen in this
+    /// slice. Deterministic for a given event order, which is what the
+    /// cross-thread determinism test relies on.
     pub fn iter(&self) -> impl Iterator<Item = (Index, &Skill)> {
-        self.present.iter().enumerate().filter_map(|(i, &p)| {
+        self.indices.iter().copied().zip(self.skills.iter())
-            if p {
-                Some((Index(i), &self.skills[i]))
-            } else {
-                None
-            }
-        })
     }
 
     pub fn iter_mut(&mut self) -> impl Iterator<Item = (Index, &mut Skill)> {
-        self.skills
+        self.indices.iter().copied().zip(self.skills.iter_mut())
-            .iter_mut()
-            .zip(self.present.iter())
-            .enumerate()
-            .filter_map(|(i, (s, &p))| if p { Some((Index(i), s)) } else { None })
     }
 
     pub fn keys(&self) -> impl Iterator<Item = Index> + '_ {
-        self.present
+        self.indices.iter().copied()
-            .iter()
-            .enumerate()
-            .filter_map(|(i, &p)| if p { Some(Index(i)) } else { None })
     }
 }
 
@@ -109,7 +147,7 @@ mod tests {
     }
 
     #[test]
-    fn iter_skips_absent_slots() {
+    fn iter_reports_global_indices() {
         let mut store = SkillStore::new();
         store.insert(Index(0), Skill::default());
         store.insert(Index(5), Skill::default());
@@ -124,4 +162,28 @@ mod tests {
         store.insert(Index(2), Skill::default());
         assert_eq!(store.len(), 1);
     }
+
+    /// The defect in #17: a slice holding two competitors must cost the same
+    /// whether their indices are small or large.
+    #[test]
+    fn footprint_is_independent_of_index_magnitude() {
+        let mut low = SkillStore::new();
+        low.insert(Index(0), Skill::default());
+        low.insert(Index(1), Skill::default());
+
+        let mut high = SkillStore::new();
+        high.insert(Index(19_998), Skill::default());
+        high.insert(Index(19_999), Skill::default());
+
+        assert_eq!(low.len(), high.len());
+        assert_eq!(low.skills.capacity(), high.skills.capacity());
+    }
+
+    #[test]
+    fn slot_survives_reinsert() {
+        let mut store = SkillStore::new();
+        let first = store.insert(Index(7), Skill::default());
+        let again = store.insert(Index(7), Skill::default());
+        assert_eq!(first, again);
+    }
 }

src/time_slice.rs

@@ -51,6 +51,13 @@ pub enum EventKind {
 #[derive(Clone, Debug)]
 struct Item {
     agent: Index,
+    /// This competitor's slot in the owning slice's `SkillStore`, resolved
+    /// once at ingestion.
+    ///
+    /// The convergence loop reaches skills through this rather than through
+    /// `agent`, which is what keeps `HashMap` hashing out of the hot path now
+    /// that the store is compact rather than indexed by the global `Index`.
+    slot: u32,
     likelihood: Gaussian,
 }
 
@@ -62,12 +69,13 @@ impl Item {
         agents: &CompetitorStore<T, D>,
     ) -> Rating<T, D> {
         let r = &agents[self.agent].rating;
-        let skill = skills.get(self.agent).unwrap();
+        let skill = skills.at(self.slot);
 
         if forward {
-            Rating::new(skill.forward, r.beta, r.drift)
+            Rating::new(skill.forward, r.beta, r.drift).with_drift_scale(r.drift_scale)
         } else {
             Rating::new(skill.posterior() / self.likelihood, r.beta, r.drift)
+                .with_drift_scale(r.drift_scale)
         }
     }
 }
@@ -157,9 +165,9 @@ impl Event {
         for (t, team) in self.teams.iter_mut().enumerate() {
             for (i, item) in team.items.iter_mut().enumerate() {
                 let fresh = update.likelihoods[t][i];
-                let old_likelihood = skills.get(item.agent).unwrap().likelihood;
+                let old_likelihood = skills.at(item.slot).likelihood;
                 let new_likelihood = (old_likelihood / item.likelihood) * fresh;
-                skills.get_mut(item.agent).unwrap().likelihood = new_likelihood;
+                skills.at_mut(item.slot).likelihood = new_likelihood;
                 item.likelihood = fresh;
             }
         }
@@ -277,8 +285,8 @@ impl<T: Time> TimeSlice<T> {
     pub fn add_events<D: Drift<T>>(
         &mut self,
         composition: Vec<Vec<Vec<Index>>>,
-        results: Vec<Vec<f64>>,
+        results: Option<Vec<Vec<f64>>>,
-        weights: Vec<Vec<Vec<f64>>>,
+        weights: Option<Vec<Vec<Vec<f64>>>>,
         kinds: Vec<EventKind>,
         agents: &CompetitorStore<T, D>,
     ) {
@@ -297,14 +305,16 @@ impl<T: Time> TimeSlice<T> {
         for idx in this_agent {
             let elapsed = compute_elapsed(agents[*idx].last_time.as_ref(), &self.time);
 
+            let forward = agents[*idx].receive(&self.time);
+
             if let Some(skill) = self.skills.get_mut(*idx) {
                 skill.elapsed = elapsed;
-                skill.forward = agents[*idx].receive(&self.time);
+                skill.forward = forward;
             } else {
                 self.skills.insert(
                     *idx,
                     Skill {
-                        forward: agents[*idx].receive(&self.time),
+                        forward,
                         backward: N_INF,
                         likelihood: N_INF,
                         elapsed,
@@ -313,6 +323,8 @@ impl<T: Time> TimeSlice<T> {
             }
         }
 
+        let skills = &self.skills;
+
         let events = composition.iter().enumerate().map(|(e, event)| {
             let teams = event
                 .iter()
@@ -322,28 +334,32 @@ impl<T: Time> TimeSlice<T> {
                         .iter()
                         .map(|&agent| Item {
                             agent,
+                            // Every participant was inserted into `skills`
+                            // just above, so the slot always resolves.
+                            slot: skills
+                                .slot_of(agent)
+                                .expect("participant must be present in the slice store"),
                             likelihood: N_INF,
                         })
                         .collect::<Vec<_>>();
 
                     Team {
                         items,
-                        output: if results.is_empty() {
+                        output: match &results {
-                            (event.len() - (t + 1)) as f64
+                            Some(results) => results[e][t],
-                        } else {
+                            // No explicit result: rank by position, first team best.
-                            results[e][t]
+                            None => (event.len() - (t + 1)) as f64,
                         },
                     }
                 })
                 .collect::<Vec<_>>();
 
-            let weights = if weights.is_empty() {
+            let weights = match &weights {
-                teams
+                Some(weights) => weights[e].clone(),
+                None => teams
                     .iter()
                     .map(|team| vec![1.0; team.items.len()])
-                    .collect::<Vec<_>>()
+                    .collect::<Vec<_>>(),
-            } else {
-                weights[e].clone()
             };
 
             Event {
@@ -370,6 +386,13 @@ impl<T: Time> TimeSlice<T> {
             .collect::<HashMap<_, _>>()
     }
 
+    /// Sweep this slice's events once, starting at index `from`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if an event references a competitor with no entry in this
+    /// slice's skill store. `add_events` inserts one for every participant, so
+    /// this cannot happen for slices built through the public API.
     pub fn iteration<D: Drift<T>>(&mut self, from: usize, agents: &CompetitorStore<T, D>) {
         if from == 0 && self.color_groups_dirty {
             self.recompute_color_groups();
@@ -402,10 +425,10 @@ impl<T: Time> TimeSlice<T> {
 
                 for (t, team) in event.teams.iter_mut().enumerate() {
                     for (i, item) in team.items.iter_mut().enumerate() {
-                        let old_likelihood = self.skills.get(item.agent).unwrap().likelihood;
+                        let old_likelihood = self.skills.at(item.slot).likelihood;
                         let new_likelihood =
                             (old_likelihood / item.likelihood) * g.likelihoods[t][i];
-                        self.skills.get_mut(item.agent).unwrap().likelihood = new_likelihood;
+                        self.skills.at_mut(item.slot).likelihood = new_likelihood;
                         item.likelihood = g.likelihoods[t][i];
                     }
                 }
@@ -567,14 +590,13 @@ impl<T: Time> TimeSlice<T> {
         n.forget(
             agents[*agent]
                 .rating
-                .drift
+                .drift_variance_for_elapsed(skill.elapsed),
-                .variance_for_elapsed(skill.elapsed),
         )
     }
 
     pub(crate) fn new_backward_info<D: Drift<T>>(&mut self, agents: &CompetitorStore<T, D>) {
         for (agent, skill) in self.skills.iter_mut() {
-            skill.backward = agents[agent].message;
+            skill.backward = agents[agent].message.unwrap_or(N_INF);
         }
         self.iteration(0, agents);
     }
@@ -623,11 +645,11 @@ impl<T: Time> TimeSlice<T> {
             let rating = &agents[agent].rating;
 
             let forward = match incoming.get(&agent) {
-                Some(message) => message.forget(rating.drift.variance_for_elapsed(skill.elapsed)),
+                Some(message) => message.forget(rating.drift_variance_for_elapsed(skill.elapsed)),
                 None => rating.prior,
             };
 
-            scratch.skills.insert(
+            let slot = scratch.skills.insert(
                 agent,
                 Skill {
                     forward,
@@ -636,6 +658,17 @@ impl<T: Time> TimeSlice<T> {
                     elapsed: skill.elapsed,
                 },
             );
+
+            // The cloned events carry slots resolved against the REAL store, so
+            // the scratch must assign the same ones. It does because `iter()`
+            // yields slot order and `insert` allocates slots in call order —
+            // but that is a coupling between two types, so pin it here rather
+            // than leave it to be rediscovered after it breaks.
+            debug_assert_eq!(
+                Some(slot),
+                self.skills.slot_of(agent),
+                "scratch slot must match the real slice's slot for {agent:?}"
+            );
         }
 
         scratch.iterate_to_convergence(agents);
@@ -754,8 +787,26 @@ impl<T: Time> TimeSlice<T> {
     }
 }
 
+/// Elapsed time from a competitor's previous appearance to `current`.
+///
+/// A negative elapsed means slices are being visited out of time order, which
+/// would make drift *reduce* uncertainty. Release builds clamp to zero so a
+/// bad timestamp degrades to "no drift" rather than corrupting the posterior;
+/// debug builds trip instead, because reaching here is a bug in slice ordering
+/// rather than something callers can cause with ordinary data.
 pub(crate) fn compute_elapsed<T: Time>(last: Option<&T>, current: &T) -> i64 {
-    last.map(|l| l.elapsed_to(current).max(0)).unwrap_or(0)
+    let Some(last) = last else {
+        return 0;
+    };
+
+    let elapsed = last.elapsed_to(current);
+
+    debug_assert!(
+        elapsed >= 0,
+        "negative elapsed ({elapsed}) — slices visited out of time order"
+    );
+
+    elapsed.max(0)
 }
 
 #[cfg(test)]
@@ -803,8 +854,8 @@ mod tests {
                 vec![vec![c], vec![d]],
                 vec![vec![e], vec![f]],
             ],
-            vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]]),
-            vec![],
+            None,
             vec![EventKind::Ranked; 3],
             &agents,
         );
@@ -880,8 +931,8 @@ mod tests {
                 vec![vec![a], vec![c]],
                 vec![vec![b], vec![c]],
             ],
-            vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]]),
-            vec![],
+            None,
             vec![EventKind::Ranked; 3],
             &agents,
         );
@@ -960,8 +1011,8 @@ mod tests {
                 vec![vec![a], vec![c]],
                 vec![vec![b], vec![c]],
             ],
-            vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]]),
-            vec![],
+            None,
             vec![EventKind::Ranked; 3],
             &agents,
         );
@@ -992,8 +1043,8 @@ mod tests {
                 vec![vec![a], vec![c]],
                 vec![vec![b], vec![c]],
             ],
-            vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]]),
-            vec![],
+            None,
             vec![EventKind::Ranked; 3],
             &agents,
         );
@@ -1063,8 +1114,8 @@ mod tests {
                 vec![vec![c], vec![d]],
                 vec![vec![a], vec![c]],
             ],
-            vec![vec![1.0, 0.0], vec![1.0, 0.0], vec![1.0, 0.0]],
+            Some(vec![vec![1.0, 0.0], vec![1.0, 0.0], vec![1.0, 0.0]]),
-            vec![],
+            None,
             vec![EventKind::Ranked; 3],
             &agents,
         );

tests/api_shape.rs

@@ -203,7 +203,7 @@ fn predict_quality_two_teams() {
     h.record_winner(&"a", &"b", 1).unwrap();
     h.converge().unwrap();
 
-    let q = h.predict_quality(&[&[&"a"], &[&"b"]]);
+    let q = h.predict_quality(&[&[&"a"], &[&"b"]]).unwrap();
     assert!(q > 0.0 && q <= 1.0);
 }
 
@@ -219,10 +219,14 @@ fn predict_outcome_two_teams_sums_to_one() {
     h.record_winner(&"a", &"b", 1).unwrap();
     h.converge().unwrap();
 
-    let p = h.predict_outcome(&[&[&"a"], &[&"b"]]);
+    let p = h.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap();
-    assert_eq!(p.len(), 2);
+    let wins = p.win_probabilities();
-    assert!((p[0] + p[1] - 1.0).abs() < 1e-9);
+    assert_eq!(wins.len(), 2);
-    assert!(p[0] > p[1]);
+    // With p_draw == 0 there is no draw outcome, so the two win
+    // probabilities are the whole space.
+    assert!((p.total() - 1.0).abs() < 1e-9, "total = {}", p.total());
+    assert!((wins[0] + wins[1] - 1.0).abs() < 1e-9);
+    assert!(wins[0] > wins[1]);
 }
 
 #[test]
@@ -247,3 +251,46 @@ fn fluent_event_builder_scores() {
     let b = h.current_skill(&"bob").unwrap();
     assert!(a.mu() > b.mu());
 }
+
+/// Every field of `ConvergenceReport` must carry real information.
+///
+/// `slices_skipped` was public, hardcoded to `0`, and reported a plausible
+/// value for a feature that never existed — the same shape as the inert
+/// `online` flag in #19. It was removed in #33. This pins the remaining fields
+/// so the next always-constant member has to survive an assertion rather than
+/// just a reviewer's attention.
+#[test]
+fn every_convergence_report_field_is_populated() {
+    let mut h = History::builder().build();
+
+    for time in 1..=6i64 {
+        h.record_winner(&"a", &"b", time).unwrap();
+    }
+
+    let report = h.converge().unwrap();
+
+    assert!(
+        report.iterations > 0,
+        "iterations is zero on a real converge"
+    );
+
+    assert!(report.converged, "fixture must converge");
+
+    assert!(
+        report.final_step.0.is_finite() && report.final_step.1.is_finite(),
+        "final_step is not finite: {:?}",
+        report.final_step
+    );
+
+    assert!(
+        report.log_evidence.is_finite() && report.log_evidence < 0.0,
+        "log_evidence is not a finite negative log probability: {}",
+        report.log_evidence
+    );
+
+    assert_eq!(
+        report.per_iteration_time.len(),
+        report.iterations,
+        "per_iteration_time must carry one duration per iteration"
+    );
+}

tests/common/mod.rs

@@ -0,0 +1,38 @@
+//! Helpers shared across the integration suites.
+//!
+//! Each integration file is its own binary, so `mod common;` compiles a copy
+//! per suite. Anything unused in a given suite would warn, hence the
+//! `#![allow(dead_code)]`.
+
+#![allow(dead_code)]
+
+use trueskill_tt::Gaussian;
+
+/// A posterior must be finite with a strictly positive sigma.
+///
+/// A non-finite posterior is the failure mode this crate is most prone to —
+/// EP breaking down produces NaN rather than an error — and a zero or negative
+/// sigma means the precision went non-positive, which `Gaussian::sigma` reports
+/// as improper rather than trapping.
+pub fn assert_finite(g: Gaussian, what: &str) {
+    assert!(
+        g.mu().is_finite(),
+        "{what}: mu is not finite (mu={}, sigma={})",
+        g.mu(),
+        g.sigma()
+    );
+
+    assert!(
+        g.sigma().is_finite() && g.sigma() > 0.0,
+        "{what}: sigma must be finite and positive (mu={}, sigma={})",
+        g.mu(),
+        g.sigma()
+    );
+}
+
+/// Every point on every learning curve must be finite.
+pub fn assert_curve_finite(curve: &[(i64, Gaussian)], who: &str) {
+    for (time, g) in curve {
+        assert_finite(*g, &format!("{who} at t={time}"));
+    }
+}

tests/degenerate_inputs.rs

@@ -3,6 +3,9 @@
 //! These run in both debug and release: the defects they pin were all
 //! guarded only by `debug_assert!`, so a debug-only suite never saw them.
 
+mod common;
+
+use common::assert_finite;
 use trueskill_tt::{
     ConstantDrift, ConvergenceOptions, Game, GameOptions, Gaussian, History, InferenceError,
     NullObserver, Outcome, Rating,
@@ -18,15 +21,6 @@ fn rating() -> R {
     )
 }
 
-fn assert_finite(g: Gaussian, what: &str) {
-    assert!(
-        g.mu().is_finite() && g.sigma().is_finite(),
-        "{what} must be finite, got mu={} sigma={}",
-        g.mu(),
-        g.sigma()
-    );
-}
-
 #[test]
 fn record_draw_without_draw_probability_is_rejected() {
     let mut h = History::default();
@@ -141,6 +135,54 @@ fn converge_on_an_empty_history_with_owned_keys() {
     assert!(report.converged);
 }
 
+/// A weights/team length mismatch used to be a `debug_assert!`, so release
+/// builds ingested the event with the weights silently unapplied. This file's
+/// CI job runs in release too, which is the point of pinning it here.
+#[test]
+fn event_builder_rejects_a_weights_length_mismatch() {
+    let mut h = History::default();
+
+    let err = h
+        .event(1)
+        .team(["a"])
+        .weights([1.0, 2.0])
+        .team(["b"])
+        .winner(0)
+        .commit()
+        .unwrap_err();
+
+    assert!(
+        matches!(
+            err,
+            InferenceError::MismatchedShape {
+                kind: "weights",
+                expected: 1,
+                got: 2,
+            }
+        ),
+        "expected a weights MismatchedShape, got {err:?}"
+    );
+}
+
+/// The mismatch must not be applied even partially — a half-weighted team
+/// reaching the history would be worse than the error.
+#[test]
+fn event_builder_weights_mismatch_leaves_the_history_untouched() {
+    let mut h = History::default();
+
+    // Two teams, so ingestion would otherwise succeed — a one-team event is
+    // rejected for an unrelated reason and would pass this vacuously.
+    let _ = h
+        .event(1)
+        .team(["a"])
+        .weights([1.0, 2.0])
+        .team(["b"])
+        .winner(0)
+        .commit();
+
+    assert!(h.learning_curve("a").is_empty());
+}
+
 #[test]
 fn empty_event_stream_then_converge() {
     let mut h = History::default();
@@ -270,3 +312,112 @@ fn empty_history_has_no_filtered_estimates() {
 
     assert!(history.filtered_learning_curve("nobody").is_empty());
 }
+
+// --- Boundary inputs (#26) ----------------------------------------------
+
+fn tight() -> ConvergenceOptions {
+    ConvergenceOptions {
+        max_iter: 2_000,
+        epsilon: 1e-12,
+        ..ConvergenceOptions::default()
+    }
+}
+
+fn assert_curve_finite(h: &History, keys: &[&str], what: &str) {
+    for key in keys {
+        for (time, g) in h.learning_curve(*key) {
+            assert!(
+                g.mu().is_finite() && g.sigma().is_finite(),
+                "{what}: non-finite posterior for {key} at t={time} (mu={} sigma={})",
+                g.mu(),
+                g.sigma()
+            );
+        }
+    }
+}
+
+/// A zero weight reaches `(m - performance.exclude(..)) * (1.0 / w)`, i.e. a
+/// division by zero. The commit is accepted today, so this pins that the
+/// resulting posterior is still finite rather than quietly NaN.
+#[test]
+fn zero_weight_does_not_produce_a_non_finite_posterior() {
+    let mut h = History::builder().build();
+
+    h.event(1)
+        .team(["a"])
+        .weights([0.0])
+        .team(["b"])
+        .winner(0)
+        .commit()
+        .expect("a zero weight is accepted today; update this test if that changes");
+
+    h.converge().unwrap();
+
+    assert_curve_finite(&h, &["a", "b"], "zero weight");
+}
+
+#[test]
+fn negative_weight_does_not_produce_a_non_finite_posterior() {
+    let mut h = History::builder().build();
+
+    h.event(1)
+        .team(["a"])
+        .weights([-1.0])
+        .team(["b"])
+        .winner(0)
+        .commit()
+        .expect("a negative weight is accepted today; update this test if that changes");
+
+    h.converge().unwrap();
+
+    assert_curve_finite(&h, &["a", "b"], "negative weight");
+}
+
+/// Events supplied newest-first must land in the same slices as oldest-first:
+/// ingestion sorts by time rather than trusting arrival order.
+#[test]
+fn out_of_order_timestamps_converge_to_the_same_answer() {
+    fn build(descending: bool) -> History {
+        let mut h = History::builder().convergence(tight()).build();
+
+        let mut times: Vec<i64> = (1..=6).collect();
+        if descending {
+            times.reverse();
+        }
+
+        for time in times {
+            h.record_winner(&"a", &"b", time).unwrap();
+        }
+
+        h.converge().unwrap();
+        h
+    }
+
+    let ascending = build(false);
+    let descending = build(true);
+
+    let one = ascending.current_skill("a").unwrap();
+    let other = descending.current_skill("a").unwrap();
+
+    assert!(
+        (one.mu() - other.mu()).abs() < 1e-8 && (one.sigma() - other.sigma()).abs() < 1e-8,
+        "arrival order changed the answer: ascending mu={} sigma={}, descending mu={} sigma={}",
+        one.mu(),
+        one.sigma(),
+        other.mu(),
+        other.sigma()
+    );
+}
+
+#[test]
+fn extreme_beta_and_sigma_stay_finite() {
+    for (beta, sigma) in [(1e-6, 1e-6), (1e6, 1e6), (1e-6, 1e6), (1e6, 1e-6)] {
+        let mut h = History::builder().beta(beta).sigma(sigma).build();
+
+        h.record_winner(&"a", &"b", 1).unwrap();
+        h.record_winner(&"a", &"b", 2).unwrap();
+        h.converge().unwrap();
+
+        assert_curve_finite(&h, &["a", "b"], &format!("beta={beta} sigma={sigma}"));
+    }
+}

tests/drift_scale.rs

@@ -0,0 +1,402 @@
+//! Per-competitor drift scaling via `Member::with_drift_scale`.
+//!
+//! The scale multiplies the *variance* the history's `Drift` contributes for
+//! that competitor, so `scale` is in the same units as `gamma`:
+//! `ConstantDrift(g)` at `scale = s` behaves as `ConstantDrift(g * s)` would.
+//! `scale = 0.0` pins a competitor still — an anchor, a rating floor, a course
+//! difficulty — while everyone around them keeps drifting.
+
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, Gaussian, History, InferenceError, Member,
+    NullObserver, Outcome, Team,
+};
+
+type Fit = History<i64, ConstantDrift, NullObserver, &'static str>;
+
+const CONVERGENCE: ConvergenceOptions = ConvergenceOptions {
+    max_iter: 64,
+    epsilon: 1e-9,
+    alpha: 1.0,
+};
+
+/// Two events separated by a long gap, so drift has room to matter.
+fn distant_pair(anchor_scale: Option<f64>) -> Vec<Event<i64, &'static str>> {
+    let anchor = |s: Option<f64>| match s {
+        Some(scale) => Member::new("anchor").with_drift_scale(scale),
+        None => Member::new("anchor"),
+    };
+
+    vec![
+        Event {
+            time: 0,
+            teams: smallvec![
+                Team::with_members([anchor(anchor_scale)]),
+                Team::with_members([Member::new("player")]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+        Event {
+            time: 1000,
+            teams: smallvec![
+                Team::with_members([anchor(anchor_scale)]),
+                Team::with_members([Member::new("player")]),
+            ],
+            outcome: Outcome::winner(1, 2),
+        },
+    ]
+}
+
+fn fit(events: Vec<Event<i64, &'static str>>, gamma: f64) -> Fit {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .drift(ConstantDrift(gamma))
+        .convergence(CONVERGENCE)
+        .build();
+
+    h.add_events(events).unwrap();
+    h.converge().unwrap();
+    h
+}
+
+fn curve(h: &Fit, key: &str) -> Vec<(i64, Gaussian)> {
+    let mut c = h.learning_curves().remove(key).expect("key in curves");
+    c.sort_by_key(|(t, _)| *t);
+    c
+}
+
+/// A competitor at `scale = 0.0` is one latent skill observed twice, so the
+/// posterior is the same distribution at both times — and strictly tighter
+/// than the same competitor left to drift.
+#[test]
+fn zero_scale_pins_a_competitor_still() {
+    let pinned = fit(distant_pair(Some(0.0)), 25.0 / 300.0);
+    let drifting = fit(distant_pair(None), 25.0 / 300.0);
+
+    let pinned_curve = curve(&pinned, "anchor");
+    assert_eq!(pinned_curve.len(), 2);
+
+    let (t0, first) = pinned_curve[0];
+    let (t1, second) = pinned_curve[1];
+    assert_eq!((t0, t1), (0, 1000));
+
+    assert!(
+        (first.sigma() - second.sigma()).abs() < 1e-9,
+        "a pinned competitor's uncertainty must not move between t=0 and t=1000: \
+         {} vs {}",
+        first.sigma(),
+        second.sigma()
+    );
+    assert!(
+        (first.mu() - second.mu()).abs() < 1e-9,
+        "a pinned competitor's mean must not move: {} vs {}",
+        first.mu(),
+        second.mu()
+    );
+
+    let drifting_curve = curve(&drifting, "anchor");
+    assert!(
+        drifting_curve[0].1.sigma() > first.sigma() + 1e-6,
+        "drift must leave the anchor less certain than pinning does: {} vs {}",
+        drifting_curve[0].1.sigma(),
+        first.sigma()
+    );
+}
+
+/// The scale is composable with `gamma`: scaling every competitor by `s` is
+/// exactly the same fit as scaling the history's drift by `s`.
+#[test]
+fn scale_is_equivalent_to_scaling_gamma() {
+    let scaled: Vec<Event<i64, &'static str>> = vec![
+        Event {
+            time: 0,
+            teams: smallvec![
+                Team::with_members([Member::new("a").with_drift_scale(0.5)]),
+                Team::with_members([Member::new("b").with_drift_scale(0.5)]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+        Event {
+            time: 400,
+            teams: smallvec![
+                Team::with_members([Member::new("b").with_drift_scale(0.5)]),
+                Team::with_members([Member::new("a").with_drift_scale(0.5)]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+    ];
+
+    let plain: Vec<Event<i64, &'static str>> = vec![
+        Event {
+            time: 0,
+            teams: smallvec![
+                Team::with_members([Member::new("a")]),
+                Team::with_members([Member::new("b")]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+        Event {
+            time: 400,
+            teams: smallvec![
+                Team::with_members([Member::new("b")]),
+                Team::with_members([Member::new("a")]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+    ];
+
+    let by_scale = fit(scaled, 0.3);
+    let by_gamma = fit(plain, 0.15);
+
+    for key in ["a", "b"] {
+        let lhs = curve(&by_scale, key);
+        let rhs = curve(&by_gamma, key);
+        assert_eq!(lhs.len(), rhs.len());
+
+        for ((t_l, g_l), (t_r, g_r)) in lhs.iter().zip(rhs.iter()) {
+            assert_eq!(t_l, t_r);
+            assert!(
+                (g_l.mu() - g_r.mu()).abs() < 1e-9 && (g_l.sigma() - g_r.sigma()).abs() < 1e-9,
+                "ConstantDrift(0.3) at scale 0.5 must equal ConstantDrift(0.15) for {key} at \
+                 t={t_l}: ({}, {}) vs ({}, {})",
+                g_l.mu(),
+                g_l.sigma(),
+                g_r.mu(),
+                g_r.sigma()
+            );
+        }
+    }
+}
+
+/// `None` means 1.0: an explicit unit scale changes nothing.
+#[test]
+fn unset_scale_matches_an_explicit_unit_scale() {
+    let implicit = fit(distant_pair(None), 25.0 / 300.0);
+    let explicit = fit(distant_pair(Some(1.0)), 25.0 / 300.0);
+
+    for key in ["anchor", "player"] {
+        let lhs = curve(&implicit, key);
+        let rhs = curve(&explicit, key);
+        assert_eq!(lhs.len(), rhs.len());
+
+        for ((t_l, g_l), (t_r, g_r)) in lhs.iter().zip(rhs.iter()) {
+            assert_eq!(t_l, t_r);
+            assert_eq!(
+                (g_l.mu(), g_l.sigma()),
+                (g_r.mu(), g_r.sigma()),
+                "an explicit scale of 1.0 must be bit-identical to leaving it unset, \
+                 for {key} at t={t_l}"
+            );
+        }
+    }
+}
+
+/// The use case from the issue: a static difficulty alongside drifting players,
+/// in one graph. The anchor must hold still without absorbing drift through its
+/// neighbours, and everything must stay finite.
+#[test]
+fn mixed_static_and_drifting_graph_converges() {
+    let mut events: Vec<Event<i64, &'static str>> = Vec::new();
+    let players = ["p0", "p1", "p2"];
+
+    for (i, p) in players.iter().cycle().take(9).enumerate() {
+        events.push(Event {
+            time: (i as i64) * 100,
+            teams: smallvec![
+                Team::with_members([Member::new(*p)]),
+                Team::with_members([Member::new("layout").with_drift_scale(0.0)]),
+            ],
+            outcome: Outcome::winner((i % 2) as u32, 2),
+        });
+    }
+
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .convergence(CONVERGENCE)
+        .build();
+
+    h.add_events(events).unwrap();
+    let report = h.converge().unwrap();
+    assert!(report.converged, "mixed graph must converge: {report:?}");
+
+    let curves = h.learning_curves();
+    for (key, points) in &curves {
+        for (t, g) in points {
+            assert!(
+                g.mu().is_finite() && g.sigma().is_finite() && g.sigma() > 0.0,
+                "{key} at t={t} is not a usable posterior: mu={}, sigma={}",
+                g.mu(),
+                g.sigma()
+            );
+        }
+    }
+
+    let layout = curve(&h, "layout");
+    assert_eq!(layout.len(), 9);
+    let (_, first) = layout[0];
+    for (t, g) in &layout {
+        assert!(
+            (g.sigma() - first.sigma()).abs() < 1e-9,
+            "a static layout must not accumulate uncertainty; t={t} has sigma {} vs {}",
+            g.sigma(),
+            first.sigma()
+        );
+    }
+
+    let p0 = curve(&h, "p0");
+    assert!(
+        p0.last().unwrap().1.sigma() > 0.0,
+        "a drifting player should still have a proper posterior"
+    );
+}
+
+fn reject(scale: f64) -> InferenceError {
+    let mut h = History::builder()
+        .drift(ConstantDrift(25.0 / 300.0))
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 0,
+        teams: smallvec![
+            Team::with_members([Member::new("a").with_drift_scale(scale)]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::winner(0, 2),
+    }];
+
+    h.add_events(events)
+        .expect_err("an out-of-range drift_scale must be rejected")
+}
+
+#[test]
+fn negative_scale_is_rejected() {
+    assert_eq!(
+        reject(-1.0),
+        InferenceError::InvalidParameter {
+            name: "drift_scale",
+            value: -1.0
+        }
+    );
+}
+
+#[test]
+fn non_finite_scale_is_rejected() {
+    for scale in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+        assert!(
+            matches!(
+                reject(scale),
+                InferenceError::InvalidParameter {
+                    name: "drift_scale",
+                    ..
+                }
+            ),
+            "a drift_scale of {scale} must be rejected as an invalid parameter"
+        );
+    }
+}
+
+/// The scale must reach the filtering pass too, not just `converge()`.
+/// `filtered_learning_curves` runs its own drift application, so a pinned
+/// competitor has to stay pinned there as well.
+#[test]
+fn zero_scale_pins_a_competitor_in_the_filtered_pass() {
+    let pinned = fit(distant_pair(Some(0.0)), 25.0 / 300.0);
+    let drifting = fit(distant_pair(None), 25.0 / 300.0);
+
+    let filtered = |h: &Fit| -> Vec<(i64, Gaussian)> {
+        let mut c = h
+            .filtered_learning_curves()
+            .remove("anchor")
+            .expect("anchor in filtered curves");
+        c.sort_by_key(|(t, _)| *t);
+        c
+    };
+
+    let pinned_curve = filtered(&pinned);
+    let drifting_curve = filtered(&drifting);
+    assert_eq!(pinned_curve.len(), 2);
+    assert_eq!(drifting_curve.len(), 2);
+
+    assert!(
+        pinned_curve[1].1.sigma() < pinned_curve[0].1.sigma(),
+        "a pinned competitor's filtered uncertainty must shrink with a second \
+         observation, not be re-inflated by drift: {} then {}",
+        pinned_curve[0].1.sigma(),
+        pinned_curve[1].1.sigma()
+    );
+
+    assert!(
+        pinned_curve[1].1.sigma() < drifting_curve[1].1.sigma() - 1e-6,
+        "pinning must leave the filtered estimate tighter than drifting does: \
+         {} vs {}",
+        pinned_curve[1].1.sigma(),
+        drifting_curve[1].1.sigma()
+    );
+}
+
+/// `drift_scale` is competitor configuration captured at first appearance, the
+/// same as `prior` — a later `with_drift_scale` on a key the history already
+/// knows is ignored. This guards that decision rather than driving it: the
+/// behaviour falls out of where the capture happens, and the point of the test
+/// is that moving the capture would be a visible break, not a silent one.
+#[test]
+fn drift_scale_is_ignored_after_first_appearance() {
+    let mut late = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .convergence(CONVERGENCE)
+        .build();
+
+    // First batch creates "anchor" with the default scale.
+    late.add_events(vec![Event {
+        time: 0,
+        teams: smallvec![
+            Team::with_members([Member::new("anchor")]),
+            Team::with_members([Member::new("player")]),
+        ],
+        outcome: Outcome::winner(0, 2),
+    }])
+    .unwrap();
+
+    // Second batch asks for a pin. Too late: the competitor already exists.
+    late.add_events(vec![Event {
+        time: 1000,
+        teams: smallvec![
+            Team::with_members([Member::new("anchor").with_drift_scale(0.0)]),
+            Team::with_members([Member::new("player")]),
+        ],
+        outcome: Outcome::winner(1, 2),
+    }])
+    .unwrap();
+    late.converge().unwrap();
+
+    let ignored = curve(&late, "anchor");
+    let drifting = curve(&fit(distant_pair(None), 25.0 / 300.0), "anchor");
+
+    for ((t_l, g_l), (t_r, g_r)) in ignored.iter().zip(drifting.iter()) {
+        assert_eq!(t_l, t_r);
+        assert!(
+            (g_l.sigma() - g_r.sigma()).abs() < 1e-9,
+            "a scale set after first appearance must be ignored, leaving the fit \
+             identical to one that never set it: t={t_l}, {} vs {}",
+            g_l.sigma(),
+            g_r.sigma()
+        );
+    }
+
+    let pinned = curve(&fit(distant_pair(Some(0.0)), 25.0 / 300.0), "anchor");
+    assert!(
+        (ignored[1].1.sigma() - pinned[1].1.sigma()).abs() > 1e-6,
+        "sanity: the pinned fit must actually differ, or the assertion above is vacuous"
+    );
+}

tests/equivalence.rs

@@ -19,7 +19,8 @@ fn ts_rating(mu: f64, sigma: f64, beta: f64, gamma: f64) -> R {
 fn game_1v1_golden_matches_historical() {
     let a = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
     let b = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
-    let (a_post, b_post) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2)).unwrap();
+    let (a_post, b_post) =
+        Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2), &GameOptions::default()).unwrap();
     // Historical golden from pre-T2 test_1vs1 (team 0 wins):
     assert_ulps_eq!(
         a_post,

tests/game.rs

@@ -32,7 +32,8 @@ fn game_ranked_1v1_golden() {
 fn game_one_v_one_shortcut() {
     let a = default_rating();
     let b = default_rating();
-    let (a_post, b_post) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2)).unwrap();
+    let (a_post, b_post) =
+        Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2), &GameOptions::default()).unwrap();
     assert!(a_post.mu() > 25.0);
     assert!(b_post.mu() < 25.0);
 }
@@ -95,3 +96,45 @@ fn game_log_evidence_is_finite() {
     assert!(g.log_evidence().is_finite());
     assert!(g.log_evidence() < 0.0);
 }
+
+/// `one_v_one` used to hardcode `GameOptions::default()`, so a 1v1 could
+/// never set `p_draw` and a drawn 1v1 was unreachable through it.
+#[test]
+fn one_v_one_honours_the_draw_probability_it_is_given() {
+    let a = default_rating();
+    let b = default_rating();
+
+    // Default options still reject a draw, because the default p_draw is zero.
+    let err = Game::<i64, _>::one_v_one(&a, &b, Outcome::draw(2), &GameOptions::default())
+        .expect_err("a draw needs a positive p_draw");
+    assert!(matches!(
+        err,
+        InferenceError::TieWithoutDrawProbability { .. }
+    ));
+
+    // With a draw probability supplied it succeeds — which was impossible
+    // before the signature took options.
+    let options = GameOptions {
+        p_draw: 0.25,
+        ..GameOptions::default()
+    };
+    let (a_post, b_post) = Game::<i64, _>::one_v_one(&a, &b, Outcome::draw(2), &options)
+        .expect("a draw is representable once p_draw is positive");
+
+    // A symmetric draw leaves the means alone and sharpens both sides.
+    assert!((a_post.mu() - b_post.mu()).abs() < 1e-9);
+    assert!(a_post.sigma() < 25.0 / 3.0);
+}
+
+/// Convergence options reach the 1v1 path too, not just `p_draw`.
+#[test]
+fn one_v_one_honours_convergence_options() {
+    let a = default_rating();
+    let b = default_rating();
+    let options = GameOptions {
+        convergence: ConvergenceOptions::default(),
+        ..GameOptions::default()
+    };
+    let (a_post, _) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2), &options).unwrap();
+    assert!(a_post.mu() > 25.0);
+}

tests/observer.rs

@@ -0,0 +1,105 @@
+//! `Observer` callbacks must actually fire.
+//!
+//! `on_slice_processed` (formerly `on_batch_processed`) was declared on the
+//! trait and never called from anywhere, so implementors wired up a callback
+//! that could not run. These tests exist so that cannot silently recur.
+
+use std::sync::{Arc, Mutex};
+
+use trueskill_tt::{History, Observer};
+
+/// `History` takes its observer by value and never hands it back, so a test
+/// that wants to read what was recorded shares the storage rather than the
+/// observer: the handles are cloned, the buffers are not.
+#[derive(Clone, Default)]
+struct Recorder {
+    iterations: Arc<Mutex<Vec<usize>>>,
+    slices: Arc<Mutex<Vec<(i64, usize, usize)>>>,
+    converged: Arc<Mutex<Vec<(usize, bool)>>>,
+}
+
+impl Observer<i64> for Recorder {
+    fn on_iteration_end(&self, iter: usize, _max_step: (f64, f64)) {
+        self.iterations.lock().unwrap().push(iter);
+    }
+
+    fn on_slice_processed(&self, time: &i64, slice_idx: usize, n_events: usize) {
+        self.slices
+            .lock()
+            .unwrap()
+            .push((*time, slice_idx, n_events));
+    }
+
+    fn on_converged(&self, iters: usize, _final_step: (f64, f64), converged: bool) {
+        self.converged.lock().unwrap().push((iters, converged));
+    }
+}
+
+#[test]
+fn every_observer_callback_fires() {
+    let recorder = Recorder::default();
+    let mut h = History::builder().observer(recorder.clone()).build();
+
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.record_winner(&"b", &"c", 2).unwrap();
+    h.record_winner(&"c", &"a", 3).unwrap();
+    h.converge().unwrap();
+
+    assert!(
+        !recorder.iterations.lock().unwrap().is_empty(),
+        "on_iteration_end never fired"
+    );
+    assert!(
+        !recorder.converged.lock().unwrap().is_empty(),
+        "on_converged never fired"
+    );
+    assert!(
+        !recorder.slices.lock().unwrap().is_empty(),
+        "on_slice_processed never fired — the defect this test exists for"
+    );
+}
+
+#[test]
+fn slice_callbacks_report_the_slice_they_swept() {
+    let recorder = Recorder::default();
+    let mut h = History::builder().observer(recorder.clone()).build();
+
+    h.record_winner(&"a", &"b", 10).unwrap();
+    h.record_winner(&"a", &"b", 20).unwrap();
+    h.converge().unwrap();
+
+    let slices = recorder.slices.lock().unwrap();
+
+    // Only the times actually in the history, and each with its own events.
+    for &(time, idx, events) in slices.iter() {
+        assert!(time == 10 || time == 20, "unexpected slice time {time}");
+        assert!(idx < 2, "slice index {idx} out of range");
+        assert_eq!(events, 1, "each slice holds exactly one event");
+    }
+
+    // Both slices must be reported, not just one end of the sweep.
+    assert!(
+        slices.iter().any(|&(t, ..)| t == 10),
+        "slice 10 never reported"
+    );
+    assert!(
+        slices.iter().any(|&(t, ..)| t == 20),
+        "slice 20 never reported"
+    );
+}
+
+#[test]
+fn a_single_slice_history_still_reports_its_sweep() {
+    let recorder = Recorder::default();
+    let mut h = History::builder().observer(recorder.clone()).build();
+
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.converge().unwrap();
+
+    let slices = recorder.slices.lock().unwrap();
+    assert!(
+        !slices.is_empty(),
+        "the single-slice path must report its sweep too"
+    );
+    assert!(slices.iter().all(|&(t, idx, _)| t == 1 && idx == 0));
+}

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);
+}

tests/properties.rs

@@ -0,0 +1,167 @@
+//! Property-based tests over generated histories.
+//!
+//! The golden suite pins exact values against the Python/Julia reference on a
+//! handful of fixtures. These pin *invariants* over inputs nobody wrote by
+//! hand, which is where the defects this crate has actually shipped were
+//! hiding: a linear evidence product that underflowed only past ~1000 teams,
+//! and a batching path no golden exercised because every golden ingests in one
+//! call.
+
+mod common;
+
+use common::assert_finite;
+use proptest::prelude::*;
+use smallvec::smallvec;
+use trueskill_tt::{ConvergenceOptions, Event, History, Member, Outcome, Team};
+
+/// Distinct competitors, so no event pits someone against themselves.
+fn pairs() -> impl Strategy<Value = Vec<(usize, usize)>> {
+    prop::collection::vec((0usize..8, 0usize..8), 1..24)
+        .prop_map(|v| v.into_iter().filter(|(a, b)| a != b).collect::<Vec<_>>())
+        .prop_filter("needs at least one valid pair", |v| !v.is_empty())
+}
+
+const KEYS: [&str; 8] = ["a", "b", "c", "d", "e", "f", "g", "h"];
+
+fn history_from(games: &[(usize, usize)]) -> History {
+    let mut h = History::builder()
+        .convergence(ConvergenceOptions {
+            max_iter: 200,
+            epsilon: 1e-10,
+            ..ConvergenceOptions::default()
+        })
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = games
+        .iter()
+        .enumerate()
+        .map(|(i, &(a, b))| Event {
+            time: i as i64 + 1,
+            teams: smallvec![
+                Team::with_members([Member::new(KEYS[a])]),
+                Team::with_members([Member::new(KEYS[b])]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        })
+        .collect();
+
+    h.add_events(events).unwrap();
+
+    h
+}
+
+proptest! {
+    #![proptest_config(ProptestConfig::with_cases(48))]
+
+    /// Whatever the schedule of games, convergence must not produce NaN or an
+    /// improper posterior. `converge` returns `NonFiniteResult` rather than
+    /// silently reporting a NaN step as converged, so a break shows up here as
+    /// either an Err or a non-finite curve point.
+    #[test]
+    fn converged_posteriors_are_always_finite(games in pairs()) {
+        let mut h = history_from(&games);
+
+        h.converge().unwrap();
+
+        for key in KEYS {
+            for (time, g) in h.learning_curve(key) {
+                assert_finite(g, &format!("{key} at t={time}"));
+            }
+        }
+    }
+
+    /// Log-evidence is a log probability: finite, and never above zero.
+    ///
+    /// The linear-product implementation this replaced underflowed to zero on
+    /// long chains, making `ln(0)` = -inf — finite-ness is the property that
+    /// would have caught it.
+    #[test]
+    fn log_evidence_is_a_finite_log_probability(games in pairs()) {
+        let mut h = history_from(&games);
+
+        h.converge().unwrap();
+
+        let batch = h.log_evidence();
+        let filtered = h.filtered_log_evidence();
+
+        prop_assert!(batch.is_finite(), "batch log-evidence {batch} is not finite");
+        prop_assert!(batch <= 0.0, "batch log-evidence {batch} exceeds zero");
+        prop_assert!(filtered.is_finite(), "filtered log-evidence {filtered} is not finite");
+        prop_assert!(filtered <= 0.0, "filtered log-evidence {filtered} exceeds zero");
+    }
+
+    /// Filtered estimates must not depend on whether `converge` has run — the
+    /// property the whole forward-only design rests on.
+    #[test]
+    fn filtered_evidence_is_invariant_to_convergence(games in pairs()) {
+        let mut h = history_from(&games);
+
+        let before = h.filtered_log_evidence();
+
+        h.converge().unwrap();
+
+        let after = h.filtered_log_evidence();
+
+        prop_assert!(
+            (before - after).abs() < 1e-8,
+            "filtered evidence moved across converge(): {before} -> {after}"
+        );
+    }
+
+    /// Ingesting the same games one at a time must reach the same fixed point
+    /// as ingesting them in one call.
+    #[test]
+    fn ingestion_order_does_not_change_the_answer(games in pairs()) {
+        let batched = {
+            let mut h = history_from(&games);
+            h.converge().unwrap();
+            h
+        };
+
+        let incremental = {
+            let mut h = History::builder()
+                .convergence(ConvergenceOptions {
+                    max_iter: 200,
+                    epsilon: 1e-10,
+                    ..ConvergenceOptions::default()
+                })
+                .build();
+
+            for (i, &(a, b)) in games.iter().enumerate() {
+                h.add_events([Event {
+                    time: i as i64 + 1,
+                    teams: smallvec![
+                        Team::with_members([Member::new(KEYS[a])]),
+                        Team::with_members([Member::new(KEYS[b])]),
+                    ],
+                    outcome: Outcome::winner(0, 2),
+                }])
+                .unwrap();
+            }
+
+            h.converge().unwrap();
+            h
+        };
+
+        for key in KEYS {
+            let one = batched.current_skill(key);
+            let other = incremental.current_skill(key);
+
+            match (one, other) {
+                (Some(one), Some(other)) => {
+                    prop_assert!(
+                        (one.mu() - other.mu()).abs() < 1e-6
+                            && (one.sigma() - other.sigma()).abs() < 1e-6,
+                        "{key}: batched mu={} sigma={}, incremental mu={} sigma={}",
+                        one.mu(),
+                        one.sigma(),
+                        other.mu(),
+                        other.sigma()
+                    );
+                }
+                (None, None) => {}
+                _ => prop_assert!(false, "{key} present in only one history"),
+            }
+        }
+    }
+}

tests/quality.rs

@@ -110,7 +110,7 @@ fn history_predict_quality_supports_three_teams() {
     h.record_winner(&"b", &"c", 2).unwrap();
     h.converge().unwrap();
 
-    let q = h.predict_quality(&[&[&"a"], &[&"b"], &[&"c"]]);
+    let q = h.predict_quality(&[&[&"a"], &[&"b"], &[&"c"]]).unwrap();
     assert!(
         q.is_finite(),
         "3-team predict_quality must be finite, got {q}"