Merge branch 'test/close-coverage-gaps'

Cover non-finite results and color-group disjointness, closing the two
test gaps #26 named.

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

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.7.0 - 2026-09-08
+
+### Features
+
+- feat: factorise the joint once with History::joint
+
+### Other (unconventional)
+
+- Merge branch 'feat/joint-handle'
+
+## 0.6.0 - 2026-09-08
+
+### Breaking Changes
+
+- fix!: make the joint span slices, not just the latest one
+
+### Miscellaneous Tasks
+
+- chore: Release trueskill-tt version 0.6.0
+
 ## 0.5.0 - 2026-09-08
 
 ### Breaking Changes
@@ -24,6 +44,10 @@ All notable changes to this project will be documented in this file.
 - feat: add History::predict_margin for scored matchups
 - feat: add expected_variance_reduction for scored active learning
 
+### Miscellaneous Tasks
+
+- chore: Release trueskill-tt version 0.5.0
+
 ### Styling
 
 - style: factor the event-pair type out of the reconvergence fixture

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trueskill-tt"
-version = "0.5.0"
+version = "0.7.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"
@@ -79,3 +79,7 @@ debug = true
 
 [profile.dev]
 debug = true
+
+[[bench]]
+name = "joint"
+harness = false

README.md

@@ -134,14 +134,20 @@ h.add_events(vec![Event {
 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`.
+Like `with_prior`, the scale is **competitor configuration, not a per-event
+value**: it applies to the competitor for the whole history, and it applies
+whenever it is supplied — including on a key the history already knows.
+Configuring one late still refits the whole history rather than taking effect
+only from that event onward, because `converge` refits from competitor state.
+Repeating the same value is inert; supplying two *different* values for one
+competitor within a single batch is `InferenceError::ConflictingCompetitorConfig`,
+since events in a batch have no order. The scale 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.
+The fluent `EventBuilder` reaches this too: `.team([...])` is the common case
+and leaves both unset, while `.members([...])` takes `Member` values directly,
+so `h.event(t).members([Member::new("layout_7").with_drift_scale(0.0)])` is
+equivalent to the typed shape above.
 
 ## Scored outcomes
 

benches/joint.rs

@@ -0,0 +1,71 @@
+//! Cost of the joint posterior: factorising versus querying.
+//!
+//! The split is the whole point of `History::joint`. Factorising is `O(n^3)` in
+//! the history's appearances and depends only on the fit; a query is `O(n^2)`
+//! and depends only on the question. `posterior_of_one_shot` pays both every
+//! time, `joint_query` pays only the second.
+
+use criterion::{Criterion, criterion_group, criterion_main};
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, ConvergenceOptions, Event, History, Member, Outcome, Team};
+
+/// 30 slices of 8 duels: 480 appearances over 100 competitors.
+fn fitted() -> History<i64, ConstantDrift, trueskill_tt::NullObserver, String> {
+    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))
+        .convergence(ConvergenceOptions {
+            max_iter: 30,
+            epsilon: 1e-10,
+            alpha: 1.0,
+        })
+        .build();
+
+    let mut events: Vec<Event<i64, String>> = Vec::new();
+    let mut k = 0usize;
+    for t in 0..30i64 {
+        for _ in 0..8 {
+            k += 1;
+            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([
+                    (k as f64 * 0.3).sin().abs() * 20.0,
+                    (k as f64 * 0.3).cos().abs() * 20.0,
+                ]),
+            });
+        }
+    }
+    h.add_events(events).unwrap();
+    let _ = h.converge().unwrap();
+    h
+}
+
+fn bench_joint(c: &mut Criterion) {
+    let h = fitted();
+    let a = "p0".to_string();
+    let b = "p1".to_string();
+    let terms = [(&a, 1.0), (&b, -1.0)];
+
+    c.bench_function("joint_factorise_480_appearances", |bencher| {
+        bencher.iter(|| std::hint::black_box(h.joint().unwrap().variables()));
+    });
+
+    c.bench_function("posterior_of_one_shot_480_appearances", |bencher| {
+        bencher.iter(|| std::hint::black_box(h.posterior_of(&terms).unwrap()));
+    });
+
+    let joint = h.joint().unwrap();
+    c.bench_function("joint_query_480_appearances", |bencher| {
+        bencher.iter(|| std::hint::black_box(joint.posterior_of(&terms).unwrap()));
+    });
+}
+
+criterion_group!(benches, bench_joint);
+criterion_main!(benches);

docs/superpowers/specs/2026-04-23-trueskill-engine-redesign-design.md

@@ -500,6 +500,26 @@ All public traits (`Time`, `Drift`, `Observer`, `Factor`, `Schedule`) require `S
 
 `rayon` as default-on feature; with `default-features = false`, parallel paths fall back to sequential iterators behind `cfg(feature = "rayon")`.
 
+> **Not implemented. Deliberate deviation, decided 2026-09-08 (issue #5).**
+>
+> `rayon` ships **opt-in**: `Cargo.toml` has no `default = [...]` key. The
+> measured speedups are 1.0x on realistic workloads and 1.3x on a pathological
+> one (issue #4), because typical slices hold too few events to amortize
+> rayon's task-spawn overhead. Default-on would hand every downstream user a
+> thread pool and a dependency for approximately no gain.
+>
+> This section made the trade conditional on cross-slice dirty-bit skipping
+> landing and changing the parallel story. It did not land: #4 was closed on
+> 2026-08-27 by removing the inert `ConvergenceReport::slices_skipped` field
+> rather than by implementing the mechanism, so the re-measurement this was
+> waiting on will not arrive.
+>
+> The "Trade-offs" note below also cited an `unsafe` concurrent-write path
+> through `SkillStore` as a cost of default-on. That cost does not exist: the
+> crate is `#![forbid(unsafe_code)]`, and the compute/apply split on the
+> internal `Event` is what lets a color group run in parallel without it. The
+> case for opt-in rests on the measurements alone.
+
 ### Expected speedup ballpark
 
 For 1000 players, 60 events/slice × 1000 slices, 30 convergence iterations:
@@ -521,7 +541,7 @@ These are pre-implementation estimates. Each tier validates with criterion.
 - Color-group parallelism requires up-front graph coloring at ingestion. Cost: linear in events, run once per `add_events`. Cheap.
 - Default = asynchronous EP (preserves current semantics). Synchronous opt-in only.
 - Cross-slice sweep stays sequential; no speculative parallel sweeps.
-- Rayon default-on but feature-gated.
+- Rayon default-on but feature-gated. **Superseded — shipped opt-in; see the deviation note in Section 6.**
 
 ### Open question
 

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/event.rs

@@ -88,7 +88,9 @@ impl<K> Member<K> {
 
     /// Set this competitor's starting skill estimate.
     ///
-    /// Captured at the competitor's first appearance; see the type docs.
+    /// Competitor configuration, not a per-event value: it applies for the
+    /// whole history and applies whenever it is supplied, including on a key
+    /// the history already knows. See the type docs.
     pub fn with_prior(mut self, prior: Gaussian) -> Self {
         self.prior = Some(prior);
         self
@@ -104,7 +106,8 @@ impl<K> Member<K> {
     /// 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.
+    /// Applies for the whole history and whenever it is supplied, including on
+    /// a key the history already knows; 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 {

src/event_builder.rs

@@ -50,6 +50,8 @@ where
     }
 
     /// Add a team by its member keys (weight 1.0 each, no prior overrides).
+    ///
+    /// Use [`EventBuilder::members`] to set `prior` or `drift_scale`.
     pub fn team<I: IntoIterator<Item = K>>(mut self, keys: I) -> Self {
         let members: SmallVec<[Member<K>; 4]> = keys.into_iter().map(Member::new).collect();
         self.event.teams.push(Team { members });
@@ -57,6 +59,40 @@ where
         self
     }
 
+    /// Add a team from fully-specified [`Member`] values.
+    ///
+    /// [`EventBuilder::team`] is the common case and builds members with
+    /// `Member::new`, which leaves `prior` and `drift_scale` unset. This is the
+    /// escape hatch for when they matter:
+    ///
+    /// ```
+    /// # use trueskill_tt::{Gaussian, History, Member};
+    /// # let mut h = History::builder().build();
+    /// h.event(0)
+    ///     .team(["player"])
+    ///     .members([Member::new("layout_7")
+    ///         .with_drift_scale(0.0)
+    ///         .with_prior(Gaussian::from_ms(0.0, 1.0))])
+    ///     .ranking([0, 1])
+    ///     .commit()?;
+    /// # Ok::<(), trueskill_tt::InferenceError>(())
+    /// ```
+    ///
+    /// One method rather than a `priors` and a `drift_scales` setter beside
+    /// `weights`: those would have to grow a parallel array — and a parallel
+    /// length check — every time `Member` gains a field, and each one would be
+    /// a new way to get the lengths wrong. `Member`'s own builder already
+    /// expresses all of it.
+    ///
+    /// `prior` and `drift_scale` are competitor configuration rather than
+    /// per-event values; see [`Member`] for what that means for a key the
+    /// history already knows.
+    pub fn members<I: IntoIterator<Item = Member<K>>>(mut self, members: I) -> Self {
+        self.event.teams.push(Team::with_members(members));
+        self.current_team_idx = Some(self.event.teams.len() - 1);
+        self
+    }
+
     /// Set per-member weights for the most recently added team.
     ///
     /// A length mismatch is recorded and returned by [`EventBuilder::commit`]

src/joint.rs

@@ -1,99 +1,152 @@
-//! Posterior of a linear combination of competitors.
+//! Cholesky factorisation of a joint precision matrix.
 //!
-//! Every accessor on `History` returns a per-competitor marginal, and almost
-//! nothing a consumer publishes is one competitor: "can we tell these two
-//! apart" is a difference, "what was this round worth" is a sum. Combining
-//! marginals means assuming the competitors are independent, and they are
-//! correlated through every event they share — which is the mechanism the model
-//! exists to exploit.
+//! Every question the joint answers is a *bilinear form* in the precision
+//! matrix's inverse — the variance of a contrast is `c^T L^-1 c`, and the
+//! covariance of two contrasts is `c^T L^-1 a`. None of them wants `L^-1 c`
+//! itself, which is what makes the shape here worth stating explicitly.
 //!
-//! Measured on a five-competitor round robin, the exact correlation is +0.857,
-//! so `sqrt(sa^2 + sb^2)` overstates the width of a difference by 2.6x.
+//! Writing the precision as `A = L L^T`,
+//!
+//! ```text
+//! c^T A^-1 a = c^T L^-T L^-1 a = (L^-1 c) . (L^-1 a)
+//! ```
+//!
+//! so a single forward substitution per contrast answers everything, and the
+//! back substitution a general solve would do is wasted work. That halves the
+//! cost of a query, and it removes a failure mode: a variance computed as
+//! `c . (A^-1 c)` is a difference of products that can round to a small
+//! negative number, where the same quantity as `|L^-1 c|^2` is a sum of
+//! squares and cannot.
+//!
+//! Factorising is `O(n^3)` and whitening is `O(n^2)`, so the split also
+//! matters structurally: the expensive half depends only on the fit, and is
+//! shared across every query a [`Joint`](crate::Joint) answers.
 
-/// Solve `A z = b` for a symmetric positive-definite `A`, by Cholesky.
-///
-/// `a` is row-major and is consumed as scratch.
-///
-/// Returns `None` if the matrix is not positive-definite, which for a precision
-/// matrix means the model is improper — a competitor with no prior and no
-/// evidence.
-pub(crate) fn solve_spd(mut a: Vec<f64>, b: &[f64]) -> Option<Vec<f64>> {
-    let n = b.len();
-    debug_assert_eq!(a.len(), n * n);
+/// A factorised symmetric positive-definite matrix, reusable across queries.
+pub(crate) struct Cholesky {
+    /// Lower triangle of `L`, row-major `n * n`. The upper triangle is
+    /// leftover scratch from the factorisation and is never read.
+    l: Vec<f64>,
+    n: usize,
+}
 
-    // In-place Cholesky: A = L L^T, lower triangle.
-    for j in 0..n {
-        let mut d = a[j * n + j];
-        for k in 0..j {
-            d -= a[j * n + k] * a[j * n + k];
-        }
-        // Explicit rather than `!(d > 0.0)`: a NaN pivot must fail here too,
-        // and a negated comparison would let it through as "not positive".
-        if d.is_nan() || d <= 0.0 {
-            return None;
-        }
-        let d = d.sqrt();
-        a[j * n + j] = d;
+impl Cholesky {
+    /// Factorise `a` (row-major, `n * n`, symmetric) into `L L^T`.
+    ///
+    /// `a` is consumed as scratch.
+    ///
+    /// Returns `None` if the matrix is not positive-definite, which for a
+    /// precision matrix means the model is improper — a competitor with
+    /// neither a proper prior nor any evidence.
+    pub(crate) fn factor(mut a: Vec<f64>, n: usize) -> Option<Self> {
+        debug_assert_eq!(a.len(), n * n);
 
-        for i in j + 1..n {
-            let mut s = a[i * n + j];
+        for j in 0..n {
+            let mut d = a[j * n + j];
             for k in 0..j {
-                s -= a[i * n + k] * a[j * n + k];
+                d -= a[j * n + k] * a[j * n + k];
+            }
+            // Explicit rather than `!(d > 0.0)`: a NaN pivot must fail here
+            // too, and a negated comparison would let it through as "not
+            // positive".
+            if d.is_nan() || d <= 0.0 {
+                return None;
+            }
+            let d = d.sqrt();
+            a[j * n + j] = d;
+
+            for i in j + 1..n {
+                let mut s = a[i * n + j];
+                for k in 0..j {
+                    s -= a[i * n + k] * a[j * n + k];
+                }
+                a[i * n + j] = s / d;
             }
-            a[i * n + j] = s / d;
         }
+
+        Some(Self { l: a, n })
     }
 
-    // Forward substitution, then back substitution.
-    let mut z = b.to_vec();
-    for i in 0..n {
-        let mut s = z[i];
-        for k in 0..i {
-            s -= a[i * n + k] * z[k];
+    /// Whiten a contrast: `y = L^-1 b`.
+    ///
+    /// The point of the result is the dot product, not the vector: for two
+    /// contrasts `b` and `b'`, `y . y'` is `b^T A^-1 b'`. See the module docs.
+    pub(crate) fn whiten(&self, b: &[f64]) -> Vec<f64> {
+        debug_assert_eq!(b.len(), self.n);
+        let n = self.n;
+        let mut y = b.to_vec();
+        for i in 0..n {
+            // Folded from `y[i]` rather than summed and subtracted once, so the
+            // accumulation order matches a plain substitution loop exactly.
+            let row = &self.l[i * n..i * n + i];
+            let s = row
+                .iter()
+                .zip(&y[..i])
+                .fold(y[i], |acc, (l, v)| acc - l * v);
+            y[i] = s / self.l[i * n + i];
         }
-        z[i] = s / a[i * n + i];
-    }
-    for i in (0..n).rev() {
-        let mut s = z[i];
-        for k in i + 1..n {
-            s -= a[k * n + i] * z[k];
-        }
-        z[i] = s / a[i * n + i];
+        y
     }
+}
 
-    Some(z)
+/// `b^T A^-1 b'`, given the two whitened contrasts.
+pub(crate) fn bilinear(y: &[f64], y_prime: &[f64]) -> f64 {
+    y.iter().zip(y_prime).map(|(a, b)| a * b).sum()
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    /// `[[4, 1], [1, 3]] z = [1, 2]` has `z = [1/11, 7/11]`, so the quadratic
+    /// form `b^T A^-1 b` is `1 * 1/11 + 2 * 7/11 = 15/11`.
     #[test]
-    fn solves_a_known_system() {
-        // [[4, 1], [1, 3]] z = [1, 2]  =>  z = [1/11, 7/11]
-        let a = vec![4.0, 1.0, 1.0, 3.0];
-        let z = solve_spd(a, &[1.0, 2.0]).unwrap();
-        assert!((z[0] - 1.0 / 11.0).abs() < 1e-12, "{z:?}");
-        assert!((z[1] - 7.0 / 11.0).abs() < 1e-12, "{z:?}");
+    fn reproduces_a_known_quadratic_form() {
+        let c = Cholesky::factor(vec![4.0, 1.0, 1.0, 3.0], 2).unwrap();
+        let y = c.whiten(&[1.0, 2.0]);
+        assert!((bilinear(&y, &y) - 15.0 / 11.0).abs() < 1e-12);
     }
 
+    /// Whitening `e_i` recovers the inverse's diagonal, which is the variance
+    /// of a single variable.
     #[test]
     fn recovers_the_inverse_diagonal() {
         // A = [[2, -1, 0], [-1, 2, -1], [0, -1, 2]]; inverse diagonal is
         // [0.75, 1.0, 0.75].
         let a = vec![2.0, -1.0, 0.0, -1.0, 2.0, -1.0, 0.0, -1.0, 2.0];
+        let c = Cholesky::factor(a, 3).unwrap();
         for (i, expected) in [0.75, 1.0, 0.75].into_iter().enumerate() {
             let mut e = vec![0.0; 3];
             e[i] = 1.0;
-            let z = solve_spd(a.clone(), &e).unwrap();
-            assert!((z[i] - expected).abs() < 1e-12, "row {i}: {z:?}");
+            let y = c.whiten(&e);
+            assert!((bilinear(&y, &y) - expected).abs() < 1e-12, "row {i}");
         }
     }
 
+    /// The off-diagonal bilinear form is symmetric and matches the inverse.
+    #[test]
+    fn recovers_an_off_diagonal_covariance() {
+        // Same A; (A^-1)_{0,1} = 0.5.
+        let a = vec![2.0, -1.0, 0.0, -1.0, 2.0, -1.0, 0.0, -1.0, 2.0];
+        let c = Cholesky::factor(a, 3).unwrap();
+        let y0 = c.whiten(&[1.0, 0.0, 0.0]);
+        let y1 = c.whiten(&[0.0, 1.0, 0.0]);
+        assert!((bilinear(&y0, &y1) - 0.5).abs() < 1e-12);
+        assert!((bilinear(&y1, &y0) - 0.5).abs() < 1e-12);
+    }
+
+    /// A variance can never come out negative, because it is a sum of squares.
+    #[test]
+    fn a_quadratic_form_is_never_negative() {
+        let a = vec![1e12, 1e12 - 1.0, 1e12 - 1.0, 1e12];
+        let c = Cholesky::factor(a, 2).unwrap();
+        let y = c.whiten(&[1.0, -1.0]);
+        assert!(bilinear(&y, &y) >= 0.0);
+    }
+
     #[test]
     fn rejects_a_non_positive_definite_matrix() {
         // Singular: the second row is a multiple of the first.
-        let a = vec![1.0, 2.0, 2.0, 4.0];
-        assert!(solve_spd(a, &[1.0, 1.0]).is_none());
+        assert!(Cholesky::factor(vec![1.0, 2.0, 2.0, 4.0], 2).is_none());
     }
 }

src/lib.rs

@@ -141,7 +141,7 @@ pub use event::{Event, Member, Team};
 pub use event_builder::EventBuilder;
 pub use game::{Game, GameOptions, OwnedGame};
 pub use gaussian::Gaussian;
-pub use history::{History, HistoryBuilder};
+pub use history::{History, HistoryBuilder, Joint};
 pub use key_table::KeyTable;
 use matrix::Matrix;
 pub use observer::{NullObserver, Observer};
@@ -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.
 ///

src/time_slice.rs

@@ -810,40 +810,26 @@ pub(crate) fn compute_elapsed<T: Time>(last: Option<&T>, current: &T) -> i64 {
 }
 
 impl<T: Time> TimeSlice<T> {
-    /// Precision matrix of the joint posterior over this slice's competitors.
+    /// This slice's scored event factors, as contrasts over competitors.
     ///
     /// Message passing produces per-competitor marginals and throws the
     /// correlation away — `Item::likelihood` is already the projection of an
-    /// event's factor down onto one competitor. So the joint has to be rebuilt
-    /// from the factor structure rather than recovered from the messages.
+    /// event's factor onto one competitor. So a joint has to be rebuilt from
+    /// the factor structure rather than recovered from the messages.
     ///
     /// Usefully, a precision matrix depends only on *structure* — who played
     /// whom, with what weights and what observation noise — and not on the
-    /// observed outcomes. The means are already exact (Gaussian belief
-    /// propagation gets those right even with cycles), so only the second
+    /// observed outcomes. The means are already exact, so only the second
     /// moment needs rebuilding.
     ///
-    /// Returns the competitor order and the dense matrix in row-major order.
-    /// Only scored events contribute their factors exactly; see the caller.
-    pub(crate) fn joint_precision<D: Drift<T>>(
+    /// Each entry is a contrast and the observation variance that sits on it.
+    /// Ranked events contribute nothing: their truncation factors are EP
+    /// approximations that inference does not retain.
+    pub(crate) fn scored_contrasts<D: Drift<T>>(
         &self,
         agents: &CompetitorStore<T, D>,
-    ) -> (Vec<Index>, Vec<f64>) {
-        let order: Vec<Index> = self.skills.keys().collect();
-        let n = order.len();
-        let mut row_of: HashMap<Index, usize> = HashMap::with_capacity(n);
-        for (r, idx) in order.iter().enumerate() {
-            row_of.insert(*idx, r);
-        }
-
-        let mut lambda = vec![0.0; n * n];
-
-        // Everything outside this slice enters as each competitor's forward and
-        // backward messages, which message passing treats as independent.
-        for (r, idx) in order.iter().enumerate() {
-            let skill = self.skills.get(*idx).expect("slice key has a skill");
-            lambda[r * n + r] += (skill.forward * skill.backward).pi();
-        }
+    ) -> Vec<(Vec<(Index, f64)>, f64)> {
+        let mut out = Vec::new();
 
         for event in &self.events {
             let EventKind::Scored { score_sigma } = event.kind else {
@@ -851,49 +837,48 @@ impl<T: Time> TimeSlice<T> {
             };
 
             // Teams best-first, matching the diff chain inference builds.
-            let mut order_idx: Vec<usize> = (0..event.teams.len()).collect();
-            order_idx.sort_by(|&a, &b| {
+            let mut order: Vec<usize> = (0..event.teams.len()).collect();
+            order.sort_by(|&a, &b| {
                 event.teams[b]
                     .output
                     .partial_cmp(&event.teams[a].output)
                     .unwrap_or(std::cmp::Ordering::Equal)
             });
 
-            for pair in order_idx.windows(2) {
+            for pair in order.windows(2) {
                 let (hi, lo) = (pair[0], pair[1]);
-
-                // Contrast vector, and the observation noise that sits on top
-                // of the skills: per-member performance noise plus the score
-                // noise itself.
-                let mut contrast: HashMap<usize, f64> = HashMap::new();
+                let mut contrast: Vec<(Index, f64)> = Vec::new();
                 let mut noise = score_sigma * score_sigma;
 
                 for (team, sign) in [(hi, 1.0), (lo, -1.0)] {
                     for (m, item) in event.teams[team].items.iter().enumerate() {
                         let w = event.weights[team][m];
-                        let beta = agents[item.agent].rating.beta;
-                        noise += w * w * beta * beta;
-                        *contrast.entry(row_of[&item.agent]).or_insert(0.0) += sign * w;
+                        noise += w * w * agents[item.agent].rating.beta.powi(2);
+                        contrast.push((item.agent, sign * w));
                     }
                 }
 
-                for (&i, &ci) in &contrast {
-                    for (&j, &cj) in &contrast {
-                        lambda[i * n + j] += ci * cj / noise;
-                    }
-                }
+                out.push((contrast, noise));
             }
         }
 
-        (order, lambda)
+        out
     }
 
-    /// True when every event here is scored, so `joint_precision` is exact.
+    /// True when every event here is scored, so the joint is exact.
     pub(crate) fn all_scored(&self) -> bool {
         self.events
             .iter()
             .all(|e| matches!(e.kind, EventKind::Scored { .. }))
     }
+
+    /// The competitors appearing in this slice, with the elapsed count since
+    /// each one's previous appearance.
+    pub(crate) fn appearances(&self) -> impl Iterator<Item = (Index, i64)> + '_ {
+        self.skills
+            .keys()
+            .map(|idx| (idx, self.skills.get(idx).expect("slice key").elapsed))
+    }
 }
 
 #[cfg(test)]

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/degenerate_inputs.rs

@@ -170,8 +170,9 @@ fn event_builder_rejects_a_weights_length_mismatch() {
 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.
+    // Two teams, so ingestion would otherwise succeed. A one-team event is
+    // rejected as `NotEnoughTeams` before the weights are ever examined, so
+    // building this with one team would pass vacuously.
     let _ = h
         .event(1)
         .team(["a"])

tests/event_builder_members.rs

@@ -0,0 +1,193 @@
+//! `EventBuilder::members` must reach exactly what the typed path reaches.
+//!
+//! Before this existed, `EventBuilder` could set weights and nothing else, so
+//! `prior` and `drift_scale` were expressible only through `Event`/`Team`/
+//! `Member` + `add_events`. Which ingestion route a competitor arrived through
+//! decided whether it could be configured 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>;
+
+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()
+}
+
+const PRIOR: Gaussian = Gaussian::from_ms(3.0, 1.5);
+
+/// The contract that makes the escape hatch worth having: same configuration,
+/// same fit, bit for bit.
+#[test]
+fn members_matches_the_typed_path_exactly() {
+    let mut typed = history();
+    typed
+        .add_events(vec![Event {
+            time: 1,
+            teams: smallvec![
+                Team::with_members([Member::new("player")]),
+                Team::with_members([Member::new("layout_7")
+                    .with_drift_scale(0.0)
+                    .with_prior(PRIOR)]),
+            ],
+            outcome: Outcome::scores([5.0, 2.0]),
+        }])
+        .unwrap();
+    assert!(typed.converge().unwrap().converged);
+
+    let mut fluent = history();
+    fluent
+        .event(1)
+        .team(["player"])
+        .members([Member::new("layout_7")
+            .with_drift_scale(0.0)
+            .with_prior(PRIOR)])
+        .scores([5.0, 2.0])
+        .commit()
+        .unwrap();
+    assert!(fluent.converge().unwrap().converged);
+
+    for key in ["player", "layout_7"] {
+        let a = typed.current_skill(&key).unwrap();
+        let b = fluent.current_skill(&key).unwrap();
+        assert_eq!(a.pi(), b.pi(), "{key} pi");
+        assert_eq!(a.tau(), b.tau(), "{key} tau");
+    }
+}
+
+/// The configuration has to actually take effect, not merely round-trip: a
+/// competitor pinned with `drift_scale = 0.0` must not move across slices,
+/// where an unpinned one does.
+///
+/// The comparison is against a control rather than against a fixed epsilon.
+/// Pinned marginals are not bit-identical across slices — each slice combines
+/// its own forward and backward messages, so the arithmetic order differs and
+/// the last bit moves. What "pinned" promises is that no drift variance
+/// accumulates, and the control is what makes that measurable.
+#[test]
+fn a_drift_scale_set_through_members_is_applied() {
+    fn spread(h: &H, key: &'static str) -> f64 {
+        let curve = h.learning_curve(&key);
+        assert!(curve.len() >= 2, "{key}: expected several appearances");
+        let (lo, hi) = curve.iter().fold((f64::MAX, f64::MIN), |(lo, hi), (_, g)| {
+            (lo.min(g.sigma()), hi.max(g.sigma()))
+        });
+        (hi - lo) / hi
+    }
+
+    let mut h = history();
+    for t in 1..=4 {
+        h.event(t)
+            .team(["player"])
+            .members([Member::new("pinned").with_drift_scale(0.0)])
+            .scores([5.0, 2.0])
+            .commit()
+            .unwrap();
+        // Same shape, no pinning: the control.
+        h.event(t)
+            .team(["rival"])
+            .team(["drifting"])
+            .scores([5.0, 2.0])
+            .commit()
+            .unwrap();
+    }
+    assert!(h.converge().unwrap().converged);
+
+    let pinned = spread(&h, "pinned");
+    let drifting = spread(&h, "drifting");
+    assert!(pinned < 1e-9, "pinned competitor moved: {pinned:e}");
+    assert!(
+        drifting > 1e-3,
+        "control did not move, so the test proves nothing: {drifting:e}"
+    );
+}
+
+/// `weights` still applies to a team added through `members`, and still
+/// records a mismatch rather than partially applying it.
+#[test]
+fn weights_still_guards_a_members_team() {
+    let mut h = history();
+    let err = h
+        .event(1)
+        .team(["a"])
+        .members([Member::new("b"), Member::new("c")])
+        .weights([1.0])
+        .winner(0)
+        .commit()
+        .unwrap_err();
+    assert!(
+        matches!(
+            err,
+            InferenceError::MismatchedShape {
+                kind: "weights",
+                expected: 2,
+                got: 1
+            }
+        ),
+        "{err:?}"
+    );
+    assert!(h.current_skill(&"b").is_none(), "nothing may reach history");
+}
+
+/// An invalid `drift_scale` surfaces from `commit`, not from a panic and not
+/// silently.
+#[test]
+fn an_invalid_drift_scale_surfaces_from_commit() {
+    for bad in [-1.0, f64::NAN, f64::INFINITY] {
+        let mut h = history();
+        let err = h
+            .event(1)
+            .team(["a"])
+            .members([Member::new("b").with_drift_scale(bad)])
+            .winner(0)
+            .commit()
+            .unwrap_err();
+        assert!(
+            matches!(
+                err,
+                InferenceError::InvalidParameter {
+                    name: "drift_scale",
+                    ..
+                }
+            ),
+            "{bad}: {err:?}"
+        );
+        assert!(h.current_skill(&"b").is_none(), "{bad} reached the history");
+    }
+}
+
+/// `members` and `team` compose in either order.
+#[test]
+fn members_and_team_interleave() {
+    let mut h = history();
+    h.event(1)
+        .members([Member::new("a").with_prior(PRIOR)])
+        .team(["b"])
+        .scores([3.0, 1.0])
+        .commit()
+        .unwrap();
+    h.event(2)
+        .team(["b"])
+        .members([Member::new("c").with_prior(PRIOR)])
+        .scores([2.0, 4.0])
+        .commit()
+        .unwrap();
+    assert!(h.converge().unwrap().converged);
+    for key in ["a", "b", "c"] {
+        assert!(h.current_skill(&key).is_some(), "{key} missing");
+    }
+}

tests/ingestion_shape.rs

@@ -0,0 +1,190 @@
+//! Malformed events must be rejected at the ingestion boundary.
+//!
+//! Every case here was reachable from safe public API in a release build. Two
+//! of them are the two shapes this crate's defects keep taking: a panic from
+//! deep inside inference, and a finite, plausible-looking posterior computed
+//! from an event that should never have been accepted.
+//!
+//! `InferenceError::NotEnoughTeams` and `EmptyTeam` already existed when these
+//! were found — they were checked on the prediction paths and nowhere else, so
+//! ingestion could still manufacture the states they describe.
+
+use smallvec::smallvec;
+use trueskill_tt::{Event, History, InferenceError, Member, Outcome, Team};
+
+type Ev = Event<i64, &'static str>;
+
+fn history() -> History<i64, trueskill_tt::ConstantDrift, trueskill_tt::NullObserver, &'static str>
+{
+    History::builder().score_sigma(1.0).build()
+}
+
+fn teams(names: &[&[&'static str]]) -> smallvec::SmallVec<[Team<&'static str>; 4]> {
+    names
+        .iter()
+        .map(|team| Team::with_members(team.iter().map(|k| Member::new(*k))))
+        .collect()
+}
+
+/// The regression this file exists for: `run_chain` builds one diff link per
+/// adjacent pair of teams, so a one-team event left it indexing `links[1..]`
+/// on an empty vector and panicked — in release, from `History::add_events`.
+#[test]
+fn a_one_team_event_is_an_error_not_a_panic() {
+    let mut h = history();
+    let err = h
+        .add_events(vec![Ev {
+            time: 1,
+            teams: teams(&[&["a"]]),
+            outcome: Outcome::winner(0, 1),
+        }])
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::NotEnoughTeams { got: 1 }),
+        "{err:?}"
+    );
+}
+
+#[test]
+fn a_zero_team_event_is_an_error() {
+    let mut h = history();
+    let err = h
+        .add_events(vec![Ev {
+            time: 1,
+            teams: smallvec![],
+            outcome: Outcome::ranking([]),
+        }])
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::NotEnoughTeams { got: 0 }),
+        "{err:?}"
+    );
+}
+
+/// The quiet half. An empty team contributes no performance, so before this
+/// was rejected the event converged and handed back a finite posterior for its
+/// opponent — a plausible constant computed from nothing.
+#[test]
+fn an_empty_team_is_an_error_rather_than_a_free_win() {
+    let mut h = history();
+    let err = h
+        .add_events(vec![Ev {
+            time: 1,
+            teams: teams(&[&[], &["b"]]),
+            outcome: Outcome::winner(0, 2),
+        }])
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::EmptyTeam { team: 0 }),
+        "{err:?}"
+    );
+    // Nothing was recorded, so the history is still empty.
+    assert!(h.current_skill(&"b").is_none());
+}
+
+#[test]
+fn an_empty_team_is_reported_by_position() {
+    let mut h = history();
+    let err = h
+        .add_events(vec![Ev {
+            time: 1,
+            teams: teams(&[&["a"], &[]]),
+            outcome: Outcome::winner(0, 2),
+        }])
+        .unwrap_err();
+    assert!(
+        matches!(err, InferenceError::EmptyTeam { team: 1 }),
+        "{err:?}"
+    );
+}
+
+/// A NaN score used to ingest cleanly. `converge` reported `NonFiniteResult`,
+/// but a caller who read `current_skill` first was handed `tau: NaN` with
+/// nothing to say so.
+#[test]
+fn a_non_finite_score_is_rejected_at_ingestion() {
+    for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
+        let mut h = history();
+        let err = h
+            .add_events(vec![Ev {
+                time: 1,
+                teams: teams(&[&["a"], &["b"]]),
+                outcome: Outcome::scores([bad, 0.0]),
+            }])
+            .unwrap_err();
+        assert!(
+            matches!(err, InferenceError::InvalidParameter { name: "score", .. }),
+            "{bad}: {err:?}"
+        );
+        assert!(h.current_skill(&"a").is_none(), "{bad} was recorded anyway");
+    }
+}
+
+/// 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]
+fn the_event_builder_inherits_the_shape_checks() {
+    let mut h = history();
+    let err = h.event(1).team(["a"]).winner(0).commit().unwrap_err();
+    assert!(
+        matches!(err, InferenceError::NotEnoughTeams { got: 1 }),
+        "{err:?}"
+    );
+}
+
+/// A well-formed event is untouched by any of this.
+#[test]
+fn a_well_formed_event_still_ingests() {
+    let mut h = history();
+    h.add_events(vec![Ev {
+        time: 1,
+        teams: teams(&[&["a"], &["b"]]),
+        outcome: Outcome::scores([3.0, 1.0]),
+    }])
+    .unwrap();
+    assert!(h.converge().unwrap().converged);
+    assert!(h.current_skill(&"a").unwrap().mu() > h.current_skill(&"b").unwrap().mu());
+}

tests/joint_handle.rs

@@ -0,0 +1,267 @@
+//! `History::joint` factorises once and answers many questions.
+//!
+//! The contract that matters is *identity*: a `Joint` must return exactly what
+//! the one-shot call returns, bit for bit. A faster path that quietly disagreed
+//! with the slow one would be worse than no fast path — a caller would get
+//! different numbers depending on how many questions they happened to ask.
+
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, History, InferenceError, Member, Outcome, Team,
+    UnknownKeys,
+};
+
+type H = History<i64, ConstantDrift, trueskill_tt::NullObserver, &'static str>;
+
+fn duel(a: &'static str, b: &'static str, t: i64, sa: f64, sb: f64) -> Event<i64, &'static str> {
+    Event {
+        time: t,
+        teams: smallvec![
+            Team::with_members([Member::new(a)]),
+            Team::with_members([Member::new(b)]),
+        ],
+        outcome: Outcome::scores([sa, sb]),
+    }
+}
+
+fn ranked(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::winner(0, 2),
+    }
+}
+
+fn history(unknown: UnknownKeys) -> H {
+    History::builder()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .score_sigma(2.0)
+        .drift(ConstantDrift(0.5))
+        .unknown_keys(unknown)
+        .convergence(ConvergenceOptions {
+            max_iter: 20_000,
+            epsilon: 1e-13,
+            alpha: 1.0,
+        })
+        .build()
+}
+
+/// Several slices, competitors with different last appearances, so `latest`
+/// and `at_slice` both have work to do.
+fn fitted(unknown: UnknownKeys) -> H {
+    let mut h = history(unknown);
+    h.add_events(vec![
+        duel("a", "b", 1, 5.0, 2.0),
+        duel("c", "d", 1, 3.0, 3.5),
+        duel("a", "c", 2, 6.0, 1.0),
+        duel("b", "d", 3, 4.0, 3.0),
+        duel("a", "d", 4, 7.0, 2.0),
+        duel("b", "c", 5, 2.0, 4.0),
+    ])
+    .unwrap();
+    let report = h.converge().unwrap();
+    assert!(report.converged, "fixture must converge");
+    h
+}
+
+const PAIRS: [(&str, &str); 6] = [
+    ("a", "b"),
+    ("a", "c"),
+    ("a", "d"),
+    ("b", "c"),
+    ("b", "d"),
+    ("c", "d"),
+];
+
+#[test]
+fn a_joint_answers_exactly_what_the_one_shot_call_does() {
+    let h = fitted(UnknownKeys::Reject);
+    let joint = h.joint().unwrap();
+
+    for (a, b) in PAIRS {
+        let terms = [(&a, 1.0), (&b, -1.0)];
+        let one_shot = h.posterior_of(&terms).unwrap();
+        let cached = joint.posterior_of(&terms).unwrap();
+        assert_eq!(one_shot.pi(), cached.pi(), "{a} - {b}");
+        assert_eq!(one_shot.tau(), cached.tau(), "{a} - {b}");
+    }
+}
+
+#[test]
+fn a_joint_agrees_at_a_pinned_time_too() {
+    let h = fitted(UnknownKeys::Reject);
+    let joint = h.joint().unwrap();
+
+    for time in 1..=5 {
+        for (a, b) in PAIRS {
+            let terms = [(&a, 1.0), (&b, -1.0)];
+            let one_shot = h.posterior_of_at(time, &terms);
+            let cached = joint.posterior_of_at(time, &terms);
+            match (one_shot, cached) {
+                (Ok(x), Ok(y)) => {
+                    assert_eq!(x.pi(), y.pi(), "t={time} {a} - {b}");
+                    assert_eq!(x.tau(), y.tau(), "t={time} {a} - {b}");
+                }
+                (Err(x), Err(y)) => assert_eq!(x, y, "t={time} {a} - {b}"),
+                (x, y) => panic!("t={time} {a} - {b}: disagreed on success: {x:?} vs {y:?}"),
+            }
+        }
+    }
+}
+
+#[test]
+fn a_joint_scores_candidate_matchups_identically() {
+    let h = fitted(UnknownKeys::Reject);
+    let joint = h.joint().unwrap();
+    let (a, b) = ("a", "b");
+    let target = [(&a, 1.0), (&b, -1.0)];
+
+    for (x, y) in PAIRS {
+        let teams: [&[&&str]; 2] = [&[&x], &[&y]];
+        let one_shot = h.expected_variance_reduction(&teams, &target).unwrap();
+        let cached = joint.expected_variance_reduction(&teams, &target).unwrap();
+        assert_eq!(one_shot, cached, "{x} vs {y}");
+    }
+}
+
+/// The whole point: a competitor appears once per slice, so the joint is over
+/// appearances rather than competitors, and a caller sizing a batch needs to
+/// know which.
+#[test]
+fn variables_counts_appearances_not_competitors() {
+    let h = fitted(UnknownKeys::Reject);
+    let joint = h.joint().unwrap();
+    // Four competitors, twelve appearances across five slices, all with
+    // positive drift between them, so no two collapse.
+    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]
+fn pinned_competitors_collapse_consecutive_appearances() {
+    let mut h = History::builder()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .score_sigma(2.0)
+        .drift(ConstantDrift(0.0))
+        .convergence(ConvergenceOptions {
+            max_iter: 20_000,
+            epsilon: 1e-13,
+            alpha: 1.0,
+        })
+        .build();
+    h.add_events(vec![
+        duel("a", "b", 1, 5.0, 2.0),
+        duel("a", "b", 2, 4.0, 3.0),
+        duel("a", "b", 3, 6.0, 1.0),
+    ])
+    .unwrap();
+    assert!(h.converge().unwrap().converged);
+    assert_eq!(h.joint().unwrap().variables(), 2);
+}
+
+#[test]
+fn a_ranked_history_has_no_exact_joint() {
+    let mut h = history(UnknownKeys::Reject);
+    h.add_events(vec![duel("a", "b", 1, 5.0, 2.0), ranked("a", "b", 2)])
+        .unwrap();
+    let _ = h.converge().unwrap();
+    assert!(matches!(
+        h.joint().unwrap_err(),
+        InferenceError::JointUnavailable { .. }
+    ));
+}
+
+#[test]
+fn an_empty_history_has_no_joint() {
+    let h = history(UnknownKeys::Reject);
+    assert!(matches!(
+        h.joint().unwrap_err(),
+        InferenceError::JointUnavailable { .. }
+    ));
+}
+
+/// Unknown keys are decided per query, not when the joint is factorised — the
+/// factorisation does not depend on the question.
+#[test]
+fn unknown_keys_are_rejected_per_query() {
+    let h = fitted(UnknownKeys::Reject);
+    let joint = h.joint().unwrap();
+    let (a, z) = ("a", "nobody");
+    assert!(matches!(
+        joint.posterior_of(&[(&a, 1.0), (&z, -1.0)]).unwrap_err(),
+        InferenceError::UnknownKey { .. }
+    ));
+    // The handle is still usable afterwards.
+    let b = "b";
+    assert!(joint.posterior_of(&[(&a, 1.0), (&b, -1.0)]).is_ok());
+}
+
+/// Under `Prior`, an unseen competitor is independent of everything in the
+/// history, and the cached path must add the same prior variance the one-shot
+/// path does.
+#[test]
+fn unseen_competitors_match_the_one_shot_path() {
+    let h = fitted(UnknownKeys::Prior);
+    let joint = h.joint().unwrap();
+    let (a, z) = ("a", "nobody");
+    let terms = [(&a, 1.0), (&z, -1.0)];
+    let one_shot = h.posterior_of(&terms).unwrap();
+    let cached = joint.posterior_of(&terms).unwrap();
+    assert_eq!(one_shot.pi(), cached.pi());
+    assert_eq!(one_shot.tau(), cached.tau());
+}

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/time_expanded_joint.rs

@@ -0,0 +1,296 @@
+//! The joint must span slices, because Through Time reads each competitor at
+//! their own last appearance.
+//!
+//! The exact posterior of a multi-slice scored history is still Gaussian: the
+//! prior, the drift between appearances, and the scored likelihoods are all
+//! Gaussian. So it can be written out by hand and compared against, which is
+//! the check a single-slice fixture cannot make.
+
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, History, Member, Outcome, Team, UnknownKeys,
+};
+
+const SIGMA0: f64 = 6.0;
+const BETA: f64 = 1.0;
+const SCORE_SIGMA: f64 = 2.0;
+const GAMMA: f64 = 0.5;
+
+type H = History<i64, ConstantDrift, trueskill_tt::NullObserver, &'static str>;
+
+fn history(gamma: f64) -> H {
+    History::builder()
+        .mu(0.0)
+        .sigma(SIGMA0)
+        .beta(BETA)
+        .score_sigma(SCORE_SIGMA)
+        .drift(ConstantDrift(gamma))
+        .unknown_keys(UnknownKeys::Reject)
+        .convergence(ConvergenceOptions {
+            max_iter: 20_000,
+            epsilon: 1e-13,
+            alpha: 1.0,
+        })
+        .build()
+}
+
+fn duel(a: &'static str, b: &'static str, t: i64, sa: f64, sb: f64) -> Event<i64, &'static str> {
+    Event {
+        time: t,
+        teams: smallvec![
+            Team::with_members([Member::new(a)]),
+            Team::with_members([Member::new(b)]),
+        ],
+        outcome: Outcome::scores([sa, sb]),
+    }
+}
+
+fn inverse(mut a: Vec<Vec<f64>>) -> Vec<Vec<f64>> {
+    let n = a.len();
+    let mut inv: Vec<Vec<f64>> = (0..n)
+        .map(|i| (0..n).map(|j| f64::from(u8::from(i == j))).collect())
+        .collect();
+    for col in 0..n {
+        let mut piv = col;
+        for r in col + 1..n {
+            if a[r][col].abs() > a[piv][col].abs() {
+                piv = r;
+            }
+        }
+        a.swap(col, piv);
+        inv.swap(col, piv);
+        let d = a[col][col];
+        for j in 0..n {
+            a[col][j] /= d;
+            inv[col][j] /= d;
+        }
+        for r in 0..n {
+            if r == col {
+                continue;
+            }
+            let f = a[r][col];
+            for j in 0..n {
+                a[r][j] -= f * a[col][j];
+                inv[r][j] -= f * inv[col][j];
+            }
+        }
+    }
+    inv
+}
+
+/// Two competitors, two slices ten units apart, one duel in each.
+///
+/// The exact precision is written out explicitly here rather than obtained
+/// from the crate, so this is an independent check rather than a restatement.
+/// Variables are `[a0, b0, a1, b1]`.
+#[test]
+fn a_two_slice_joint_matches_the_exact_posterior() {
+    let mut h = history(GAMMA);
+    h.add_events(vec![
+        duel("a", "b", 0, 5.0, 2.0),
+        duel("a", "b", 10, 4.0, 3.0),
+    ])
+    .unwrap();
+    let report = h.converge().unwrap();
+    assert!(report.converged, "{:?}", report.final_step);
+
+    let prior_prec = 1.0 / (SIGMA0 * SIGMA0);
+    let drift_prec = 1.0 / (10.0 * GAMMA * GAMMA);
+    let obs_prec = 1.0 / (SCORE_SIGMA * SCORE_SIGMA + 2.0 * BETA * BETA);
+
+    let mut lambda = vec![vec![0.0; 4]; 4];
+    // priors on the first appearances
+    lambda[0][0] += prior_prec;
+    lambda[1][1] += prior_prec;
+    // drift a0-a1 and b0-b1
+    for (p, q) in [(0usize, 2usize), (1, 3)] {
+        lambda[p][p] += drift_prec;
+        lambda[q][q] += drift_prec;
+        lambda[p][q] -= drift_prec;
+        lambda[q][p] -= drift_prec;
+    }
+    // one duel per slice: contrast (+1, -1) on that slice's variables
+    for (p, q) in [(0usize, 1usize), (2, 3)] {
+        lambda[p][p] += obs_prec;
+        lambda[q][q] += obs_prec;
+        lambda[p][q] -= obs_prec;
+        lambda[q][p] -= obs_prec;
+    }
+    let cov = inverse(lambda);
+
+    // The crate reads each competitor at their latest appearance: a1, b1.
+    let exact_gap = (cov[2][2] + cov[3][3] - 2.0 * cov[2][3]).sqrt();
+    let got = h.posterior_of(&[(&"a", 1.0), (&"b", -1.0)]).unwrap();
+    assert!(
+        (got.sigma() - exact_gap).abs() / exact_gap < 1e-9,
+        "difference: got {} exact {exact_gap}",
+        got.sigma()
+    );
+
+    let exact_single = cov[2][2].sqrt();
+    let got_single = h.posterior_of(&[(&"a", 1.0)]).unwrap();
+    assert!(
+        (got_single.sigma() - exact_single).abs() / exact_single < 1e-9,
+        "single node: got {} exact {exact_single}",
+        got_single.sigma()
+    );
+}
+
+/// The case that motivated this: competitors read at *different* slices, with
+/// the last slice holding only one of them. Under the old latest-slice joint
+/// this was `UnknownKey`.
+#[test]
+fn competitors_last_seen_in_different_slices_are_comparable() {
+    let mut h = history(GAMMA);
+    h.add_events(vec![
+        duel("a", "b", 0, 5.0, 2.0),
+        duel("a", "c", 10, 4.0, 3.0),
+        // the final slice holds one duel that does not involve b at all
+        duel("a", "c", 20, 6.0, 1.0),
+    ])
+    .unwrap();
+    let _ = h.converge().unwrap();
+
+    // b last appeared at time 0; a and c at time 20. All three must resolve.
+    for (x, y) in [("a", "b"), ("b", "c"), ("a", "c")] {
+        let g = h
+            .posterior_of(&[(&x, 1.0), (&y, -1.0)])
+            .unwrap_or_else(|e| panic!("{x} - {y} should resolve across slices: {e}"));
+        assert!(g.sigma() > 0.0 && g.sigma().is_finite());
+    }
+}
+
+/// The mean must agree with what message passing reports, which is exact even
+/// with cycles. Only the second moment needs the joint.
+#[test]
+fn means_agree_with_the_marginals() {
+    let mut h = history(GAMMA);
+    h.add_events(vec![
+        duel("a", "b", 0, 5.0, 2.0),
+        duel("b", "c", 5, 3.0, 1.0),
+        duel("a", "c", 10, 4.0, 2.0),
+    ])
+    .unwrap();
+    let _ = h.converge().unwrap();
+
+    for k in ["a", "b", "c"] {
+        let marginal = h.current_skill(&k).unwrap().mu();
+        let joint = h.posterior_of(&[(&k, 1.0)]).unwrap().mu();
+        assert!(
+            (marginal - joint).abs() < 1e-9,
+            "{k}: marginal {marginal}, joint {joint}"
+        );
+    }
+}
+
+/// With zero drift a competitor has one latent skill however many slices it
+/// appears in, so spreading the same events over time must not change the
+/// answer. This exercises the appearance-merging path.
+#[test]
+fn zero_drift_makes_slice_layout_irrelevant() {
+    let spread = {
+        let mut h = history(0.0);
+        h.add_events(vec![
+            duel("a", "b", 0, 5.0, 2.0),
+            duel("a", "b", 10, 4.0, 3.0),
+            duel("a", "b", 20, 6.0, 1.0),
+        ])
+        .unwrap();
+        let _ = h.converge().unwrap();
+        h.posterior_of(&[(&"a", 1.0), (&"b", -1.0)]).unwrap()
+    };
+    let together = {
+        let mut h = history(0.0);
+        h.add_events(vec![
+            duel("a", "b", 0, 5.0, 2.0),
+            duel("a", "b", 0, 4.0, 3.0),
+            duel("a", "b", 0, 6.0, 1.0),
+        ])
+        .unwrap();
+        let _ = h.converge().unwrap();
+        h.posterior_of(&[(&"a", 1.0), (&"b", -1.0)]).unwrap()
+    };
+
+    assert!(
+        (spread.sigma() - together.sigma()).abs() < 1e-9,
+        "zero drift: spread {} vs together {}",
+        spread.sigma(),
+        together.sigma()
+    );
+}
+
+/// More drift means less is carried forward from old evidence, so a comparison
+/// against a competitor last seen long ago must widen.
+#[test]
+fn drift_widens_a_comparison_across_time() {
+    let mut previous = 0.0;
+    for gamma in [0.0f64, 0.1, 0.5, 2.0] {
+        let mut h = history(gamma);
+        h.add_events(vec![
+            duel("a", "b", 0, 5.0, 2.0),
+            duel("a", "c", 100, 4.0, 3.0),
+        ])
+        .unwrap();
+        let _ = h.converge().unwrap();
+
+        // b was last seen at time 0; a at time 100.
+        let g = h.posterior_of(&[(&"a", 1.0), (&"b", -1.0)]).unwrap();
+        assert!(
+            g.sigma() > previous,
+            "gamma={gamma}: sigma {} did not exceed {previous}",
+            g.sigma()
+        );
+        previous = g.sigma();
+    }
+}
+
+/// `posterior_of_at` pins the reading to a moment, where `posterior_of` takes
+/// each competitor wherever they were last seen.
+#[test]
+fn posterior_of_at_reads_as_of_a_time() {
+    let mut h = history(GAMMA);
+    h.add_events(vec![
+        duel("a", "b", 0, 5.0, 2.0),
+        duel("a", "b", 10, 4.0, 3.0),
+        duel("a", "b", 20, 6.0, 1.0),
+    ])
+    .unwrap();
+    let _ = h.converge().unwrap();
+
+    let early = h.posterior_of_at(0, &[(&"a", 1.0), (&"b", -1.0)]).unwrap();
+    let late = h.posterior_of_at(20, &[(&"a", 1.0), (&"b", -1.0)]).unwrap();
+    let latest = h.posterior_of(&[(&"a", 1.0), (&"b", -1.0)]).unwrap();
+
+    // Asking as of the final slice is the same as asking for the latest.
+    assert!((late.mu() - latest.mu()).abs() < 1e-9);
+    assert!((late.sigma() - latest.sigma()).abs() < 1e-9);
+
+    // Reading at time 0 is a different quantity, and the smoothed estimate
+    // there is informed by everything that came after.
+    assert!(
+        (early.mu() - late.mu()).abs() > 1e-6,
+        "as-of-0 and as-of-20 should differ: {} vs {}",
+        early.mu(),
+        late.mu()
+    );
+
+    // A time before any event has nothing to read.
+    assert!(h.posterior_of_at(-1, &[(&"a", 1.0)]).is_err());
+}
+
+/// Times between slices resolve to the latest appearance at or before them.
+#[test]
+fn a_time_between_slices_reads_the_previous_appearance() {
+    let mut h = history(GAMMA);
+    h.add_events(vec![
+        duel("a", "b", 0, 5.0, 2.0),
+        duel("a", "b", 100, 4.0, 3.0),
+    ])
+    .unwrap();
+    let _ = h.converge().unwrap();
+
+    let at_zero = h.posterior_of_at(0, &[(&"a", 1.0)]).unwrap();
+    let between = h.posterior_of_at(50, &[(&"a", 1.0)]).unwrap();
+    assert!((at_zero.mu() - between.mu()).abs() < 1e-12);
+    assert!((at_zero.sigma() - between.sigma()).abs() < 1e-12);
+}

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