chore: Release trueskill-tt version 0.8.0

Reject malformed games at the Game entry point, which does not pass
through History's ingestion chokepoint.

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

CHANGELOG.md

@@ -2,12 +2,51 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.8.0 - 2026-09-08
+
+### Breaking Changes
+
+- feat!: make a short fit an error and raise the default iteration cap
+- feat!: validate mu, sigma and beta on HistoryBuilder
+- feat!: add History::register and History::rating, and reject config conflicts across batches
+- fix!: reject non-finite weights at ingestion
+- fix!: reject malformed games at the Game boundary too
+
+### Bug Fixes
+
+- fix: reject malformed events at the ingestion boundary
+
+### Documentation
+
+- docs: record the rayon opt-in deviation in spec section 6
+- docs: state what the joint's cost actually scales in
+
+### Features
+
+- feat: add EventBuilder::members for per-member configuration
+
+### Other (unconventional)
+
+- Merge branch 'fix/ingestion-shape'
+- Merge branch 'feat/convergence-strictness'
+- Merge branch 'fix/non-finite-weights'
+- Merge branch 'test/close-coverage-gaps'
+- Merge branch 'fix/game-boundary'
+
+### Testing
+
+- test: cover non-finite results and color-group disjointness
+
 ## 0.7.0 - 2026-09-08
 
 ### Features
 
 - feat: factorise the joint once with History::joint
 
+### Miscellaneous Tasks
+
+- chore: Release trueskill-tt version 0.7.0
+
 ### Other (unconventional)
 
 - Merge branch 'feat/joint-handle'

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trueskill-tt"
-version = "0.7.0"
+version = "0.8.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"

src/color_group.rs

@@ -191,3 +191,121 @@ mod tests {
         assert_eq!(cg.total_events(), 4);
     }
 }
+
+#[cfg(test)]
+mod properties {
+    use std::collections::HashSet;
+
+    use proptest::prelude::*;
+
+    use super::*;
+
+    /// The property the whole parallel sweep rests on: two events sharing a
+    /// competitor must never land in the same color, because a color group is
+    /// run concurrently and two events touching one competitor would race.
+    ///
+    /// Hand-written cases cover the shapes someone thought of. This covers the
+    /// ones nobody did — the correctness of `sweep_color_groups` depends on it
+    /// holding for every input, not for five.
+    fn check(events: &[Vec<usize>]) {
+        let groups = color_greedy(events.len(), |ev| {
+            events[ev]
+                .iter()
+                .copied()
+                .map(Index::from)
+                .collect::<Vec<_>>()
+        });
+
+        // Disjointness *between events* within a color. Deduplicated per
+        // event, because one event legitimately naming a competitor twice is
+        // not a collision — `color_greedy` collects each event's members into
+        // a set for exactly that reason.
+        for color in 0..groups.n_colors() {
+            let mut seen: HashSet<usize> = HashSet::new();
+            for &ev in &groups.groups[color] {
+                let members: HashSet<usize> = events[ev].iter().copied().collect();
+                for competitor in members {
+                    assert!(
+                        seen.insert(competitor),
+                        "competitor {competitor} shared by two events in color {color}"
+                    );
+                }
+            }
+        }
+
+        // Every event is assigned exactly once. Without this, a partition that
+        // dropped events would satisfy disjointness trivially.
+        let mut assigned: Vec<usize> = groups.groups.iter().flatten().copied().collect();
+        assigned.sort_unstable();
+        assert_eq!(assigned, (0..events.len()).collect::<Vec<_>>());
+        assert_eq!(groups.total_events(), events.len());
+
+        // No empty colors: one would waste a sweep and make `n_colors`
+        // misleading.
+        for (color, group) in groups.groups.iter().enumerate() {
+            assert!(!group.is_empty(), "color {color} is empty");
+        }
+
+        // Contiguity is not a property of `color_greedy` — it holds only after
+        // `recompute_color_groups` reorders the events so each color occupies
+        // one range. What must always hold is that the reorder is *possible*:
+        // relabelling events in group order yields contiguous groups. The
+        // parallel sweep slices `&mut` sub-ranges from those, so if this ever
+        // failed the reorder would produce overlapping ranges.
+        let mut next = 0usize;
+        let relabelled: Vec<Vec<usize>> = groups
+            .groups
+            .iter()
+            .map(|group| {
+                group
+                    .iter()
+                    .map(|_| {
+                        let i = next;
+                        next += 1;
+                        i
+                    })
+                    .collect()
+            })
+            .collect();
+        assert!(ColorGroups { groups: relabelled }.groups_are_contiguous());
+    }
+
+    proptest! {
+        #![proptest_config(ProptestConfig::with_cases(512))]
+
+        /// Small competitor pool, so collisions are common and colors are
+        /// forced to multiply.
+        #[test]
+        fn colors_are_disjoint_on_a_dense_pool(
+            events in prop::collection::vec(
+                prop::collection::vec(0usize..6, 1..4),
+                0..20,
+            )
+        ) {
+            check(&events);
+        }
+
+        /// Wide pool, so most events are independent and land in one color.
+        #[test]
+        fn colors_are_disjoint_on_a_sparse_pool(
+            events in prop::collection::vec(
+                prop::collection::vec(0usize..200, 1..6),
+                0..30,
+            )
+        ) {
+            check(&events);
+        }
+
+        /// Repeated competitors within one event must not confuse the
+        /// member-set bookkeeping.
+        #[test]
+        fn colors_are_disjoint_with_repeated_members(
+            events in prop::collection::vec(
+                prop::collection::vec(0usize..3, 1..8),
+                0..15,
+            )
+        ) {
+            check(&events);
+        }
+    }
+}

src/convergence.rs

@@ -62,10 +62,17 @@ impl Default for ConvergenceOptions {
 }
 
 /// Post-hoc summary of a `History::converge` call.
+///
+/// From [`History::converge`](crate::History::converge) this always describes a
+/// converged fit — stopping at `max_iter` is
+/// [`InferenceError::NotConverged`](crate::InferenceError::NotConverged) there.
+/// From [`History::converge_partial`](crate::History::converge_partial) it may
+/// not be, and `converged` is what says so.
 #[derive(Clone, Debug)]
-#[must_use = "a ConvergenceReport carries `converged`, and a fit that stopped \
-              at `max_iter` is wrong by a little rather than loudly broken — \
-              check it, or bind it to `_` to say you have decided not to"]
+#[must_use = "from `converge_partial` this may describe a fit that stopped at \
+              `max_iter`, which is wrong by a little rather than loudly \
+              broken — check `converged`, or bind it to `_` to say you have \
+              decided not to"]
 pub struct ConvergenceReport {
     pub iterations: usize,
     pub final_step: (f64, f64),

src/error.rs

@@ -64,6 +64,24 @@ pub enum InferenceError {
     /// result has no representable likelihood. Configure a positive `p_draw`
     /// (via `HistoryBuilder::p_draw` or `GameOptions::p_draw`) to admit ties.
     TieWithoutDrawProbability { teams: (usize, usize) },
+    /// The convergence sweep hit `max_iter` with the step still above
+    /// `epsilon`.
+    ///
+    /// A fit that stops short is wrong by a little, which is the worst
+    /// available failure: every rating is finite, the ordering looks sensible,
+    /// and nothing in the numbers says they were still moving. Reported rather
+    /// than returned as a flag on an `Ok`, because a flag has to be checked
+    /// and `let _ = h.converge()` is the natural way not to.
+    ///
+    /// Either the history needs more iterations — raise `max_iter` — or it is
+    /// oscillating rather than converging, in which case `alpha < 1.0` damps
+    /// the within-game EP loop. [`History::converge_partial`](crate::History::converge_partial)
+    /// returns the short fit instead when that is genuinely what is wanted.
+    NotConverged {
+        iterations: usize,
+        final_step: (f64, f64),
+        epsilon: f64,
+    },
     /// Inference produced a non-finite value (NaN or infinity).
     ///
     /// Indicates numerical breakdown; the resulting skills are meaningless
@@ -100,6 +118,17 @@ pub enum InferenceError {
         member: usize,
         key: String,
     },
+    /// `History::register` was called for a competitor that already exists.
+    ///
+    /// Registration states a competitor's configuration before anything has
+    /// been observed about them, so a competitor that already exists has
+    /// already been configured — by an earlier `register`, or by an event that
+    /// created them. Silently overwriting would reintroduce exactly the
+    /// order-dependence registration exists to remove.
+    ///
+    /// To change an existing competitor's configuration, supply it on an event
+    /// through `Member`; that refits the whole history.
+    AlreadyRegistered { key: String },
     /// A prediction was given a team with no members.
     EmptyTeam { team: usize },
     /// A joint posterior was requested where one cannot be formed exactly.
@@ -144,6 +173,18 @@ impl fmt::Display for InferenceError {
                     teams.0, teams.1
                 )
             }
+            Self::NotConverged {
+                iterations,
+                final_step,
+                epsilon,
+            } => {
+                write!(
+                    f,
+                    "did not converge in {iterations} iterations: final step {final_step:?} \
+                     is still above epsilon {epsilon}; raise max_iter, or damp with \
+                     alpha < 1.0 if it is oscillating"
+                )
+            }
             Self::NonFiniteResult { context, step } => {
                 write!(
                     f,
@@ -167,6 +208,14 @@ impl fmt::Display for InferenceError {
                      with `lookup` or `current_skill` if that is not guaranteed)"
                 )
             }
+            Self::AlreadyRegistered { key } => {
+                write!(
+                    f,
+                    "competitor {key} is already registered; registration states \
+                     configuration before anything is observed, so re-registering \
+                     would silently overwrite it"
+                )
+            }
             Self::EmptyTeam { team } => {
                 write!(f, "team {team} has no members")
             }

src/game.rs

@@ -431,6 +431,29 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
 }
 
 impl<T: Time, D: Drift<T>> Game<'_, T, D> {
+    /// Reject the team shapes inference cannot represent.
+    ///
+    /// `run_chain` builds one diff link per adjacent pair of teams, so fewer
+    /// than two teams leaves it indexing `links[1..]` on an empty vector — a
+    /// panic, in release, from safe API. An empty team is the quiet half: it
+    /// contributes no performance, so a malformed game returns a finite,
+    /// plausible-looking posterior for whoever it was matched against.
+    ///
+    /// `History` validates the same two things at its own ingestion
+    /// chokepoint. `Game` is a separate public entry point that does not pass
+    /// through it, so it needs its own check rather than inheriting one.
+    fn validate_teams(teams: &[&[Rating<T, D>]]) -> Result<(), crate::InferenceError> {
+        if teams.len() < 2 {
+            return Err(crate::InferenceError::NotEnoughTeams { got: teams.len() });
+        }
+        for (team, members) in teams.iter().enumerate() {
+            if members.is_empty() {
+                return Err(crate::InferenceError::EmptyTeam { team });
+            }
+        }
+        Ok(())
+    }
+
     /// # Errors
     ///
     /// - `InvalidParameter` if `options.convergence` is out of range — an
@@ -442,12 +465,15 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
     /// - `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`.
+    /// - `NotEnoughTeams` for fewer than two teams, and `EmptyTeam` for a team
+    ///   with no members.
     pub fn ranked(
         teams: &[&[Rating<T, D>]],
         outcome: crate::Outcome,
         options: &GameOptions,
     ) -> Result<OwnedGame<T, D>, crate::InferenceError> {
         options.convergence.validate()?;
+        Self::validate_teams(teams)?;
         if !(0.0..1.0).contains(&options.p_draw) {
             return Err(crate::InferenceError::InvalidProbability {
                 value: options.p_draw,
@@ -499,12 +525,15 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
     ///   or is NaN, or if `options.convergence` is out of range.
     /// - `MismatchedShape` if the outcome's score count differs from `teams.len()`.
     /// - `WrongOutcomeKind` if `outcome` is not `Outcome::Scored`.
+    /// - `NotEnoughTeams` for fewer than two teams, `EmptyTeam` for a team with
+    ///   no members, and `InvalidParameter` for a non-finite score.
     pub fn scored(
         teams: &[&[Rating<T, D>]],
         outcome: crate::Outcome,
         options: &GameOptions,
     ) -> Result<OwnedGame<T, D>, crate::InferenceError> {
         options.convergence.validate()?;
+        Self::validate_teams(teams)?;
         if options.score_sigma <= 0.0 || options.score_sigma.is_nan() {
             return Err(crate::InferenceError::InvalidParameter {
                 name: "score_sigma",
@@ -526,6 +555,16 @@ impl<T: Time, D: Drift<T>> Game<'_, T, D> {
                 got: "Outcome::Ranked",
             })?
             .to_vec();
+        // A non-finite score poisons the chain rather than failing it. Ranks
+        // need no equivalent: they are `u32`.
+        for value in &scores {
+            if !value.is_finite() {
+                return Err(crate::InferenceError::InvalidParameter {
+                    name: "score",
+                    value: *value,
+                });
+            }
+        }
         let teams_owned: Vec<Vec<Rating<T, D>>> = teams.iter().map(|t| t.to_vec()).collect();
         let weights: Vec<Vec<f64>> = teams.iter().map(|t| vec![1.0; t.len()]).collect();
         Ok(OwnedGame::new_scored(

src/history.rs

@@ -6,6 +6,7 @@ use crate::{
     convergence::{ConvergenceOptions, ConvergenceReport},
     drift::{ConstantDrift, Drift},
     error::InferenceError,
+    event::Member,
     gaussian::Gaussian,
     key_table::KeyTable,
     observer::{NullObserver, Observer},
@@ -39,17 +40,55 @@ pub struct HistoryBuilder<
 }
 
 impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> HistoryBuilder<T, D, O, K> {
+    /// Prior mean skill.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `mu` is not finite. A non-finite prior mean poisons every
+    /// posterior derived from it: `converge` reports `NonFiniteResult`, but a
+    /// caller who reads `current_skill` first is handed `tau: NaN`.
     pub fn mu(mut self, mu: f64) -> Self {
+        assert!(mu.is_finite(), "mu must be finite (got {mu})");
         self.mu = mu;
         self
     }
 
+    /// Prior standard deviation.
+    ///
+    /// # Panics
+    ///
+    /// Panics unless `sigma` is finite and strictly positive.
+    ///
+    /// Zero and infinity both give a prior precision that is not a number, and
+    /// the whole fit comes back NaN. A *negative* sigma is the quieter half:
+    /// it is only ever squared, so `-8.33` produces bit-identical results to
+    /// `8.33` — a sign the caller cannot have meant, silently ignored.
     pub fn sigma(mut self, sigma: f64) -> Self {
+        assert!(
+            sigma.is_finite() && sigma > 0.0,
+            "sigma must be finite and positive (got {sigma})"
+        );
         self.sigma = sigma;
         self
     }
 
+    /// Per-event performance noise.
+    ///
+    /// # Panics
+    ///
+    /// Panics unless `beta` is finite and non-negative.
+    ///
+    /// Zero is allowed and meaningful — performance is then exactly skill, and
+    /// the fit differs measurably from a positive `beta` rather than
+    /// degenerating. Negative is rejected for the same reason as a negative
+    /// `sigma` or `Member::with_drift_scale`: `beta` enters only as `beta^2`,
+    /// so a negative value behaves as its absolute value and the sign is lost
+    /// without comment.
     pub fn beta(mut self, beta: f64) -> Self {
+        assert!(
+            beta.is_finite() && beta >= 0.0,
+            "beta must be finite and non-negative (got {beta})"
+        );
         self.beta = beta;
         self
     }
@@ -169,6 +208,7 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> HistoryBuilder<
             convergence: self.convergence,
             observer: self.observer,
             unknown_keys: self.unknown_keys,
+            declared: HashMap::new(),
         }
     }
 }
@@ -276,6 +316,12 @@ pub struct History<
     convergence: ConvergenceOptions,
     observer: O,
     unknown_keys: crate::UnknownKeys,
+    /// Competitor configuration explicitly declared so far, by whichever route.
+    ///
+    /// Kept separate from the applied `Rating` because a `Rating` cannot say
+    /// whether a value was *chosen* or inherited from the history defaults,
+    /// and that is exactly the distinction a conflict check needs.
+    declared: HashMap<Index, CompetitorConfig>,
 }
 
 impl Default for History<i64, ConstantDrift, NullObserver, &'static str> {
@@ -455,6 +501,111 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     }
 
     /// Skill estimate at the latest time slice the competitor appears in.
+    /// Configure a competitor before anything has been observed about them.
+    ///
+    /// The configuration a competitor needs is often a property of the domain
+    /// rather than of any one event — "every layout is static", "this bot sits
+    /// at a known strength". Stating it per-event means every ingestion path
+    /// has to remember it, and the fluent and two-argument paths could not
+    /// state it at all.
+    ///
+    /// ```
+    /// # use trueskill_tt::{History, Member};
+    /// let mut h = History::builder().build();
+    /// h.register(Member::new("layout_7").with_drift_scale(0.0))?;
+    ///
+    /// // Reaches a competitor first seen through any route, including the
+    /// // two-argument one, which cannot carry configuration itself.
+    /// h.record_winner(&"player", &"layout_7", 1)?;
+    /// assert_eq!(h.rating(&"layout_7").unwrap().drift_scale(), 0.0);
+    /// # Ok::<(), trueskill_tt::InferenceError>(())
+    /// ```
+    ///
+    /// The competitor exists from this point on, with no appearances, so
+    /// [`History::rating`] can read back what was actually stored — the
+    /// diagnostic that was previously missing entirely.
+    ///
+    /// `weight` is per-event and has no meaning here, so a `Member` carrying a
+    /// non-default one is rejected rather than silently ignored.
+    ///
+    /// # Errors
+    ///
+    /// `AlreadyRegistered` if the competitor already exists, whether from an
+    /// earlier `register` or from an event. `InvalidParameter` for a `weight`
+    /// other than 1.0, or a `drift_scale` that is negative or non-finite.
+    pub fn register(&mut self, member: Member<K>) -> Result<(), InferenceError>
+    where
+        K: std::fmt::Debug,
+    {
+        if member.weight != 1.0 {
+            return Err(InferenceError::InvalidParameter {
+                name: "weight",
+                value: member.weight,
+            });
+        }
+        if let Some(scale) = member.drift_scale {
+            if !scale.is_finite() || scale < 0.0 {
+                return Err(InferenceError::InvalidParameter {
+                    name: "drift_scale",
+                    value: scale,
+                });
+            }
+        }
+
+        let key = format!("{:?}", member.key);
+        let idx = self.keys.get_or_create(&member.key);
+        if self.agents.contains(idx) {
+            return Err(InferenceError::AlreadyRegistered { key });
+        }
+
+        let mut rating = 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;
+        }
+
+        self.declared.insert(
+            idx,
+            CompetitorConfig {
+                prior: member.prior,
+                drift_scale: member.drift_scale,
+            },
+        );
+        self.agents.insert(
+            idx,
+            Competitor {
+                rating,
+                message: None,
+                last_time: None,
+            },
+        );
+
+        Ok(())
+    }
+
+    /// The configuration in force for a competitor, or `None` if the history
+    /// has never seen them.
+    ///
+    /// Reads back what was actually stored, which is what makes a
+    /// configuration mistake detectable from outside the crate. Every other
+    /// accessor returns what inference *inferred*; this returns what it was
+    /// told.
+    #[must_use]
+    pub fn rating<Q>(&self, key: &Q) -> Option<Rating<T, D>>
+    where
+        K: std::borrow::Borrow<Q>,
+        Q: std::hash::Hash + Eq + ?Sized,
+    {
+        let idx = self.keys.get(key)?;
+        self.agents.contains(idx).then(|| self.agents[idx].rating)
+    }
+
     pub fn current_skill<Q>(&self, key: &Q) -> Option<Gaussian>
     where
         K: std::borrow::Borrow<Q>,
@@ -958,6 +1109,14 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     /// [`Joint`] with [`History::joint`] instead — the answers are identical,
     /// and only the first one pays.
     ///
+    /// # Cost
+    ///
+    /// A dense solve over the history's *appearances*, not its competitors. A
+    /// drift-free competitor collapses to a single variable however long the
+    /// history, so the same events can differ enormously in cost depending on
+    /// the drift configuration — see [`Joint`], which also amortises this
+    /// across many questions.
+    ///
     /// # Limitations
     ///
     /// Exact only for a history whose events are all scored, because a scored
@@ -1390,17 +1549,62 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         ))
     }
 
-    /// Run the full forward+backward convergence loop and return a summary.
+    /// Run the full forward+backward convergence loop to a fixed point.
     ///
-    /// Failing to reach `epsilon` within `max_iter` is not an error: the
-    /// returned report carries `converged: false` and the final step.
+    /// # Stopping short is an error
+    ///
+    /// Hitting `max_iter` without reaching `epsilon` returns `NotConverged`.
+    ///
+    /// It used to return `Ok` with `converged: false`, which was the worst
+    /// available shape. A fit that stops short is *wrong by a little*: every
+    /// rating is finite, the ordering looks sensible, and nothing about the
+    /// output says the numbers were still moving. Detection was opt-in, and
+    /// `let _ = h.converge()` silently opted out — which is how a real defect
+    /// hid in this crate's own test suite.
+    ///
+    /// The default `max_iter` is [`ITERATIONS`](crate::ITERATIONS), which is
+    /// set high enough that reaching it means something is genuinely wrong
+    /// rather than that the history is merely large. Raising the cap costs
+    /// nothing when it is not needed, because the loop exits at `epsilon`.
+    ///
+    /// Use [`History::converge_partial`] when a capped, unconverged fit is
+    /// what you actually want.
     ///
     /// # Errors
     ///
+    /// `NotConverged` if the sweep hits `max_iter` with the step still above
+    /// `epsilon`.
+    ///
     /// `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> {
+        let report = self.converge_partial()?;
+
+        if report.converged {
+            Ok(report)
+        } else {
+            Err(InferenceError::NotConverged {
+                iterations: report.iterations,
+                final_step: report.final_step,
+                epsilon: self.convergence.epsilon,
+            })
+        }
+    }
+
+    /// As [`History::converge`], but a fit that stops at `max_iter` is
+    /// returned rather than reported as an error.
+    ///
+    /// The report's `converged` flag says which happened. Use this when a
+    /// deliberately capped sweep is the point — a cheap approximate fit, or a
+    /// test that pins what a fixed number of iterations produces. Prefer
+    /// `converge` everywhere else: an unconverged fit that nobody checks is
+    /// indistinguishable from a converged one.
+    ///
+    /// # Errors
+    ///
+    /// `NonFiniteResult` if a sweep produces a NaN or infinite step.
+    pub fn converge_partial(&mut self) -> Result<ConvergenceReport, InferenceError> {
         use std::time::Instant;
 
         use smallvec::SmallVec;
@@ -1549,6 +1753,29 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             }
         }
 
+        // A non-finite weight is not a weight. Measured, it behaves exactly as
+        // `0.0` — the member contributes nothing — while `converge` reports
+        // `converged: true` after one iteration with a step of `(0.0, 0.0)`.
+        // So a NaN arriving from a division or a parse is indistinguishable
+        // from a deliberate zero, and looks like a clean fit.
+        //
+        // Zero and negative weights stay accepted: both are expressible
+        // choices about how much a member contributes, and
+        // `tests/degenerate_inputs.rs` pins them deliberately. Only the values
+        // that are not quantities at all are rejected.
+        if let Some(weights) = weights.as_ref() {
+            for team_weights in weights.iter().flatten() {
+                for weight in team_weights {
+                    if !weight.is_finite() {
+                        return Err(InferenceError::InvalidParameter {
+                            name: "weight",
+                            value: *weight,
+                        });
+                    }
+                }
+            }
+        }
+
         // Chokepoint for tie validation: every ingestion route lands here,
         // including `record_draw`, which builds its results directly rather
         // than going through `Outcome`.
@@ -1564,6 +1791,47 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             }
         }
 
+        // Cross-batch conflict. The in-batch check upstream rejects one batch
+        // that sets a field twice; `priors` is rebuilt per call, so without
+        // this a *second* batch could quietly overwrite what a first one
+        // declared, last-write-wins.
+        //
+        // That asymmetry cut against the invariant `tests/ingestion_equivalence.rs`
+        // exists to protect: the same contradictory events errored when
+        // batched and succeeded, order-dependently, when fed one at a time.
+        // Checked before anything mutates, so a rejected batch leaves the
+        // history untouched.
+        for (agent, batch) in &priors {
+            let held = self.declared.get(agent).copied().unwrap_or_default();
+
+            if let (Some(existing), Some(new)) = (held.prior, batch.prior) {
+                if existing != new {
+                    return Err(InferenceError::ConflictingCompetitorConfig {
+                        competitor: agent.get(),
+                        field: "prior",
+                    });
+                }
+            }
+            if let (Some(existing), Some(new)) = (held.drift_scale, batch.drift_scale) {
+                if existing != new {
+                    return Err(InferenceError::ConflictingCompetitorConfig {
+                        competitor: agent.get(),
+                        field: "drift_scale",
+                    });
+                }
+            }
+        }
+
+        for (agent, batch) in &priors {
+            let entry = self.declared.entry(*agent).or_default();
+            if batch.prior.is_some() {
+                entry.prior = batch.prior;
+            }
+            if batch.drift_scale.is_some() {
+                entry.drift_scale = batch.drift_scale;
+            }
+        }
+
         competitor::clean(self.agents.values_mut(), true);
 
         let mut this_agent = Vec::with_capacity(1024);
@@ -1575,7 +1843,9 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
 
             this_agent.push(*agent);
 
-            let config = priors.get(agent).copied().unwrap_or_default();
+            // From `declared` rather than `priors`: a competitor configured by
+            // `register` before any event has nothing in this batch's map.
+            let config = self.declared.get(agent).copied().unwrap_or_default();
 
             if self.agents.contains(*agent) {
                 // Seeding a competitor the history already knows. This used to
@@ -1966,6 +2236,34 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
 /// added while it is alive. That is what makes it correct without any
 /// invalidation logic: there is no window in which the factorisation could
 /// describe a fit that no longer exists.
+///
+/// # What the cost actually scales in
+///
+/// Not competitors, and not slices times competitors. One variable per
+/// *appearance* — a competitor per slice they appear in — minus every
+/// consecutive pair with no drift between them, which collapse to a single
+/// latent variable.
+///
+/// That last clause dominates, and it is not obvious. A competitor whose drift
+/// is zero contributes **one** variable however long the history: whole-history
+/// `gamma = 0`, or `drift_scale = 0` on that competitor. So two fits over the
+/// same events and the same slices can differ in problem size by roughly the
+/// slice count, and in factorisation time by its cube. Measured by a consumer
+/// on a ~2,000-node model over 76 slices:
+///
+/// ```text
+/// career fit   (gamma = 0)      787 ms per solve
+/// drifting fit (gamma = 0.15)  6214 ms per solve
+/// ```
+///
+/// Choosing between a drifting and a drift-free configuration is therefore also
+/// choosing an 8x difference in query cost. [`Joint::variables`] reports the
+/// number that decides it, and can be read before committing to a batch of
+/// queries.
+///
+/// Slices a competitor sits out cost nothing: an absence is not an appearance,
+/// so a competitor seen in the first and last of a hundred slices contributes
+/// two variables, not a hundred.
 pub struct Joint<'h, T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> {
     history: &'h History<T, D, O, K>,
     cholesky: crate::joint::Cholesky,
@@ -1993,9 +2291,14 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> Joint<'_, T, D,
     /// Number of variables in the joint: the history's appearances, after
     /// collapsing consecutive pairs a competitor does not drift between.
     ///
-    /// This is what the cost scales in, and it is not the competitor count — a
-    /// competitor contributes one variable per slice it appears in. Worth
-    /// checking before asking for a joint over a long history.
+    /// This is what the cost scales in — `O(n^3)` to factorise, `O(n^2)` per
+    /// query — and it is neither the competitor count nor slices times
+    /// competitors. A drift-free competitor contributes one variable however
+    /// many slices they appear in; see the type docs for how large that
+    /// difference gets.
+    ///
+    /// Worth reading before committing to a batch of queries: it is the one
+    /// number that says whether a joint over this history is affordable.
     #[must_use]
     pub fn variables(&self) -> usize {
         self.width
@@ -2799,13 +3102,15 @@ mod tests {
             epsilon = 1e-6
         );
 
-        // run exactly 11 iterations (old test used convergence(11, ...))
+        // Run exactly 11 iterations. `converge_partial` rather than
+        // `converge`: stopping at the cap is the point here, and `converge`
+        // now reports that as `NotConverged`.
         h.convergence = ConvergenceOptions {
             max_iter: 11,
             epsilon: EPSILON,
             alpha: 1.0,
         };
-        let _ = h.converge().unwrap();
+        let _ = h.converge_partial().unwrap();
 
         let loocv_approx_2 = h.log_evidence_internal(false, &[]).exp().sqrt();
 
@@ -3172,7 +3477,9 @@ mod tests {
             })
             .build();
         events_for(&mut h_capped);
-        let _ = h_capped.converge().unwrap();
+        // A one-iteration cap is deliberate here, so the short fit is the
+        // result rather than an error.
+        let _ = h_capped.converge_partial().unwrap();
 
         let mut h_full: History<i64, _, _, &'static str> = History::builder().build();
         events_for(&mut h_full);

src/lib.rs

@@ -158,22 +158,43 @@ pub const P_DRAW: f64 = 0.0;
 pub const EPSILON: f64 = 1e-6;
 /// Default cap on convergence sweeps.
 ///
-/// **This is a floor, not a recommendation.** It is adequate for small
-/// histories and is quickly outgrown: a history of 400 events over 100
-/// competitors already stops here with a final step of ~7e-3 against the 1e-6
-/// default tolerance — four orders of magnitude short — and a dense joint model
-/// of ~2,000 nodes over ~3,300 events has been measured needing 76 to 161.
+/// **A runaway guard, not a budget.** The sweep exits as soon as the step falls
+/// below `epsilon`, so the cap is never reached by a history that converges and
+/// raising it costs nothing. Measured on a history that needs four sweeps:
 ///
-/// Overrunning it is not an error, and deliberately so: `converge` returns a
-/// [`ConvergenceReport`] whose `converged` flag says what happened. But a fit
-/// that stopped short is *wrong by a little*, which is the worst available
-/// failure — every rating is finite and ordered sensibly, and nothing in the
-/// numbers themselves says they were still moving. Read the report; the type is
-/// `#[must_use]` for that reason.
+/// ```text
+/// max_iter      30: 4 iterations, 129.9 us
+/// max_iter 100_000: 4 iterations, 131.9 us
+/// ```
 ///
-/// Raise it via [`ConvergenceOptions`]. Convergence cost is roughly linear in
-/// the cap, and for anything but a toy the extra sweeps are milliseconds.
-pub const ITERATIONS: usize = 30;
+/// This was `30` until it was measured, and 30 truncated ordinary healthy
+/// histories: 160 events over 100 competitors already needs 42. Because a short
+/// fit is finite and sensibly ordered, that was invisible.
+///
+/// # Why it is not scaled to the history
+///
+/// The obvious improvement — pick the cap from the node or event count — does
+/// not work, because iteration count is driven by how *loopy* the graph is
+/// rather than how big it is. At a fixed 320 events over 40 slices, varying
+/// only the number of competitors sharing them:
+///
+/// ```text
+/// competitors    appearances each    iterations
+///           3                 213         2_789
+///          10                  64         1_068
+///          50                12.8           206
+///         100                 6.4            90
+///         400                 1.6             2
+/// ```
+///
+/// Three orders of magnitude apart on identical event and slice counts. Any
+/// formula in those two numbers would be badly wrong on some real shape, so the
+/// cap is a single value set high enough that reaching it means the fit is
+/// oscillating rather than merely large.
+///
+/// Reaching it is [`InferenceError::NotConverged`]. See
+/// [`History::converge`](crate::History::converge).
+pub const ITERATIONS: usize = 10_000;
 
 /// Largest team count `History::predict_outcome` will enumerate.
 ///

tests/convergence_strictness.rs

@@ -0,0 +1,152 @@
+//! Stopping short of convergence is an error, not a flag on a success.
+//!
+//! A fit that hits `max_iter` is wrong by a little: every rating is finite,
+//! the ordering looks sensible, and nothing in the numbers says they were
+//! still moving. When that was `Ok` with `converged: false`, detecting it was
+//! opt-in and `let _ = h.converge()` was the natural way to opt out — which is
+//! how a real defect once hid in this crate's own suite.
+
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, History, InferenceError, Member, Outcome, Team,
+};
+
+type H = History<i64, ConstantDrift, trueskill_tt::NullObserver, &'static str>;
+
+fn duel(a: &'static str, b: &'static str, t: i64) -> Event<i64, &'static str> {
+    Event {
+        time: t,
+        teams: smallvec![
+            Team::with_members([Member::new(a)]),
+            Team::with_members([Member::new(b)]),
+        ],
+        outcome: Outcome::scores([3.0, 1.0]),
+    }
+}
+
+fn capped(max_iter: usize) -> H {
+    History::builder()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .score_sigma(2.0)
+        .drift(ConstantDrift(0.5))
+        .convergence(ConvergenceOptions {
+            max_iter,
+            epsilon: 1e-13,
+            alpha: 1.0,
+        })
+        .build()
+}
+
+fn fill(h: &mut H) {
+    h.add_events((1..=6).map(|t| duel("a", "b", t)).collect::<Vec<_>>())
+        .unwrap();
+}
+
+#[test]
+fn hitting_the_cap_is_an_error() {
+    let mut h = capped(1);
+    fill(&mut h);
+    let err = h.converge().unwrap_err();
+    match err {
+        InferenceError::NotConverged {
+            iterations,
+            final_step,
+            epsilon,
+        } => {
+            assert_eq!(iterations, 1);
+            assert!(
+                final_step.0 > epsilon || final_step.1 > epsilon,
+                "{final_step:?}"
+            );
+        }
+        other => panic!("expected NotConverged, got {other:?}"),
+    }
+}
+
+/// The message has to name what to do about it, since the fit looks fine.
+#[test]
+fn the_error_says_how_to_fix_it() {
+    let mut h = capped(1);
+    fill(&mut h);
+    let text = h.converge().unwrap_err().to_string();
+    assert!(text.contains("did not converge in 1 iterations"), "{text}");
+    assert!(text.contains("max_iter"), "{text}");
+    assert!(text.contains("alpha"), "{text}");
+}
+
+/// The escape hatch: a deliberately capped fit is still reachable.
+#[test]
+fn converge_partial_returns_the_short_fit() {
+    let mut h = capped(1);
+    fill(&mut h);
+    let report = h.converge_partial().unwrap();
+    assert_eq!(report.iterations, 1);
+    assert!(!report.converged);
+    assert!(h.current_skill(&"a").is_some());
+}
+
+/// Both agree when the fit does converge, so the strict path costs nothing.
+#[test]
+fn the_two_agree_on_a_converged_fit() {
+    let mut strict = capped(20_000);
+    fill(&mut strict);
+    let a = strict.converge().unwrap();
+
+    let mut partial = capped(20_000);
+    fill(&mut partial);
+    let b = partial.converge_partial().unwrap();
+
+    assert!(a.converged && b.converged);
+    assert_eq!(a.iterations, b.iterations);
+    assert_eq!(a.final_step, b.final_step);
+}
+
+/// The default cap must be high enough that an ordinary history clears it.
+/// At the old value of 30 this history stopped short and said nothing.
+#[test]
+fn the_default_cap_clears_an_ordinary_history() {
+    let mut h: History<i64, ConstantDrift, _, String> = History::builder_with_key()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .score_sigma(2.0)
+        .drift(ConstantDrift(0.05))
+        .build();
+
+    let mut events = Vec::new();
+    for t in 0..20i64 {
+        for j in 0..8usize {
+            let k = (t as usize) * 8 + j;
+            events.push(Event {
+                time: t,
+                teams: smallvec![
+                    Team::with_members([Member::new(format!("p{}", k % 100))]),
+                    Team::with_members([Member::new(format!("p{}", (k + 37) % 100))]),
+                ],
+                outcome: Outcome::scores([3.0, 1.0]),
+            });
+        }
+    }
+    h.add_events(events).unwrap();
+
+    let report = h
+        .converge()
+        .expect("an ordinary history must converge by default");
+    assert!(
+        report.iterations > 30,
+        "needed {} sweeps",
+        report.iterations
+    );
+    assert!(report.iterations < trueskill_tt::ITERATIONS);
+}
+
+/// An empty history converges trivially rather than erroring.
+#[test]
+fn an_empty_history_converges() {
+    let mut h = capped(1);
+    let report = h.converge().unwrap();
+    assert!(report.converged);
+    assert_eq!(report.iterations, 0);
+}

tests/game.rs

@@ -138,3 +138,115 @@ fn one_v_one_honours_convergence_options() {
     let (a_post, _) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2), &options).unwrap();
     assert!(a_post.mu() > 25.0);
 }
+
+/// `Game` is a public entry point that does not pass through `History`'s
+/// ingestion chokepoint, so it needs its own boundary — and did not have one.
+///
+/// A one-team game panicked at `src/game.rs:317` with "range start index 1 out
+/// of range for slice of length 0", in release, from safe API. This is the
+/// same defect `tests/ingestion_shape.rs` covers for `History`; fixing that
+/// path left this one open, because they share no validation.
+mod malformed_games {
+    use super::*;
+
+    #[test]
+    fn a_one_team_ranked_game_is_an_error_not_a_panic() {
+        let a = default_rating();
+        let err = Game::<i64, _>::ranked(&[&[a]], Outcome::winner(0, 1), &GameOptions::default())
+            .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::NotEnoughTeams { got: 1 }),
+            "{err:?}"
+        );
+    }
+
+    #[test]
+    fn a_one_team_scored_game_is_an_error_not_a_panic() {
+        let a = default_rating();
+        let err = Game::<i64, _>::scored(
+            &[&[a]],
+            Outcome::scores([1.0]),
+            &GameOptions {
+                score_sigma: 1.0,
+                ..GameOptions::default()
+            },
+        )
+        .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::NotEnoughTeams { got: 1 }),
+            "{err:?}"
+        );
+    }
+
+    #[test]
+    fn a_zero_team_game_is_an_error() {
+        let err =
+            Game::<i64, ConstantDrift>::ranked(&[], Outcome::ranking([]), &GameOptions::default())
+                .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::NotEnoughTeams { got: 0 }),
+            "{err:?}"
+        );
+    }
+
+    /// The quiet half: an empty team contributed no performance, so the game
+    /// returned a finite posterior for its opponent as though it had won one.
+    #[test]
+    fn an_empty_team_is_an_error() {
+        let a = default_rating();
+        let err =
+            Game::<i64, _>::ranked(&[&[], &[a]], Outcome::winner(0, 2), &GameOptions::default())
+                .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::EmptyTeam { team: 0 }),
+            "{err:?}"
+        );
+    }
+
+    #[test]
+    fn a_non_finite_score_is_an_error() {
+        let a = default_rating();
+        for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+            let err = Game::<i64, _>::scored(
+                &[&[a], &[a]],
+                Outcome::scores([bad, 1.0]),
+                &GameOptions {
+                    score_sigma: 1.0,
+                    ..GameOptions::default()
+                },
+            )
+            .unwrap_err();
+            assert!(
+                matches!(err, InferenceError::InvalidParameter { name: "score", .. }),
+                "{bad}: {err:?}"
+            );
+        }
+    }
+
+    /// `free_for_all` and `one_v_one` build their teams internally, so they
+    /// must keep working — the check must not catch well-formed games.
+    #[test]
+    fn well_formed_games_are_untouched() {
+        let a = default_rating();
+        assert!(
+            Game::<i64, _>::ranked(
+                &[&[a], &[a]],
+                Outcome::winner(0, 2),
+                &GameOptions::default()
+            )
+            .is_ok()
+        );
+        assert!(
+            Game::<i64, _>::free_for_all(
+                &[&a, &a, &a],
+                Outcome::ranking([0, 1, 2]),
+                &GameOptions::default()
+            )
+            .is_ok()
+        );
+        assert!(
+            Game::<i64, _>::one_v_one(&a, &a, Outcome::winner(0, 2), &GameOptions::default())
+                .is_ok()
+        );
+    }
+}

tests/ingestion_shape.rs

@@ -120,6 +120,49 @@ fn a_non_finite_score_is_rejected_at_ingestion() {
     }
 }
 
+/// A non-finite weight behaved exactly as `0.0` — the member contributed
+/// nothing — while `converge` reported `converged: true` after one iteration
+/// with a step of `(0.0, 0.0)`. So a NaN arriving from a division or a parse
+/// was indistinguishable from a deliberate zero, and looked like a clean fit.
+#[test]
+fn a_non_finite_weight_is_rejected_at_ingestion() {
+    for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+        let mut h = history();
+        let err = h
+            .event(1)
+            .team(["a"])
+            .weights([bad])
+            .team(["b"])
+            .winner(0)
+            .commit()
+            .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::InvalidParameter { name: "weight", .. }),
+            "{bad}: {err:?}"
+        );
+        assert!(h.current_skill(&"a").is_none(), "{bad} reached the history");
+    }
+}
+
+/// Zero and negative weights are expressible choices about how much a member
+/// contributes, not malformed input, and `tests/degenerate_inputs.rs` pins
+/// their behaviour deliberately. Rejecting non-finite values must not catch
+/// them too.
+#[test]
+fn zero_and_negative_weights_still_ingest() {
+    for w in [0.0, -1.0, 0.5] {
+        let mut h = history();
+        h.event(1)
+            .team(["a"])
+            .weights([w])
+            .team(["b"])
+            .winner(0)
+            .commit()
+            .unwrap_or_else(|e| panic!("weight {w} should ingest: {e:?}"));
+        assert!(h.current_skill(&"a").is_some(), "weight {w}");
+    }
+}
+
 /// The fluent builder routes through the same chokepoint, so it inherits the
 /// checks rather than needing its own.
 #[test]

tests/joint_handle.rs

@@ -141,6 +141,53 @@ fn variables_counts_appearances_not_competitors() {
     assert_eq!(joint.variables(), 12);
 }
 
+/// How much the collapse is worth, which is the part a caller has to plan
+/// around: a drift-free competitor contributes **one** variable however long
+/// the history, so the same events at `gamma = 0` and `gamma > 0` differ by
+/// roughly the slice count in problem size — and by its cube in solve time.
+///
+/// Reported by a consumer as an 8x difference in solve time on a ~2,000-node,
+/// 76-slice model (787 ms career against 6,214 ms drifting). This pins the
+/// mechanism behind that so a change to the collapse rule cannot quietly
+/// remove it.
+#[test]
+fn drift_free_competitors_shrink_the_joint_by_the_slice_count() {
+    fn variables(gamma: f64) -> usize {
+        let mut h = History::builder()
+            .mu(0.0)
+            .sigma(6.0)
+            .beta(1.0)
+            .score_sigma(2.0)
+            .drift(ConstantDrift(gamma))
+            .convergence(ConvergenceOptions {
+                max_iter: 20_000,
+                epsilon: 1e-13,
+                alpha: 1.0,
+            })
+            .build();
+        h.add_events(
+            (1..=10)
+                .map(|t| duel("a", "b", t, 5.0, 2.0))
+                .collect::<Vec<_>>(),
+        )
+        .unwrap();
+        let _ = h.converge().unwrap();
+        h.joint().unwrap().variables()
+    }
+
+    let drifting = variables(0.5);
+    let career = variables(0.0);
+
+    // Two competitors over ten slices: twenty appearances, or two variables.
+    assert_eq!(drifting, 20);
+    assert_eq!(career, 2);
+    assert_eq!(
+        drifting / career,
+        10,
+        "collapse should track the slice count"
+    );
+}
+
 /// With `drift = 0` consecutive appearances are the same latent variable, so
 /// the joint is smaller than the appearance count.
 #[test]

tests/non_finite_results.rs

@@ -0,0 +1,117 @@
+//! Inference must report numerical breakdown rather than call it convergence.
+//!
+//! The boundary rejects inputs that are *not numbers*, but finite inputs can
+//! still overflow during inference — `beta.powi(2)` at 1e300 is infinite, and
+//! infinity minus infinity is NaN. `NonFiniteResult` is the guard for that, and
+//! it matters because the alternative is silent: NaN fails every comparison, so
+//! a naive `step < epsilon` check reads a NaN step as *converged*.
+//!
+//! That is why the crate has `step_converged` / `step_is_finite` rather than
+//! `!tuple_gt(..)`. These tests pin the guard from outside.
+
+use smallvec::smallvec;
+use trueskill_tt::{Event, Gaussian, History, InferenceError, Member, Outcome, Team};
+
+fn scored_fit(
+    sigma: f64,
+    beta: f64,
+    score_sigma: f64,
+    scores: [f64; 2],
+) -> Result<bool, InferenceError> {
+    let mut h = History::builder()
+        .mu(0.0)
+        .sigma(sigma)
+        .beta(beta)
+        .score_sigma(score_sigma)
+        .build();
+    h.add_events(vec![Event {
+        time: 1i64,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::scores(scores),
+    }])?;
+    h.converge().map(|r| r.converged)
+}
+
+/// Every one of these is built from finite, individually legal parameters. The
+/// overflow happens inside inference, which is exactly the case the boundary
+/// checks cannot catch.
+///
+/// Matched rather than merely `is_err()`: an assertion that only checks "some
+/// error" would keep passing if these started failing at the boundary for an
+/// unrelated reason, and would then be testing nothing.
+#[test]
+fn overflow_during_inference_is_reported_not_hidden() {
+    let cases: [(&str, f64, f64, f64, [f64; 2]); 5] = [
+        ("huge sigma", 1e300, 1.0, 1.0, [3.0, 1.0]),
+        ("huge beta", 6.0, 1e300, 1.0, [3.0, 1.0]),
+        ("tiny sigma", 1e-300, 1.0, 1.0, [3.0, 1.0]),
+        ("tiny score_sigma", 6.0, 1.0, 1e-300, [3.0, 1.0]),
+        ("huge scores", 6.0, 1.0, 1.0, [1e308, -1e308]),
+    ];
+
+    for (name, sigma, beta, score_sigma, scores) in cases {
+        match scored_fit(sigma, beta, score_sigma, scores) {
+            Err(InferenceError::NonFiniteResult { context, step }) => {
+                assert_eq!(context, "History::converge", "{name}");
+                assert!(
+                    !step.0.is_finite() || !step.1.is_finite(),
+                    "{name}: reported NonFiniteResult with a finite step {step:?}"
+                );
+            }
+            other => panic!("{name}: expected NonFiniteResult, got {other:?}"),
+        }
+    }
+}
+
+/// The trap the invariant exists for: NaN fails every comparison, so a naive
+/// `step < epsilon` test reads a NaN step as converged. A breakdown must never
+/// come back as a successful fit.
+#[test]
+fn a_broken_fit_is_never_reported_as_converged() {
+    let mut h = History::builder().build();
+    h.add_events(vec![Event {
+        time: 1i64,
+        teams: smallvec![
+            Team::with_members([Member::new("a").with_prior(Gaussian::from_ms(1e300, 1e-300))]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::winner(0, 2),
+    }])
+    .unwrap();
+
+    let err = h.converge().unwrap_err();
+    assert!(
+        matches!(err, InferenceError::NonFiniteResult { .. }),
+        "a breakdown must not be reported as convergence: {err:?}"
+    );
+
+    // `converge_partial` must not launder it into an `Ok` either — the
+    // permissive path is permissive about *stopping short*, not about NaN.
+    let mut h2 = History::builder().build();
+    h2.add_events(vec![Event {
+        time: 1i64,
+        teams: smallvec![
+            Team::with_members([Member::new("a").with_prior(Gaussian::from_ms(1e300, 1e-300))]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::winner(0, 2),
+    }])
+    .unwrap();
+    assert!(matches!(
+        h2.converge_partial().unwrap_err(),
+        InferenceError::NonFiniteResult { .. }
+    ));
+}
+
+/// The neighbouring case, so the tests above cannot pass by the fit simply
+/// always failing: ordinary extreme-but-workable parameters still converge.
+#[test]
+fn merely_extreme_parameters_still_converge() {
+    assert!(scored_fit(1e6, 1.0, 1.0, [3.0, 1.0]).unwrap());
+    assert!(scored_fit(1e-6, 1.0, 1.0, [3.0, 1.0]).unwrap());
+    assert!(scored_fit(6.0, 1.0, 1e6, [3.0, 1.0]).unwrap());
+    assert!(scored_fit(6.0, 1.0, 1.0, [1e150, -1e150]).unwrap());
+}

tests/registration.rs

@@ -0,0 +1,338 @@
+//! Configuring a competitor before anything is observed about them.
+//!
+//! The configuration a competitor needs is usually a property of the domain —
+//! "every layout is static" — not of whichever event happens to mention them
+//! first. Stating it per-event meant every ingestion path had to remember it,
+//! and two of the four paths could not state it at all.
+
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, Gaussian, History, InferenceError, Member, Outcome,
+    Team,
+};
+
+type H = History<i64, ConstantDrift, trueskill_tt::NullObserver, &'static str>;
+
+const PINNED: Gaussian = Gaussian::from_ms(2.0, 0.5);
+
+fn history() -> H {
+    History::builder()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .score_sigma(2.0)
+        .drift(ConstantDrift(0.5))
+        .convergence(ConvergenceOptions {
+            max_iter: 20_000,
+            epsilon: 1e-13,
+            alpha: 1.0,
+        })
+        .build()
+}
+
+fn duel(
+    a: &'static str,
+    b: &'static str,
+    t: i64,
+    m: Option<Member<&'static str>>,
+) -> Event<i64, &'static str> {
+    Event {
+        time: t,
+        teams: smallvec![
+            Team::with_members([Member::new(a)]),
+            Team::with_members([m.unwrap_or_else(|| Member::new(b))]),
+        ],
+        outcome: Outcome::scores([5.0, 2.0]),
+    }
+}
+
+fn skills(h: &H) -> Vec<(&'static str, Gaussian)> {
+    ["player", "layout"]
+        .into_iter()
+        .map(|k| (k, h.current_skill(&k).unwrap()))
+        .collect()
+}
+
+/// The headline contract.
+#[test]
+fn registering_matches_configuring_on_the_first_event() {
+    let configured = {
+        let mut h = history();
+        h.add_events(vec![
+            duel(
+                "player",
+                "layout",
+                1,
+                Some(
+                    Member::new("layout")
+                        .with_drift_scale(0.0)
+                        .with_prior(PINNED),
+                ),
+            ),
+            duel("player", "layout", 2, None),
+        ])
+        .unwrap();
+        let _ = h.converge().unwrap();
+        h
+    };
+
+    let registered = {
+        let mut h = history();
+        h.register(
+            Member::new("layout")
+                .with_drift_scale(0.0)
+                .with_prior(PINNED),
+        )
+        .unwrap();
+        h.add_events(vec![
+            duel("player", "layout", 1, None),
+            duel("player", "layout", 2, None),
+        ])
+        .unwrap();
+        let _ = h.converge().unwrap();
+        h
+    };
+
+    for ((k, a), (_, b)) in skills(&configured).into_iter().zip(skills(&registered)) {
+        assert_eq!(a.pi(), b.pi(), "{k} pi");
+        assert_eq!(a.tau(), b.tau(), "{k} tau");
+    }
+}
+
+/// The case `EventBuilder` and the typed path cannot reach: a competitor whose
+/// first appearance arrives through the two-argument convenience route.
+#[test]
+fn registration_reaches_a_competitor_first_seen_through_record_winner() {
+    let mut h = history();
+    h.register(
+        Member::new("layout")
+            .with_drift_scale(0.0)
+            .with_prior(PINNED),
+    )
+    .unwrap();
+    h.record_winner(&"player", &"layout", 1).unwrap();
+    h.record_winner(&"player", &"layout", 2).unwrap();
+    let _ = h.converge().unwrap();
+
+    let rating = h.rating(&"layout").unwrap();
+    assert_eq!(rating.drift_scale(), 0.0);
+    assert_eq!(rating.prior().mu(), PINNED.mu());
+
+    // Pinned means pinned: no drift across the two slices.
+    let curve = h.learning_curve(&"layout");
+    assert!(curve.len() >= 2);
+    let widest = curve
+        .iter()
+        .map(|(_, g)| g.sigma())
+        .fold(f64::MIN, f64::max);
+    let narrowest = curve
+        .iter()
+        .map(|(_, g)| g.sigma())
+        .fold(f64::MAX, f64::min);
+    assert!(
+        (widest - narrowest) / widest < 1e-9,
+        "{narrowest} .. {widest}"
+    );
+}
+
+#[test]
+fn registering_a_known_competitor_is_an_error() {
+    let mut h = history();
+    h.record_winner(&"player", &"layout", 1).unwrap();
+    let err = h.register(Member::new("layout")).unwrap_err();
+    assert!(
+        matches!(err, InferenceError::AlreadyRegistered { .. }),
+        "{err:?}"
+    );
+}
+
+#[test]
+fn registering_twice_is_an_error() {
+    let mut h = history();
+    h.register(Member::new("layout").with_drift_scale(0.0))
+        .unwrap();
+    let err = h
+        .register(Member::new("layout").with_drift_scale(1.0))
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::AlreadyRegistered { .. }),
+        "{err:?}"
+    );
+    // The first registration stands.
+    assert_eq!(h.rating(&"layout").unwrap().drift_scale(), 0.0);
+}
+
+/// `weight` is per-event and meaningless here, so it is rejected rather than
+/// dropped — dropping it silently is the defect class this whole area keeps
+/// producing.
+#[test]
+fn a_weight_on_a_registration_is_rejected() {
+    let mut h = history();
+    let err = h
+        .register(Member::new("layout").with_weight(0.5))
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::InvalidParameter { name: "weight", .. }),
+        "{err:?}"
+    );
+}
+
+#[test]
+fn an_invalid_drift_scale_on_a_registration_is_rejected() {
+    for bad in [-1.0, f64::NAN, f64::INFINITY] {
+        let mut h = history();
+        let err = h
+            .register(Member::new("layout").with_drift_scale(bad))
+            .unwrap_err();
+        assert!(
+            matches!(
+                err,
+                InferenceError::InvalidParameter {
+                    name: "drift_scale",
+                    ..
+                }
+            ),
+            "{bad}: {err:?}"
+        );
+    }
+}
+
+/// Registration makes the fit independent of the order events arrive in,
+/// which is what the per-event shape could not guarantee.
+#[test]
+fn registration_makes_the_fit_order_independent() {
+    let build = |reversed: bool| {
+        let mut h = history();
+        h.register(
+            Member::new("layout")
+                .with_drift_scale(0.0)
+                .with_prior(PINNED),
+        )
+        .unwrap();
+        let mut events = vec![
+            duel("player", "layout", 1, None),
+            duel("player", "layout", 2, None),
+            duel("player", "layout", 3, None),
+        ];
+        if reversed {
+            events.reverse();
+        }
+        h.add_events(events).unwrap();
+        let _ = h.converge().unwrap();
+        h
+    };
+
+    let forward = build(false);
+    let backward = build(true);
+    for ((k, a), (_, b)) in skills(&forward).into_iter().zip(skills(&backward)) {
+        assert_eq!(a.pi(), b.pi(), "{k} pi");
+        assert_eq!(a.tau(), b.tau(), "{k} tau");
+    }
+}
+
+/// `rating` is the read-back that made a configuration mistake detectable from
+/// outside the crate at all. Every other accessor reports what inference
+/// inferred; this reports what it was told.
+#[test]
+fn rating_reads_back_what_was_stored() {
+    let mut h = history();
+    assert!(h.rating(&"nobody").is_none());
+
+    h.register(
+        Member::new("layout")
+            .with_drift_scale(0.25)
+            .with_prior(PINNED),
+    )
+    .unwrap();
+    let r = h.rating(&"layout").unwrap();
+    assert_eq!(r.drift_scale(), 0.25);
+    assert_eq!(r.prior().pi(), PINNED.pi());
+    assert_eq!(r.prior().tau(), PINNED.tau());
+
+    // A competitor created by an event reports the history defaults.
+    h.record_winner(&"player", &"layout", 1).unwrap();
+    assert_eq!(h.rating(&"player").unwrap().drift_scale(), 1.0);
+}
+
+/// The decision this issue turned on: two different values for one competitor
+/// are an error whether they arrive in one batch or two.
+///
+/// Last-write-wins across batches cut against the invariant
+/// `tests/ingestion_equivalence.rs` protects — the same contradictory events
+/// errored when batched and succeeded, order-dependently, one at a time.
+mod conflicting_configuration {
+    use super::*;
+
+    fn seed(scale: f64) -> Event<i64, &'static str> {
+        duel(
+            "player",
+            "layout",
+            1,
+            Some(Member::new("layout").with_drift_scale(scale)),
+        )
+    }
+
+    #[test]
+    fn within_one_batch_is_an_error() {
+        let mut h = history();
+        let err = h.add_events(vec![seed(0.0), seed(1.0)]).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                InferenceError::ConflictingCompetitorConfig {
+                    field: "drift_scale",
+                    ..
+                }
+            ),
+            "{err:?}"
+        );
+    }
+
+    #[test]
+    fn across_two_batches_is_also_an_error() {
+        let mut h = history();
+        h.add_events(vec![seed(0.0)]).unwrap();
+        let err = h.add_events(vec![seed(1.0)]).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                InferenceError::ConflictingCompetitorConfig {
+                    field: "drift_scale",
+                    ..
+                }
+            ),
+            "{err:?}"
+        );
+        // Rejected before anything mutates: the first declaration stands.
+        assert_eq!(h.rating(&"layout").unwrap().drift_scale(), 0.0);
+    }
+
+    /// Repeating the *same* value stays inert, which is the expected shape
+    /// when the configuration is a property of the domain.
+    #[test]
+    fn repeating_the_same_value_is_inert() {
+        let mut h = history();
+        h.add_events(vec![seed(0.0)]).unwrap();
+        h.add_events(vec![seed(0.0)]).unwrap();
+        assert_eq!(h.rating(&"layout").unwrap().drift_scale(), 0.0);
+    }
+
+    /// A registration and a later event that agree are fine; one that
+    /// disagrees is the same error.
+    #[test]
+    fn a_registration_conflicts_with_a_later_event() {
+        let mut h = history();
+        h.register(Member::new("layout").with_drift_scale(0.0))
+            .unwrap();
+        h.add_events(vec![seed(0.0)]).unwrap();
+
+        let mut h2 = history();
+        h2.register(Member::new("layout").with_drift_scale(0.0))
+            .unwrap();
+        let err = h2.add_events(vec![seed(1.0)]).unwrap_err();
+        assert!(
+            matches!(err, InferenceError::ConflictingCompetitorConfig { .. }),
+            "{err:?}"
+        );
+    }
+}

tests/validation.rs

@@ -184,3 +184,74 @@ fn ingestion_rejects_weights_that_do_not_match_their_team() {
         "got {err:?}"
     );
 }
+
+/// `mu`, `sigma` and `beta` were the last unvalidated setters on
+/// `HistoryBuilder`, next to `p_draw`, `score_sigma` and `convergence`, which
+/// all assert eagerly.
+///
+/// Two of the rejected values are the quiet kind. A negative `sigma` or `beta`
+/// enters inference only as its square, so it produced bit-identical results
+/// to the positive value — the sign was dropped without comment.
+mod builder_parameters {
+    use trueskill_tt::History;
+
+    #[test]
+    #[should_panic(expected = "mu must be finite")]
+    fn a_non_finite_mu_is_rejected() {
+        let _ = History::builder().mu(f64::NAN);
+    }
+
+    #[test]
+    #[should_panic(expected = "sigma must be finite and positive")]
+    fn a_zero_sigma_is_rejected() {
+        let _ = History::builder().sigma(0.0);
+    }
+
+    #[test]
+    #[should_panic(expected = "sigma must be finite and positive")]
+    fn a_negative_sigma_is_rejected() {
+        let _ = History::builder().sigma(-8.33);
+    }
+
+    #[test]
+    #[should_panic(expected = "sigma must be finite and positive")]
+    fn an_infinite_sigma_is_rejected() {
+        let _ = History::builder().sigma(f64::INFINITY);
+    }
+
+    #[test]
+    #[should_panic(expected = "beta must be finite and non-negative")]
+    fn a_negative_beta_is_rejected() {
+        let _ = History::builder().beta(-4.17);
+    }
+
+    #[test]
+    #[should_panic(expected = "beta must be finite and non-negative")]
+    fn a_non_finite_beta_is_rejected() {
+        let _ = History::builder().beta(f64::NAN);
+    }
+
+    /// Zero beta is deliberately allowed: performance is then exactly skill.
+    /// It has to reach a different fit than a positive beta, or "allowed"
+    /// would just mean "not checked".
+    #[test]
+    fn a_zero_beta_is_allowed_and_changes_the_fit() {
+        let fit = |beta: f64| {
+            let mut h = History::builder()
+                .mu(25.0)
+                .sigma(25.0 / 3.0)
+                .beta(beta)
+                .build();
+            h.record_winner(&"a", &"b", 1).unwrap();
+            let _ = h.converge().unwrap();
+            h.current_skill(&"a").unwrap()
+        };
+        let zero = fit(0.0);
+        let positive = fit(25.0 / 6.0);
+        assert!(zero.pi().is_finite() && zero.pi() > 0.0);
+        assert!(
+            (zero.pi() - positive.pi()).abs() > 1e-6,
+            "zero beta must not merely be ignored: {zero:?} vs {positive:?}"
+        );
+    }
+}