chore: Release trueskill-tt version 0.7.0

Factorise the joint once with History::joint, so a batch of queries pays
the O(n^3) Cholesky once rather than once per question.

Closes #51

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

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

src/history.rs

@@ -202,6 +202,19 @@ pub(crate) struct CompetitorConfig {
     drift_scale: Option<f64>,
 }
 
+/// The joint precision over a history's appearances, with the maps needed to
+/// address a competitor either at their latest appearance or at a given slice.
+struct TimeExpanded {
+    /// Row-major precision matrix over appearances.
+    lambda: Vec<f64>,
+    /// `(row, slice)` of each competitor's latest appearance.
+    latest: HashMap<Index, (usize, usize)>,
+    /// Row of each `(competitor, slice)` appearance.
+    at_slice: HashMap<(Index, usize), usize>,
+    /// Side length of `lambda`.
+    width: usize,
+}
+
 /// A linear functional resolved against one time slice.
 struct ResolvedTerms {
     /// Coefficients over the slice's own competitors, in its ordering.
@@ -765,19 +778,104 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
         Ok(crate::quality(&group_refs, self.beta))
     }
 
-    /// Resolve `terms` into a contrast over the slice's competitor order, the
+    /// The joint posterior precision over the whole history, time-expanded.
-    /// coefficients of any competitors the slice has never seen, and the mean.
     ///
-    /// An unseen competitor shares no event with the slice, so it is
+    /// A competitor's skill is not one variable but one per appearance, linked
-    /// independent of everything in it by construction; keeping those
+    /// by drift. That is the point of Through Time, and it is why a joint over
-    /// coefficients separate is what lets their variance be added rather than
+    /// a single slice answers almost nothing: competitors are each read at
-    /// solved for.
+    /// *their own* last appearance, and in a history with per-day or per-event
+    /// slices those are different slices. A 76-slice history whose last slice
+    /// holds one competitor can answer no pairwise question at all.
+    ///
+    /// Variables are `(competitor, appearance)`. Factors are the prior on a
+    /// first appearance, the drift between consecutive appearances, and the
+    /// within-slice event contrasts. Consecutive appearances with zero drift
+    /// variance are the same variable rather than two joined by an infinite
+    /// precision, which keeps the matrix positive-definite when a competitor is
+    /// pinned with `drift_scale = 0`.
+    ///
+    /// Returns the matrix, each competitor's row at its latest appearance, and
+    /// the row at each `(competitor, slice)` for time-addressed queries.
+    fn time_expanded_joint(&self) -> TimeExpanded {
+        let mut latest: HashMap<Index, (usize, usize)> = HashMap::new();
+        let mut at_slice: HashMap<(Index, usize), usize> = HashMap::new();
+        // Row of a competitor's previous appearance, and the drift variance
+        // separating it from the current one.
+        let mut previous: HashMap<Index, usize> = HashMap::new();
+        let mut drift_links: Vec<(usize, usize, f64)> = Vec::new();
+        let mut first_rows: Vec<(usize, Index)> = Vec::new();
+        let mut n = 0usize;
+
+        for (slice_idx, slice) in self.time_slices.iter().enumerate() {
+            for (agent, elapsed) in slice.appearances() {
+                let rating = &self.agents[agent].rating;
+                let row = match previous.get(&agent) {
+                    None => {
+                        let row = n;
+                        n += 1;
+                        first_rows.push((row, agent));
+                        row
+                    }
+                    Some(&prev) => {
+                        let drift = rating.drift_variance_for_elapsed(elapsed);
+                        if drift <= 0.0 {
+                            // No drift: the same latent skill, not two.
+                            prev
+                        } else {
+                            let row = n;
+                            n += 1;
+                            drift_links.push((prev, row, drift));
+                            row
+                        }
+                    }
+                };
+                previous.insert(agent, row);
+                latest.insert(agent, (row, slice_idx));
+                at_slice.insert((agent, slice_idx), row);
+            }
+        }
+
+        let mut lambda = vec![0.0; n * n];
+
+        for (row, agent) in first_rows {
+            lambda[row * n + row] += 1.0 / self.agents[agent].rating.prior.sigma().powi(2);
+        }
+        for (a, b, drift) in drift_links {
+            lambda[a * n + a] += 1.0 / drift;
+            lambda[b * n + b] += 1.0 / drift;
+            lambda[a * n + b] -= 1.0 / drift;
+            lambda[b * n + a] -= 1.0 / drift;
+        }
+        for (slice_idx, slice) in self.time_slices.iter().enumerate() {
+            for (contrast, noise) in slice.scored_contrasts(&self.agents) {
+                for (ia, ca) in &contrast {
+                    let ra = at_slice[&(*ia, slice_idx)];
+                    for (ib, cb) in &contrast {
+                        let rb = at_slice[&(*ib, slice_idx)];
+                        lambda[ra * n + rb] += ca * cb / noise;
+                    }
+                }
+            }
+        }
+
+        TimeExpanded {
+            lambda,
+            latest,
+            at_slice,
+            width: n,
+        }
+    }
+
+    /// Resolve `terms` into a contrast over the time-expanded rows, the
+    /// coefficients of competitors the history has never seen, and the mean.
+    ///
+    /// `row_for` picks which appearance of a competitor the caller means —
+    /// their latest, or the one at a given time.
     fn resolve_terms(
         &self,
         terms: &[(&K, f64)],
-        slice: &TimeSlice<T>,
-        row_of: &HashMap<Index, usize>,
         width: usize,
+        row_for: impl Fn(Index) -> Option<(usize, usize)>,
     ) -> Result<ResolvedTerms, InferenceError>
     where
         K: std::fmt::Debug,
@@ -790,16 +888,16 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
             let located = self
                 .keys
                 .get(*key)
-                .and_then(|index| row_of.get(&index).map(|row| (index, *row)));
+                .and_then(|index| row_for(index).map(|located| (index, located)));
 
             match located {
-                Some((index, row)) => {
+                Some((index, (row, slice_idx))) => {
                     contrast[row] += coefficient;
                     mean += coefficient
-                        * slice
+                        * self.time_slices[slice_idx]
                             .skills
                             .get(index)
-                            .expect("index came from this slice")
+                            .expect("row came from this slice")
                             .posterior()
                             .mu();
                 }
@@ -844,61 +942,63 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     /// The mean is the same combination of the marginal means, which message
     /// passing already gets exactly right. Only the variance needs the joint.
     ///
+    /// # Which appearance each competitor is read at
+    ///
+    /// Each competitor is read at *their own* latest appearance, which is where
+    /// [`History::current_skill`] reads them too, so the two agree about which
+    /// posterior they describe. That matters in a Through-Time history: with
+    /// per-day or per-event slices, competitors are rarely all present in any
+    /// one of them. Use [`History::posterior_of_at`] to pin a time instead.
+    ///
+    /// # Asking more than one question
+    ///
+    /// This factorises the joint, uses it once, and throws it away. The
+    /// factorisation is the expensive part and it depends only on the fit, so
+    /// asking `n` questions this way pays for it `n` times. Take a
+    /// [`Joint`] with [`History::joint`] instead — the answers are identical,
+    /// and only the first one pays.
+    ///
     /// # Limitations
     ///
-    /// Currently exact only for a slice whose events are all scored, because a
+    /// Exact only for a history whose events are all scored, because a scored
-    /// scored likelihood is Gaussian and its factor can be rebuilt exactly. A
+    /// likelihood is Gaussian and its factor can be rebuilt exactly. A ranked
-    /// ranked outcome's truncation is approximated by EP, and reconstructing
+    /// outcome's truncation is approximated by EP, and reconstructing those
-    /// those factors needs the converged messages, which inference does not
+    /// factors needs the converged messages, which inference does not retain —
-    /// retain. Ranked slices return `JointUnavailable` rather than a plausible
+    /// so a history containing ranked events returns `JointUnavailable` rather
-    /// wrong number.
+    /// than a plausible wrong number.
     ///
     /// # Errors
     ///
-    /// `UnknownKey` for a competitor absent from the latest slice, and
+    /// `UnknownKey` for a competitor the history has never seen, and
-    /// `JointUnavailable` if that slice contains ranked events or the system is
+    /// `JointUnavailable` for ranked events or a system that is not
-    /// not positive-definite.
+    /// positive-definite.
     pub fn posterior_of(&self, terms: &[(&K, f64)]) -> Result<Gaussian, InferenceError>
     where
         K: std::fmt::Debug,
     {
-        let slice = self
+        self.joint()?.posterior_of(terms)
-            .time_slices
-            .last()
-            .ok_or(InferenceError::JointUnavailable {
-                reason: "the history has no events",
-            })?;
-
-        if !slice.all_scored() {
-            return Err(InferenceError::JointUnavailable {
-                reason: "the latest slice contains ranked events, whose EP factors \
-                         are not retained after convergence",
-            });
     }
 
-        let (order, lambda) = slice.joint_precision(&self.agents);
+    /// Posterior of a linear combination, read as of `time`.
-        let mut row_of = HashMap::with_capacity(order.len());
+    ///
-        for (r, idx) in order.iter().enumerate() {
+    /// Each competitor is taken at their latest appearance at or before `time`,
-            row_of.insert(*idx, r);
+    /// which is the same reading [`History::learning_curve`] gives. Use this
-        }
+    /// when a comparison must be anchored to a moment — "how did these two
-
+    /// stand at the end of last season" — rather than to wherever each
-        let ResolvedTerms {
+    /// competitor was last seen.
-            contrast,
+    ///
-            unseen,
+    /// As with [`History::posterior_of`], this factorises the joint for one
-            mean,
+    /// question; [`History::joint`] amortises that across many.
-        } = self.resolve_terms(terms, slice, &row_of, order.len())?;
+    ///
-
+    /// # Errors
-        let z =
+    ///
-            crate::joint::solve_spd(lambda, &contrast).ok_or(InferenceError::JointUnavailable {
+    /// As [`History::posterior_of`], plus `UnknownKey` for a competitor with no
-                reason: "the precision matrix is not positive-definite, which means \
+    /// appearance at or before `time`.
-                         a competitor has neither a proper prior nor any evidence",
+    pub fn posterior_of_at(&self, time: T, terms: &[(&K, f64)]) -> Result<Gaussian, InferenceError>
-            })?;
+    where
-
+        K: std::fmt::Debug,
-        let prior_var = self.sigma * self.sigma;
+    {
-        let variance: f64 = contrast.iter().zip(&z).map(|(c, z)| c * z).sum::<f64>()
+        self.joint()?.posterior_of_at(time, terms)
-            + unseen.values().map(|c| c * c * prior_var).sum::<f64>();
-
-        Ok(Gaussian::from_mv(mean, variance))
     }
 
     /// How much observing this matchup would shrink the variance of `target`.
@@ -914,6 +1014,11 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     /// score. It is also far cheaper: one linear solve rather than a full
     /// inference pass per possible outcome.
     ///
+    /// Scoring a field of candidates is the whole point of this call, and each
+    /// candidate is one question against an unchanged fit — so use
+    /// [`Joint::expected_variance_reduction`] for anything past a single
+    /// candidate, or pay for the factorisation once per candidate.
+    ///
     /// # There is no expectation to take
     ///
     /// Observing a scored event is a rank-one update to the precision matrix,
@@ -943,90 +1048,90 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     where
         K: std::fmt::Debug,
     {
-        if teams.len() != 2 {
+        self.joint()?.expected_variance_reduction(teams, target)
-            return Err(InferenceError::MismatchedShape {
-                kind: "expected_variance_reduction takes exactly 2 teams",
-                expected: 2,
-                got: teams.len(),
-            });
     }
 
-        let slice = self
+    /// Factorise the joint posterior once, to answer many questions against it.
-            .time_slices
+    ///
-            .last()
+    /// [`History::posterior_of`] and its neighbours each build and factorise
-            .ok_or(InferenceError::JointUnavailable {
+    /// the joint, use it once, and drop it. The factorisation is `O(n^3)` in
-                reason: "the history has no events",
+    /// the history's *appearances* and depends only on the fit, so a caller
-            })?;
+    /// asking about every pair in a standings table, every cell in a grid, or
-        if !slice.all_scored() {
+    /// every candidate in an active-learning sweep pays for the same
+    /// factorisation once per question.
+    ///
+    /// A `Joint` pays it once. Each subsequent query is `O(n^2)` — one forward
+    /// substitution — and returns exactly what the one-shot call would.
+    ///
+    /// ```
+    /// # use smallvec::smallvec;
+    /// # use trueskill_tt::{Event, History, Member, Outcome, Team};
+    /// # let mut h = History::builder().score_sigma(1.0).build();
+    /// # let round = |x, y, sx, sy, t| Event {
+    /// #     time: t,
+    /// #     teams: smallvec![
+    /// #         Team::with_members([Member::new(x)]),
+    /// #         Team::with_members([Member::new(y)]),
+    /// #     ],
+    /// #     outcome: Outcome::scores([sx, sy]),
+    /// # };
+    /// # h.add_events(vec![
+    /// #     round("a", "b", 3.0, 1.0, 1),
+    /// #     round("b", "c", 2.0, 1.0, 2),
+    /// # ]).unwrap();
+    /// # h.converge().unwrap();
+    /// let joint = h.joint()?;
+    /// for (a, b) in [("a", "b"), ("a", "c"), ("b", "c")] {
+    ///     let gap = joint.posterior_of(&[(&a, 1.0), (&b, -1.0)])?;
+    ///     println!("{a} - {b}: {:.3} +/- {:.3}", gap.mu(), gap.sigma());
+    /// }
+    /// # Ok::<(), trueskill_tt::InferenceError>(())
+    /// ```
+    ///
+    /// The handle borrows the history, so the borrow checker enforces what a
+    /// cache would otherwise have to invalidate: no events can be added and no
+    /// refit can run while it is alive. Drop it to release the factorisation,
+    /// which is `n^2` floats and is the largest thing this crate allocates.
+    ///
+    /// # Errors
+    ///
+    /// `JointUnavailable` if the history is empty, contains ranked events, or
+    /// yields a precision matrix that is not positive-definite.
+    pub fn joint(&self) -> Result<Joint<'_, T, D, O, K>, InferenceError> {
+        if self.time_slices.is_empty() {
             return Err(InferenceError::JointUnavailable {
-                reason: "the latest slice contains ranked events, whose EP factors \
+                reason: "the history has no events",
-                         are not retained after convergence",
+            });
+        }
+        if !self.time_slices.iter().all(TimeSlice::all_scored) {
+            return Err(InferenceError::JointUnavailable {
+                reason: "the history contains ranked events, whose EP factors are \
+                         not retained after convergence",
             });
         }
 
-        // The candidate matchup, expressed as the same kind of linear
+        let TimeExpanded {
-        // functional as the target.
+            lambda,
-        let mut matchup: Vec<(&K, f64)> = Vec::new();
+            latest,
-        let mut noise = self.score_sigma * self.score_sigma;
+            at_slice,
-        for (team_idx, team) in teams.iter().enumerate() {
+            width,
-            if team.is_empty() {
+        } = self.time_expanded_joint();
-                return Err(InferenceError::EmptyTeam { team: team_idx });
-            }
-            let sign = if team_idx == 0 { 1.0 } else { -1.0 };
-            for key in team.iter() {
-                matchup.push((*key, sign));
-                let beta = self
-                    .keys
-                    .get(*key)
-                    .map_or(self.beta, |index| self.agents[index].rating.beta);
-                noise += beta * beta;
-            }
-        }
 
-        let (order, lambda) = slice.joint_precision(&self.agents);
+        let cholesky = crate::joint::Cholesky::factor(lambda, width).ok_or(
-        let mut row_of = HashMap::with_capacity(order.len());
-        for (r, idx) in order.iter().enumerate() {
-            row_of.insert(*idx, r);
-        }
-
-        let target = self.resolve_terms(target, slice, &row_of, order.len())?;
-        let matchup = self.resolve_terms(&matchup, slice, &row_of, order.len())?;
-        let (target_contrast, target_unseen) = (target.contrast, target.unseen);
-        let (matchup_contrast, matchup_unseen) = (matchup.contrast, matchup.unseen);
-
-        // One solve: z = L^-1 a serves both inner products, since
-        // c^T L^-1 a = c^T z and a^T L^-1 a = a^T z.
-        let z = crate::joint::solve_spd(lambda, &matchup_contrast).ok_or(
             InferenceError::JointUnavailable {
-                reason: "the precision matrix is not positive-definite",
+                reason: "the precision matrix is not positive-definite, which means \
+                         a competitor has neither a proper prior nor any evidence",
             },
         )?;
 
-        let prior_var = self.sigma * self.sigma;
+        Ok(Joint {
-        // Competitors outside the slice are independent, so they contribute
+            history: self,
-        // only where the same key appears in both functionals.
+            cholesky,
-        let cross_unseen: f64 = target_unseen
+            latest,
-            .iter()
+            at_slice,
-            .map(|(k, tc)| tc * matchup_unseen.get(k).copied().unwrap_or(0.0) * prior_var)
+            width,
-            .sum();
+        })
-        let self_unseen: f64 = matchup_unseen.values().map(|c| c * c * prior_var).sum();
-
-        let cross: f64 = target_contrast
-            .iter()
-            .zip(&z)
-            .map(|(c, z)| c * z)
-            .sum::<f64>()
-            + cross_unseen;
-        let matchup_var: f64 = matchup_contrast
-            .iter()
-            .zip(&z)
-            .map(|(a, z)| a * z)
-            .sum::<f64>()
-            + self_unseen;
-
-        Ok(cross * cross / (noise + matchup_var))
     }
-
     /// Predictive distribution of the score margin between two teams.
     ///
     /// Answers "what will the gap be, and how wide is that interval" for a
@@ -1805,6 +1910,195 @@ impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> History<T, D, O
     }
 }
 
+/// A factorised joint posterior, reusable across many queries.
+///
+/// Built by [`History::joint`]. Every question the joint answers — the width of
+/// a contrast, the covariance of two, how much a candidate matchup would
+/// sharpen either — is a bilinear form in the inverse precision matrix, and all
+/// of them share one factorisation. That factorisation is the whole cost:
+/// `O(n^3)` in the history's appearances to build, `O(n^2)` per question after.
+///
+/// The handle borrows the history, so no refit can run and no events can be
+/// added while it is alive. That is what makes it correct without any
+/// invalidation logic: there is no window in which the factorisation could
+/// describe a fit that no longer exists.
+pub struct Joint<'h, T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> {
+    history: &'h History<T, D, O, K>,
+    cholesky: crate::joint::Cholesky,
+    /// `(row, slice)` of each competitor's latest appearance.
+    latest: HashMap<Index, (usize, usize)>,
+    /// Row of each `(competitor, slice)` appearance.
+    at_slice: HashMap<(Index, usize), usize>,
+    /// Side length of the precision matrix.
+    width: usize,
+}
+
+/// Deliberately does not print the factorisation, which is `n^2` floats and
+/// would make a `{:?}` of a large joint unreadable and slow.
+impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> std::fmt::Debug
+    for Joint<'_, T, D, O, K>
+{
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Joint")
+            .field("variables", &self.width)
+            .finish_non_exhaustive()
+    }
+}
+
+impl<T: Time, D: Drift<T>, O: Observer<T>, K: Eq + Hash + Clone> Joint<'_, T, D, O, K> {
+    /// Number of variables in the joint: the history's appearances, after
+    /// collapsing consecutive pairs a competitor does not drift between.
+    ///
+    /// This is what the cost scales in, and it is not the competitor count — a
+    /// competitor contributes one variable per slice it appears in. Worth
+    /// checking before asking for a joint over a long history.
+    #[must_use]
+    pub fn variables(&self) -> usize {
+        self.width
+    }
+
+    /// Turn a resolved functional into its posterior.
+    ///
+    /// The variance is `|L^-1 c|^2` over the competitors the history knows,
+    /// plus an independent prior variance for each competitor it does not —
+    /// unseen competitors are uncorrelated with everything by construction.
+    fn distribution(&self, resolved: &ResolvedTerms) -> Gaussian {
+        let y = self.cholesky.whiten(&resolved.contrast);
+        let prior_var = self.history.sigma * self.history.sigma;
+        let variance = crate::joint::bilinear(&y, &y)
+            + resolved
+                .unseen
+                .values()
+                .map(|c| c * c * prior_var)
+                .sum::<f64>();
+        Gaussian::from_mv(resolved.mean, variance)
+    }
+
+    /// Posterior of a linear combination of competitors' skills.
+    ///
+    /// Identical to [`History::posterior_of`], including which appearance each
+    /// competitor is read at, without re-paying the factorisation.
+    ///
+    /// # Errors
+    ///
+    /// `UnknownKey` for a competitor the history has never seen.
+    pub fn posterior_of(&self, terms: &[(&K, f64)]) -> Result<Gaussian, InferenceError>
+    where
+        K: std::fmt::Debug,
+    {
+        let resolved = self
+            .history
+            .resolve_terms(terms, self.width, |index| self.latest.get(&index).copied())?;
+        Ok(self.distribution(&resolved))
+    }
+
+    /// Posterior of a linear combination, read as of `time`.
+    ///
+    /// Identical to [`History::posterior_of_at`] without re-paying the
+    /// factorisation.
+    ///
+    /// # Errors
+    ///
+    /// `UnknownKey` for a competitor with no appearance at or before `time`.
+    pub fn posterior_of_at(&self, time: T, terms: &[(&K, f64)]) -> Result<Gaussian, InferenceError>
+    where
+        K: std::fmt::Debug,
+    {
+        let as_of = self.rows_as_of(time);
+        let resolved = self
+            .history
+            .resolve_terms(terms, self.width, |index| as_of.get(&index).copied())?;
+        Ok(self.distribution(&resolved))
+    }
+
+    /// Latest appearance at or before `time`, per competitor.
+    fn rows_as_of(&self, time: T) -> HashMap<Index, (usize, usize)> {
+        let mut as_of: HashMap<Index, (usize, usize)> = HashMap::new();
+        for (slice_idx, slice) in self.history.time_slices.iter().enumerate() {
+            if slice.time > time {
+                break;
+            }
+            for (agent, _) in slice.appearances() {
+                if let Some(row) = self.at_slice.get(&(agent, slice_idx)) {
+                    as_of.insert(agent, (*row, slice_idx));
+                }
+            }
+        }
+        as_of
+    }
+
+    /// How much observing this matchup would shrink the variance of `target`.
+    ///
+    /// Identical to [`History::expected_variance_reduction`] without re-paying
+    /// the factorisation, which is the shape this call is normally used in:
+    /// one target, a field of candidate matchups, one unchanged fit.
+    ///
+    /// # Errors
+    ///
+    /// `MismatchedShape` unless exactly two teams are supplied, `EmptyTeam` for
+    /// an empty one, and `UnknownKey` for an unseen competitor.
+    pub fn expected_variance_reduction(
+        &self,
+        teams: &[&[&K]],
+        target: &[(&K, f64)],
+    ) -> Result<f64, InferenceError>
+    where
+        K: std::fmt::Debug,
+    {
+        if teams.len() != 2 {
+            return Err(InferenceError::MismatchedShape {
+                kind: "expected_variance_reduction takes exactly 2 teams",
+                expected: 2,
+                got: teams.len(),
+            });
+        }
+
+        // The candidate matchup, expressed as the same kind of linear
+        // functional as the target.
+        let mut matchup: Vec<(&K, f64)> = Vec::new();
+        let mut noise = self.history.score_sigma * self.history.score_sigma;
+        for (team_idx, team) in teams.iter().enumerate() {
+            if team.is_empty() {
+                return Err(InferenceError::EmptyTeam { team: team_idx });
+            }
+            let sign = if team_idx == 0 { 1.0 } else { -1.0 };
+            for key in team.iter() {
+                matchup.push((*key, sign));
+                let beta = self
+                    .history
+                    .keys
+                    .get(*key)
+                    .map_or(self.history.beta, |index| {
+                        self.history.agents[index].rating.beta
+                    });
+                noise += beta * beta;
+            }
+        }
+
+        let row_for = |index: Index| self.latest.get(&index).copied();
+        let target = self.history.resolve_terms(target, self.width, row_for)?;
+        let matchup = self.history.resolve_terms(&matchup, self.width, row_for)?;
+
+        let y_target = self.cholesky.whiten(&target.contrast);
+        let y_matchup = self.cholesky.whiten(&matchup.contrast);
+
+        let prior_var = self.history.sigma * self.history.sigma;
+        // Competitors outside the history are independent, so they contribute
+        // only where the same key appears in both functionals.
+        let cross_unseen: f64 = target
+            .unseen
+            .iter()
+            .map(|(k, tc)| tc * matchup.unseen.get(k).copied().unwrap_or(0.0) * prior_var)
+            .sum();
+        let self_unseen: f64 = matchup.unseen.values().map(|c| c * c * prior_var).sum();
+
+        let cross = crate::joint::bilinear(&y_target, &y_matchup) + cross_unseen;
+        let matchup_var = crate::joint::bilinear(&y_matchup, &y_matchup) + self_unseen;
+
+        Ok(cross * cross / (noise + matchup_var))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use approx::assert_ulps_eq;

src/joint.rs

@@ -1,34 +1,54 @@
-//! 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
+//! Every question the joint answers is a *bilinear form* in the precision
-//! nothing a consumer publishes is one competitor: "can we tell these two
+//! matrix's inverse — the variance of a contrast is `c^T L^-1 c`, and the
-//! apart" is a difference, "what was this round worth" is a sum. Combining
+//! covariance of two contrasts is `c^T L^-1 a`. None of them wants `L^-1 c`
-//! marginals means assuming the competitors are independent, and they are
+//! itself, which is what makes the shape here worth stating explicitly.
-//! correlated through every event they share — which is the mechanism the model
-//! exists to exploit.
 //!
-//! Measured on a five-competitor round robin, the exact correlation is +0.857,
+//! Writing the precision as `A = L L^T`,
-//! so `sqrt(sa^2 + sb^2)` overstates the width of a difference by 2.6x.
+//!
+//! ```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 factorised symmetric positive-definite matrix, reusable across queries.
-///
+pub(crate) struct Cholesky {
-/// `a` is row-major and is consumed as scratch.
+    /// Lower triangle of `L`, row-major `n * n`. The upper triangle is
-///
+    /// leftover scratch from the factorisation and is never read.
-/// Returns `None` if the matrix is not positive-definite, which for a precision
+    l: Vec<f64>,
-/// matrix means the model is improper — a competitor with no prior and no
+    n: usize,
-/// evidence.
+}
-pub(crate) fn solve_spd(mut a: Vec<f64>, b: &[f64]) -> Option<Vec<f64>> {
+
-    let n = b.len();
+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);
 
-    // 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,
+            // Explicit rather than `!(d > 0.0)`: a NaN pivot must fail here
-        // and a negated comparison would let it through as "not positive".
+            // too, and a negated comparison would let it through as "not
+            // positive".
             if d.is_nan() || d <= 0.0 {
                 return None;
             }
@@ -44,56 +64,89 @@ pub(crate) fn solve_spd(mut a: Vec<f64>, b: &[f64]) -> Option<Vec<f64>> {
             }
         }
 
-    // Forward substitution, then back substitution.
+        Some(Self { l: a, n })
-    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];
-        }
-        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];
     }
 
-    Some(z)
+    /// 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];
+        }
+        y
+    }
+}
+
+/// `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() {
+    fn reproduces_a_known_quadratic_form() {
-        // [[4, 1], [1, 3]] z = [1, 2]  =>  z = [1/11, 7/11]
+        let c = Cholesky::factor(vec![4.0, 1.0, 1.0, 3.0], 2).unwrap();
-        let a = vec![4.0, 1.0, 1.0, 3.0];
+        let y = c.whiten(&[1.0, 2.0]);
-        let z = solve_spd(a, &[1.0, 2.0]).unwrap();
+        assert!((bilinear(&y, &y) - 15.0 / 11.0).abs() < 1e-12);
-        assert!((z[0] - 1.0 / 11.0).abs() < 1e-12, "{z:?}");
-        assert!((z[1] - 7.0 / 11.0).abs() < 1e-12, "{z:?}");
     }
 
+    /// 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();
+            let y = c.whiten(&e);
-            assert!((z[i] - expected).abs() < 1e-12, "row {i}: {z:?}");
+            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!(Cholesky::factor(vec![1.0, 2.0, 2.0, 4.0], 2).is_none());
-        assert!(solve_spd(a, &[1.0, 1.0]).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};

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
+    /// event's factor onto one competitor. So a joint has to be rebuilt from
-    /// from the factor structure rather than recovered from the messages.
+    /// 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
+    /// observed outcomes. The means are already exact, so only the second
-    /// propagation gets those right even with cycles), so only the second
     /// moment needs rebuilding.
     ///
-    /// Returns the competitor order and the dense matrix in row-major order.
+    /// Each entry is a contrast and the observation variance that sits on it.
-    /// Only scored events contribute their factors exactly; see the caller.
+    /// Ranked events contribute nothing: their truncation factors are EP
-    pub(crate) fn joint_precision<D: Drift<T>>(
+    /// approximations that inference does not retain.
+    pub(crate) fn scored_contrasts<D: Drift<T>>(
         &self,
         agents: &CompetitorStore<T, D>,
-    ) -> (Vec<Index>, Vec<f64>) {
+    ) -> Vec<(Vec<(Index, f64)>, f64)> {
-        let order: Vec<Index> = self.skills.keys().collect();
+        let mut out = Vec::new();
-        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();
-        }
 
         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();
+            let mut order: Vec<usize> = (0..event.teams.len()).collect();
-            order_idx.sort_by(|&a, &b| {
+            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]);
-
+                let mut contrast: Vec<(Index, f64)> = Vec::new();
-                // 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 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 * agents[item.agent].rating.beta.powi(2);
-                        noise += w * w * beta * beta;
+                        contrast.push((item.agent, sign * w));
-                        *contrast.entry(row_of[&item.agent]).or_insert(0.0) += sign * w;
                     }
                 }
 
-                for (&i, &ci) in &contrast {
+                out.push((contrast, noise));
-                    for (&j, &cj) in &contrast {
-                        lambda[i * n + j] += ci * cj / 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/joint_handle.rs

@@ -0,0 +1,220 @@
+//! `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);
+}
+
+/// 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/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);
+}