chore: Release trueskill-tt version 0.1.1

Adds soft Gaussian-observation evidence on the per-pair diff variable,
enabling continuous score margins as a richer alternative to ranks.

Public API:
- `Outcome::Scored([scores])` (non-breaking enum extension under
  `#[non_exhaustive]`).
- `Game::scored(teams, outcome, options)` constructor parallel to
  `Game::ranked`.
- `EventBuilder::scores([...])` fluent helper.
- `HistoryBuilder::score_sigma(σ)` knob (default 1.0, validated > 0).
- `GameOptions::score_sigma`.
- `EventKind` re-exported from `lib.rs` (annotated `#[non_exhaustive]`).
- New `InferenceError::InvalidParameter { name, value }` variant.

Internals:
- `MarginFactor` (`factor/margin.rs`): Gaussian observation factor that
  closes in one EP step; cavity-cached log-evidence mirrors `TruncFactor`.
- `BuiltinFactor::Margin` dispatch arm.
- `DiffFactor` enum in `game.rs` lets `Game::likelihoods` and the new
  `likelihoods_scored` share the per-pair link abstraction.
- Per-event `EventKind { Ranked, Scored { score_sigma } }` routed through
  `TimeSlice::add_events`, `iteration_direct`, and `log_evidence`.

Tests: 88 lib + 27 integration (4 new in `tests/scored.rs`); existing
goldens byte-identical.  Bench: `benches/scored.rs` baseline ~960µs for
60 events × 20-player pool with default convergence.

Plan: docs/superpowers/plans/2026-04-27-t4-margin-factor.md
Spec item marked Done.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -2,6 +2,150 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased — T3 concurrency
+
+Adds rayon-backed parallel paths per Section 6 of
+`docs/superpowers/specs/2026-04-23-trueskill-engine-redesign-design.md`.
+
+### Breaking
+
+- `Send + Sync` bounds added to public traits: `Time`, `Drift<T>`,
+  `Observer<T>`, `Factor`, `Schedule`. All built-in impls satisfy these
+  via auto-derive, but downstream custom impls that aren't thread-safe
+  will need the bounds.
+
+### New
+
+- Opt-in `rayon` cargo feature. When enabled:
+  - Within-slice event iteration runs color-group events in parallel
+    via `par_iter_mut` (`TimeSlice::sweep_color_groups`).
+  - `History::learning_curves` computes per-slice posteriors in
+    parallel, merges sequentially in slice order.
+  - `History::log_evidence` / `log_evidence_for` use per-slice parallel
+    computation with deterministic sequential reduction (sum in slice
+    order) — bit-identical to the sequential baseline.
+- `ColorGroups` internal infrastructure with greedy graph coloring
+  (`src/color_group.rs`). Events sharing no `Index` go into the same
+  color group; events in the same group can run concurrently without
+  touching each other's skills.
+- `tests/determinism.rs` asserts bit-identical posteriors across
+  `RAYON_NUM_THREADS={1, 2, 4, 8}`.
+- `benches/history_converge.rs` measures end-to-end convergence on
+  three workload shapes.
+
+### Performance notes
+
+- Default build (no rayon): `Batch::iteration` 23.23 µs — no regression
+  vs T2.
+- With `--features rayon`:
+  - 500 events / 100 competitors / 10 per slice: 1.0× speedup.
+  - 2000 events / 200 competitors / 20 per slice: 1.0× speedup.
+  - 5000 events in one slice / 50k competitors: **1.3× speedup.**
+- The spec targeted >2× speedup on 8-core offline converge. This is
+  only achievable on workloads with many events-per-slice AND large
+  competitor pools. **Typical TrueSkill workloads (tens of events
+  per slice) do not materially benefit from T3's within-slice
+  parallelism** because rayon's task-spawn overhead dominates.
+- Cross-slice parallelism (dirty-bit slice skipping per spec Section
+  5) is the natural next step for real workload speedup — deferred
+  to a future tier.
+
+### Internals
+
+- The parallel path uses an `unsafe` block to concurrently write to
+  `SkillStore` from color-group-disjoint events. Soundness rests on
+  the color-group invariant (events in the same color touch no shared
+  `Index`), which is guaranteed by construction in
+  `TimeSlice::recompute_color_groups`. Sequential path unchanged.
+- `RAYON_THRESHOLD = 64` — color groups smaller than this fall back to
+  sequential iteration inside the parallel `sweep_color_groups` to
+  avoid rayon's task-spawn overhead.
+- Thread-local `ScratchArena` per rayon worker thread.
+
+## Unreleased — T2 new API surface
+
+Breaking: every renamed type and the new public API land together per
+`docs/superpowers/specs/2026-04-23-trueskill-engine-redesign-design.md`
+Section 7 "T2".
+
+### Breaking renames
+
+- `Batch` → `TimeSlice`
+- `Player` → `Rating` (and the `.player` field on `Competitor` is now `.rating`)
+- `Agent` → `Competitor`
+- `IndexMap` → `KeyTable`
+- `History` field `.batches` → `.time_slices`
+
+### New types
+
+- `Time` trait with `Untimed` ZST and `i64` impls (generic time axis).
+- `Drift<T: Time>` — generified from the old `Drift` trait.
+- `Event<T, K>`, `Team<K>`, `Member<K>` — typed bulk-ingest event shape.
+- `Outcome` (`#[non_exhaustive]`) — `Ranked(SmallVec<[u32; 4]>)` with convenience
+  constructors `winner`, `draw`, `ranking`. `Scored` lands in T4.
+- `Observer<T: Time>` trait + `NullObserver` ZST — structured progress callbacks.
+- `ConvergenceOptions`, `ConvergenceReport` — configuration and post-hoc summary.
+- `GameOptions`, `OwnedGame<T, D>` — ergonomic Game constructors without lifetime
+  gymnastics.
+- `factors` module — re-exports `Factor`, `BuiltinFactor`, `VarId`, `VarStore`,
+  `Schedule`, `EpsilonOrMax`, `ScheduleReport`, and the three built-in factor types
+  (`TeamSumFactor`, `RankDiffFactor`, `TruncFactor`) as public API.
+
+### New `History` API
+
+- Three-tier ingestion:
+  - Tier 1 (bulk): `add_events<I: IntoIterator<Item = Event<T, K>>>(events) -> Result`
+  - Tier 2 (one-off): `record_winner(&K, &K, T)`, `record_draw(&K, &K, T)`
+  - Tier 3 (fluent): `event(T).team([...]).weights([...]).ranking([...]).commit()`
+- `converge() -> Result<ConvergenceReport, InferenceError>` — replaces
+  `convergence(iters, eps, verbose)`.
+- `current_skill(&K)`, `learning_curve(&K)`, `learning_curves()` (now keyed on `K`).
+- `log_evidence()` zero-arg, `log_evidence_for(&[&K])`.
+- `predict_quality(&[&[&K]])`, `predict_outcome(&[&[&K]])` (2-team only in T2;
+  N-team deferred to T4).
+- `intern(&Q)` / `lookup(&Q)` expose the internal `KeyTable<K>` for power users.
+- `History<T, D, O, K>` is now fully generic with defaults
+  `<i64, ConstantDrift, NullObserver, &'static str>`.
+
+### New `Game` API
+
+- `Game::ranked(&[&[Rating]], Outcome, &GameOptions) -> Result<OwnedGame, _>`.
+- `Game::one_v_one(&Rating, &Rating, Outcome) -> Result<(Gaussian, Gaussian), _>`.
+- `Game::free_for_all(&[&Rating], Outcome, &GameOptions) -> Result<OwnedGame, _>`.
+- `Game::custom(...)` minimal escape hatch for user-defined factor graphs
+  (`#[doc(hidden)]` — full ergonomics in T4).
+- `Game::log_evidence()` and `OwnedGame::log_evidence()` accessors.
+
+### Errors
+
+- `InferenceError` now carries `MismatchedShape { kind, expected, got }`,
+  `InvalidProbability { value }`, `ConvergenceFailed { last_step, iterations }`,
+  and `NegativePrecision { pi }`. Shape and bounds validation at the API boundary
+  now returns `Err` rather than panicking.
+
+### Removed (breaking)
+
+- `History::convergence(iters, eps, verbose)` — use `converge()`.
+- `HistoryBuilder::gamma(f64)` — use `.drift(ConstantDrift(g))`.
+- `HistoryBuilder::time(bool)` and `History.time: bool` — use the `Time` type parameter.
+- The nested-`Vec<Vec<Vec<_>>>` public `add_events` signature —
+  use typed `add_events(iter)`.
+- `learning_curves_by_index()` — use `learning_curves()`.
+
+### Performance
+
+`Batch::iteration` bench: **21.36 µs** (T1 was 22.88 µs on the same hardware, a
+~7% improvement from the typed-path being slightly more direct). Gaussian
+operations unchanged.
+
+### Notes
+
+- `Time = Untimed` returns `elapsed_to → 0` — **behavior change** from the old
+  `time=false` mode, which implicitly generated `elapsed=1` per event via an
+  `i64::MAX` sentinel in `Agent.last_time`. Tests that relied on the old
+  `time=false` semantics now use `History::<i64, _>` with explicit
+  `1..=n` timestamps.
+
 ## 0.1.0 - 2026-04-23
 
 ### Features

CLAUDE.md

@@ -35,6 +35,7 @@ History  →  Batch[]  →  Game[]  →  teams/players
 - **`Player`** (`player.rs`) — static configuration: prior `Gaussian`, `beta` (performance noise), `gamma` (skill drift per time unit).
 - **`Gaussian`** (`gaussian.rs`) — core probability type. Stored as natural parameters (`pi = 1/sigma²`, `tau = mu/sigma²`). Arithmetic ops implement message multiplication/division in the factor graph.
 - **`message.rs`** — `TeamMessage` and `DiffMessage`: intermediate factor graph messages used inside `Game`.
+- **`MarginFactor`** (`factor/margin.rs`) — Gaussian observation factor on a diff variable; engaged by `Outcome::Scored`.
 - **`lib.rs`** — exports the public API (`Game`, `Gaussian`, `History`, `Player`) and standalone functions (`quality()`, `pdf()`, `cdf()`, `erfc()`). Also defines global defaults: `MU=0.0`, `SIGMA=6.0`, `BETA=1.0`, `GAMMA=0.03`, `P_DRAW=0.0`, `EPSILON=1e-6`, `ITERATIONS=30`.
 
 ### Key design points

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trueskill-tt"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2024"
 
 [lib]
@@ -14,10 +14,23 @@ harness = false
 name = "gaussian"
 harness = false
 
+[[bench]]
+name = "history_converge"
+harness = false
+
+[[bench]]
+name = "scored"
+harness = false
+
 [dependencies]
 approx = { version = "0.5.1", optional = true }
+rayon = { version = "1", optional = true }
 smallvec = "1"
 
+[features]
+approx = ["dep:approx"]
+rayon = ["dep:rayon"]
+
 [dev-dependencies]
 criterion = "0.5"
 plotters = { version = "0.3", default-features = false, features = ["svg_backend", "all_elements", "all_series"] }

README.md

@@ -71,6 +71,27 @@ let h = History::builder()
     .build();
 ```
 
+## Scored outcomes
+
+Use `Outcome::scores([...])` when you have continuous per-team scores rather
+than just ranks. Adjacent score margins flow into a `MarginFactor` that adds
+soft Gaussian evidence about the latent performance diff. Configure
+`HistoryBuilder::score_sigma(σ)` to control how much you trust the margins
+(smaller σ = more trust).
+
+```rust
+use trueskill_tt::{History, Outcome};
+
+let mut h = History::builder().score_sigma(2.0).build();
+h.event(1)
+    .team(["alice"])
+    .team(["bob"])
+    .scores([21.0, 9.0])
+    .commit()
+    .unwrap();
+h.converge().unwrap();
+```
+
 ## Todo
 
 - [x] Implement approx for Gaussian

benches/baseline.txt

@@ -65,3 +65,68 @@ Gaussian::pi_tau_combined 234.xx ps    (unchanged)
 # - Gaussian operations unchanged vs T0.
 # - All 53 tests pass. factor graph infrastructure (VarStore, Factor trait,
 #   BuiltinFactor, TruncFactor, EpsilonOrMax schedule) in place for T2.
+
+# After T2 (2026-04-24, same hardware)
+
+Batch::iteration           21.36 µs   (1.07× vs T1 22.88 µs — 7% improvement)
+Gaussian::add             218.97 ps    (unchanged)
+Gaussian::sub             218.58 ps    (unchanged)
+Gaussian::mul             218.59 ps    (unchanged)
+Gaussian::div             218.57 ps    (unchanged)
+Gaussian::pi              264.20 ps    (unchanged)
+Gaussian::tau             260.80 ps    (unchanged)
+
+# Notes:
+# - API-only tier; hot inference path unchanged. The 7% improvement on
+#   Batch::iteration likely comes from the typed add_events(iter) path
+#   being slightly more direct than the nested-Vec path it replaced
+#   (one less layer of composition construction per event).
+# - Public surface now matches spec Section 4:
+#     record_winner / record_draw / add_events(iter) / event(t).team().commit()
+#     converge() -> Result<ConvergenceReport, InferenceError>
+#     learning_curve(&K) / learning_curves() / current_skill(&K)
+#     log_evidence() / log_evidence_for(&[&K])
+#     predict_quality / predict_outcome
+#     Game::ranked / one_v_one / free_for_all / custom
+#     factors module (pub Factor/Schedule/VarStore/EpsilonOrMax/BuiltinFactor)
+# - Breaking type renames: Batch→TimeSlice, Player→Rating, Agent→Competitor,
+#   IndexMap→KeyTable.
+# - Generic over T: Time (default i64), D: Drift<T>, O: Observer<T>,
+#   K: Eq + Hash + Clone (default &'static str).
+# - Legacy removed: History::convergence(iters, eps, verbose),
+#   HistoryBuilder::gamma(), HistoryBuilder::time(bool), History::time field,
+#   learning_curves_by_index(), nested-Vec public add_events().
+# - 90 tests green: 68 lib + 10 api_shape + 6 game + 4 record_winner +
+#   2 equivalence.
+
+# After T3 (2026-04-24, same hardware)
+
+Batch::iteration (seq, no rayon)     23.23 µs   (matches T2 baseline; no regression)
+Batch::iteration (rayon, small slice) 24.57 µs   (within noise; small workloads pay rayon overhead)
+Gaussian::add                         236.62 ps  (unchanged)
+Gaussian::sub                         236.43 ps  (unchanged)
+Gaussian::mul                         237.05 ps  (unchanged)
+Gaussian::div                         236.07 ps  (unchanged)
+
+# End-to-end history_converge benchmark (Apple M5 Pro, RAYON_NUM_THREADS=auto):
+# workload                              seq      rayon    speedup
+# 500 events, 100 competitors, 10/slice 4.03 ms  4.24 ms  1.0x
+# 2000 events, 200 competitors, 20/slice 20.18 ms 19.82 ms 1.0x
+# 5000 events, 50000 competitors, 1 slice 11.88 ms 9.10 ms 1.3x
+#
+# Notes:
+# - T3's within-slice color-group parallelism only materializes a speedup
+#   when a slice holds many events with disjoint competitor sets. Typical
+#   TrueSkill workloads (tens of events per slice) don't show measurable
+#   benefit from rayon.
+# - The pre-revert SmallVec experiment hit 2x on the 5000-event workload
+#   but regressed sequential Batch::iteration by 28%. The tradeoff wasn't
+#   worth it for typical workloads — ShipVec<[_; 8]> inline size (1 KB per
+#   Game struct) hurt cache locality on the hot path.
+# - Cross-slice parallelism (dirty-bit slice skipping per spec Section 5)
+#   is the natural next step for realistic TrueSkill workloads and would
+#   deliver the spec's ~50-500x online-add speedup. Deferred to T4+.
+# - Determinism verified: tests/determinism.rs asserts bit-identical
+#   posteriors across RAYON_NUM_THREADS={1, 2, 4, 8}.
+# - Send + Sync bounds added on Time, Drift<T>, Observer<T>, Factor, Schedule.
+# - Rayon is opt-in via `--features rayon`. Default build is unchanged from T2.

benches/batch.rs

@@ -1,7 +1,7 @@
 use criterion::{Criterion, criterion_group, criterion_main};
 use trueskill_tt::{
-    BETA, Competitor, GAMMA, KeyTable, MU, P_DRAW, Rating, SIGMA, TimeSlice, drift::ConstantDrift,
-    gaussian::Gaussian, storage::CompetitorStore,
+    BETA, Competitor, EventKind, GAMMA, KeyTable, MU, P_DRAW, Rating, SIGMA, TimeSlice,
+    drift::ConstantDrift, gaussian::Gaussian, storage::CompetitorStore,
 };
 
 fn criterion_benchmark(criterion: &mut Criterion) {
@@ -33,8 +33,10 @@ fn criterion_benchmark(criterion: &mut Criterion) {
         weights.push(vec![vec![1.0], vec![1.0]]);
     }
 
+    let kinds = vec![EventKind::Ranked; composition.len()];
+
     let mut time_slice = TimeSlice::new(1, P_DRAW);
-    time_slice.add_events(composition, results, weights, &agents);
+    time_slice.add_events(composition, results, weights, kinds, &agents);
 
     criterion.bench_function("Batch::iteration", |b| {
         b.iter(|| time_slice.iteration(0, &agents))

benches/history_converge.rs

@@ -0,0 +1,116 @@
+//! End-to-end History::converge benchmark.
+//!
+//! Workload shapes designed to expose rayon's within-slice color-group
+//! parallelism. Events in the same color group are processed in parallel
+//! via direct-write with disjoint index sets (no data races). Color groups
+//! smaller than a threshold fall back to the sequential path to avoid
+//! rayon overhead on small workloads.
+//!
+//! On Apple M5 Pro, the P-core count (6) is the optimal thread count.
+//! The rayon thread pool is initialised to `min(P-cores, available)` to
+//! avoid scheduling onto the slower E-cores.
+//!
+//! ## Results (Apple M5 Pro, 2026-04-24, after SmallVec revert)
+//!
+//! | Workload                                    | Sequential  | Parallel   | Speedup |
+//! |---------------------------------------------|------------:|-----------:|--------:|
+//! | History::converge/500x100@10perslice        |     4.03 ms |    4.24 ms |   1.0×  |
+//! | History::converge/2000x200@20perslice       |    20.18 ms |   19.82 ms |   1.0×  |
+//! | History::converge/1v1-5000x50000@5000perslice|   11.88 ms |    9.10 ms |   1.3×  |
+//!
+//! T3 acceptance gate: ≥2× speedup on at least one workload — NOT achieved after revert.
+//! The SmallVec storage that enabled the 2× gate caused a +28% regression in the
+//! sequential Batch::iteration benchmark and was reverted. Small workloads still fall
+//! below the RAYON_THRESHOLD (64 events/color) and run sequentially with near-zero overhead.
+
+use criterion::{BatchSize, Criterion, criterion_group, criterion_main};
+use smallvec::smallvec;
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Event, History, Member, NullObserver, Outcome, Team,
+};
+
+fn build_history_1v1(
+    n_events: usize,
+    n_competitors: usize,
+    events_per_slice: usize,
+    seed: u64,
+) -> History<i64, ConstantDrift, NullObserver, String> {
+    let mut rng = seed;
+    let mut next = || {
+        rng = rng
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(1442695040888963407);
+        rng
+    };
+
+    let mut h = History::<i64, _, _, String>::builder_with_key()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .convergence(ConvergenceOptions {
+            max_iter: 30,
+            epsilon: 1e-6,
+        })
+        .build();
+
+    let mut events: Vec<Event<i64, String>> = Vec::with_capacity(n_events);
+    for ev_i in 0..n_events {
+        let a = (next() as usize) % n_competitors;
+        let mut b = (next() as usize) % n_competitors;
+        while b == a {
+            b = (next() as usize) % n_competitors;
+        }
+        events.push(Event {
+            time: (ev_i as i64 / events_per_slice as i64) + 1,
+            teams: smallvec![
+                Team::with_members([Member::new(format!("p{a}"))]),
+                Team::with_members([Member::new(format!("p{b}"))]),
+            ],
+            outcome: Outcome::winner((next() % 2) as u32, 2),
+        });
+    }
+    h.add_events(events).unwrap();
+    h
+}
+
+fn bench_converge(c: &mut Criterion) {
+    // Two original task workloads (small per-slice event count;
+    // fall below RAYON_THRESHOLD so sequential path runs — near-zero overhead).
+    c.bench_function("History::converge/500x100@10perslice", |b| {
+        b.iter_batched(
+            || build_history_1v1(500, 100, 10, 42),
+            |mut h| {
+                h.converge().unwrap();
+            },
+            BatchSize::SmallInput,
+        );
+    });
+
+    c.bench_function("History::converge/2000x200@20perslice", |b| {
+        b.iter_batched(
+            || build_history_1v1(2000, 200, 20, 42),
+            |mut h| {
+                h.converge().unwrap();
+            },
+            BatchSize::SmallInput,
+        );
+    });
+
+    // Large single-slice workload: 5000 events, 50000 competitors.
+    // All events in one slice → color-0 gets ~4900 disjoint events, well above
+    // the 64-event RAYON_THRESHOLD. 30 iterations × 1 slice = 30 sweeps, each
+    // parallelised across P-core threads. Shows ≥2× speedup.
+    c.bench_function("History::converge/1v1-5000x50000@5000perslice", |b| {
+        b.iter_batched(
+            || build_history_1v1(5000, 50000, 5000, 42),
+            |mut h| {
+                h.converge().unwrap();
+            },
+            BatchSize::SmallInput,
+        );
+    });
+}
+
+criterion_group!(benches, bench_converge);
+criterion_main!(benches);

benches/scored.rs

@@ -0,0 +1,38 @@
+use criterion::{Criterion, criterion_group, criterion_main};
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, Event, History, Member, Outcome, Team};
+
+fn bench_scored_history(c: &mut Criterion) {
+    c.bench_function("scored_history_60_events_30_iter", |bencher| {
+        bencher.iter(|| {
+            let mut h: History<i64, ConstantDrift, _, String> = History::builder_with_key()
+                .mu(25.0)
+                .sigma(25.0 / 3.0)
+                .beta(25.0 / 6.0)
+                .drift(ConstantDrift(0.03))
+                .score_sigma(2.0)
+                .build();
+
+            let mut events: Vec<Event<i64, String>> = Vec::with_capacity(60);
+            for i in 0..60 {
+                let a = format!("p{}", i % 20);
+                let b = format!("p{}", (i + 7) % 20);
+                let s_a = (i as f64 * 0.3).sin().abs() * 21.0;
+                let s_b = (i as f64 * 0.3).cos().abs() * 21.0;
+                events.push(Event {
+                    time: 1 + (i / 6) as i64,
+                    teams: smallvec![
+                        Team::with_members([Member::new(a)]),
+                        Team::with_members([Member::new(b)]),
+                    ],
+                    outcome: Outcome::scores([s_a, s_b]),
+                });
+            }
+            h.add_events(events).unwrap();
+            h.converge().unwrap();
+        });
+    });
+}
+
+criterion_group!(benches, bench_scored_history);
+criterion_main!(benches);

benches/scored_baseline.txt

@@ -0,0 +1,14 @@
+    Finished `bench` profile [optimized + debuginfo] target(s) in 0.02s
+     Running benches/scored.rs (target/release/deps/scored-988d1798504ff7d2)
+Gnuplot not found, using plotters backend
+Benchmarking scored_history_60_events_30_iter
+Benchmarking scored_history_60_events_30_iter: Warming up for 3.0000 s
+Benchmarking scored_history_60_events_30_iter: Collecting 100 samples in estimated 9.7418 s (10k iterations)
+Benchmarking scored_history_60_events_30_iter: Analyzing
+scored_history_60_events_30_iter
+                        time:   [959.36 µs 962.68 µs 966.13 µs]
+Found 11 outliers among 100 measurements (11.00%)
+  1 (1.00%) low mild
+  5 (5.00%) high mild
+  5 (5.00%) high severe
+

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

@@ -578,7 +578,7 @@ All renames and the new public API land together. No half-renamed intermediate s
 
 Each shipped independently after T3.
 
-- `MarginFactor` → enables `Outcome::Scored`.
+- `MarginFactor` → enables `Outcome::Scored`. **Done** (see `docs/superpowers/plans/2026-04-27-t4-margin-factor.md`).
 - `Damped` and `Residual` schedules.
 - `SynergyFactor`, `ScoreFactor` → same pattern when wanted.
 

examples/atp.rs

@@ -1,50 +1,61 @@
 use plotters::prelude::*;
+use smallvec::smallvec;
 use time::{Date, Month};
-use trueskill_tt::{History, KeyTable};
+use trueskill_tt::{Event, History, Member, Outcome, Team, drift::ConstantDrift};
 
 fn main() {
     let mut csv = csv::Reader::open("examples/atp.csv").unwrap();
 
-    let mut composition = Vec::new();
-    let mut results = Vec::new();
-    let mut times = Vec::new();
-
     let from = Date::from_calendar_date(1900, Month::January, 1).unwrap();
     let time_format = time::format_description::parse("[year]-[month]-[day]").unwrap();
 
-    let mut index_map = KeyTable::new();
+    let mut events: Vec<Event<i64, String>> = Vec::new();
 
     for row in csv.records() {
-        if &row["double"] == "t" {
-            let w1_id = index_map.get_or_create(&row["w1_id"]);
-            let w2_id = index_map.get_or_create(&row["w2_id"]);
-
-            let l1_id = index_map.get_or_create(&row["l1_id"]);
-            let l2_id = index_map.get_or_create(&row["l2_id"]);
-
-            composition.push(vec![vec![w1_id, w2_id], vec![l1_id, l2_id]]);
-        } else {
-            let w1_id = index_map.get_or_create(&row["w1_id"]);
-
-            let l1_id = index_map.get_or_create(&row["l1_id"]);
-
-            composition.push(vec![vec![w1_id], vec![l1_id]]);
-        }
-
-        results.push(vec![1.0, 0.0]);
-
         let date = Date::parse(&row["time_start"], &time_format).unwrap();
+        let time = (date - from).whole_days();
 
-        times.push((date - from).whole_days());
+        if &row["double"] == "t" {
+            events.push(Event {
+                time,
+                teams: smallvec![
+                    Team::with_members([
+                        Member::new(row["w1_id"].to_owned()),
+                        Member::new(row["w2_id"].to_owned()),
+                    ]),
+                    Team::with_members([
+                        Member::new(row["l1_id"].to_owned()),
+                        Member::new(row["l2_id"].to_owned()),
+                    ]),
+                ],
+                outcome: Outcome::winner(0, 2),
+            });
+        } else {
+            events.push(Event {
+                time,
+                teams: smallvec![
+                    Team::with_members([Member::new(row["w1_id"].to_owned())]),
+                    Team::with_members([Member::new(row["l1_id"].to_owned())]),
+                ],
+                outcome: Outcome::winner(0, 2),
+            });
+        }
     }
 
-    let mut hist = History::builder().sigma(1.6).gamma(0.036).build();
+    let mut hist: History<i64, _, _, String> = History::builder_with_key()
+        .sigma(1.6)
+        .drift(ConstantDrift(0.036))
+        .convergence(trueskill_tt::ConvergenceOptions {
+            max_iter: 10,
+            epsilon: 0.01,
+        })
+        .build();
 
-    hist.add_events(composition, results, times, vec![]);
-    hist.convergence(10, 0.01, true);
+    hist.add_events(events).unwrap();
+    hist.converge().unwrap();
 
     let players = [
-        ("aggasi", "a092", 38800),
+        ("aggasi", "a092", 38800i64),
         ("borg", "b058", 30300),
         ("connors", "c044", 31250),
         ("courier", "c243", 35750),
@@ -61,21 +72,16 @@ fn main() {
         ("wilander", "w023", 32600),
     ];
 
-    let curves = hist.learning_curves();
-
     let mut x_spec = (f64::MAX, f64::MIN);
     let mut y_spec = (f64::MAX, f64::MIN);
 
-    for (id, cutoff) in players
-        .iter()
-        .map(|&(_, id, cutoff)| (index_map.get_or_create(id), cutoff))
-    {
-        for (ts, gs) in &curves[&id] {
-            if *ts >= cutoff {
+    for &(_, id, cutoff) in &players {
+        for (ts, gs) in hist.learning_curve(id) {
+            if ts >= cutoff {
                 continue;
             }
 
-            let ts = *ts as f64;
+            let ts = ts as f64;
 
             if ts < x_spec.0 {
                 x_spec.0 = ts;
@@ -111,24 +117,19 @@ fn main() {
 
     chart.configure_mesh().draw().unwrap();
 
-    for (idx, (player, id, cutoff)) in players
-        .iter()
-        .map(|&(player, id, cutoff)| (player, index_map.get_or_create(id), cutoff))
-        .enumerate()
-    {
+    for (idx, &(player, id, cutoff)) in players.iter().enumerate() {
         let mut data = Vec::new();
         let mut upper = Vec::new();
         let mut lower = Vec::new();
 
-        for (ts, gs) in curves[&id].iter() {
-            if *ts >= cutoff {
+        for (ts, gs) in hist.learning_curve(id) {
+            if ts >= cutoff {
                 continue;
             }
 
-            data.push((*ts as f64, gs.mu()));
-
-            upper.push((*ts as f64, gs.mu() + gs.sigma()));
-            lower.push((*ts as f64, gs.mu() - gs.sigma()));
+            data.push((ts as f64, gs.mu()));
+            upper.push((ts as f64, gs.mu() + gs.sigma()));
+            lower.push((ts as f64, gs.mu() - gs.sigma()));
         }
 
         let color = Palette99::pick(idx);

examples/scored.rs

@@ -0,0 +1,59 @@
+//! Worked example: continuous-score outcomes via `Outcome::Scored`.
+//!
+//! Three players play a small round-robin where the score margin matters,
+//! not just who won. We show how `score_sigma` controls how much weight
+//! the engine places on the observed margin.
+//!
+//! Run with: `cargo run --example scored --release`
+
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, Event, History, Member, Outcome, Team};
+
+fn main() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(0.03))
+        .score_sigma(2.0) // tune to data; smaller = trust margins more
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![
+        Event {
+            time: 1,
+            teams: smallvec![
+                Team::with_members([Member::new("alice")]),
+                Team::with_members([Member::new("bob")]),
+            ],
+            outcome: Outcome::scores([21.0, 9.0]),
+        },
+        Event {
+            time: 2,
+            teams: smallvec![
+                Team::with_members([Member::new("bob")]),
+                Team::with_members([Member::new("carol")]),
+            ],
+            outcome: Outcome::scores([21.0, 18.0]),
+        },
+        Event {
+            time: 3,
+            teams: smallvec![
+                Team::with_members([Member::new("alice")]),
+                Team::with_members([Member::new("carol")]),
+            ],
+            outcome: Outcome::scores([21.0, 21.0]),
+        },
+    ];
+    h.add_events(events).unwrap();
+
+    let report = h.converge().unwrap();
+    println!(
+        "converged={}, iterations={}, log_evidence={:.4}",
+        report.converged, report.iterations, report.log_evidence
+    );
+
+    for who in &["alice", "bob", "carol"] {
+        let s = h.current_skill(who).unwrap();
+        println!("{:>6}: mu={:>7.3}  sigma={:.3}", who, s.mu(), s.sigma());
+    }
+}

src/color_group.rs

@@ -0,0 +1,158 @@
+//! Greedy graph coloring for within-slice event independence.
+//!
+//! Events sharing no `Index` can be processed in parallel under async-EP
+//! semantics. This module partitions a list of events into "colors" such
+//! that events of the same color touch disjoint index sets.
+//!
+//! The algorithm is greedy: for each event in ingestion order, place it in
+//! the lowest-numbered color whose existing members share no `Index`. If
+//! no existing color accepts the event, open a new color.
+//!
+//! Complexity: O(n × c × m) where n is events, c is colors (small, ≤ 5 in
+//! practice), and m is average team size.
+
+use std::collections::HashSet;
+
+use crate::Index;
+
+/// Partition of event indices into color groups.
+///
+/// Each inner `Vec<usize>` holds the indices (into the original events
+/// array) of events assigned to one color. Colors are iterated in ascending
+/// order by convention.
+#[derive(Clone, Debug, Default)]
+pub(crate) struct ColorGroups {
+    pub(crate) groups: Vec<Vec<usize>>,
+}
+
+impl ColorGroups {
+    #[allow(dead_code)]
+    pub(crate) fn new() -> Self {
+        Self::default()
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn n_colors(&self) -> usize {
+        self.groups.len()
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn is_empty(&self) -> bool {
+        self.groups.is_empty()
+    }
+
+    /// Total event count across all colors.
+    #[allow(dead_code)]
+    pub(crate) fn total_events(&self) -> usize {
+        self.groups.iter().map(|g| g.len()).sum()
+    }
+
+    /// Contiguous index range for one color after events have been reordered
+    /// into color-contiguous positions by `TimeSlice::recompute_color_groups`.
+    #[allow(dead_code)]
+    pub(crate) fn color_range(&self, color_idx: usize) -> std::ops::Range<usize> {
+        let group = &self.groups[color_idx];
+        if group.is_empty() {
+            return 0..0;
+        }
+        let start = *group.first().unwrap();
+        let end = *group.last().unwrap() + 1;
+        start..end
+    }
+}
+
+/// Compute color groups greedily.
+///
+/// `index_set(ev_idx)` yields, for each event index, the iterator of
+/// `Index` values that event touches. The returned `ColorGroups` has one
+/// inner `Vec<usize>` per color, containing event indices in the order
+/// they were assigned.
+#[allow(dead_code)]
+pub(crate) fn color_greedy<I, F>(n_events: usize, index_set: F) -> ColorGroups
+where
+    F: Fn(usize) -> I,
+    I: IntoIterator<Item = Index>,
+{
+    let mut groups: Vec<Vec<usize>> = Vec::new();
+    let mut members: Vec<HashSet<Index>> = Vec::new();
+
+    for ev_idx in 0..n_events {
+        let ev_members: HashSet<Index> = index_set(ev_idx).into_iter().collect();
+        // Find first color whose member-set is disjoint from this event's indices.
+        let chosen = members.iter().position(|m| m.is_disjoint(&ev_members));
+        let color_idx = match chosen {
+            Some(c) => c,
+            None => {
+                groups.push(Vec::new());
+                members.push(HashSet::new());
+                groups.len() - 1
+            }
+        };
+        groups[color_idx].push(ev_idx);
+        members[color_idx].extend(ev_members);
+    }
+
+    ColorGroups { groups }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn idx(i: usize) -> Index {
+        Index::from(i)
+    }
+
+    #[test]
+    fn single_event_gets_one_color() {
+        let cg = color_greedy(1, |_| vec![idx(0), idx(1)]);
+        assert_eq!(cg.n_colors(), 1);
+        assert_eq!(cg.groups[0], vec![0]);
+    }
+
+    #[test]
+    fn disjoint_events_share_a_color() {
+        let cg = color_greedy(2, |i| match i {
+            0 => vec![idx(0), idx(1)],
+            1 => vec![idx(2), idx(3)],
+            _ => unreachable!(),
+        });
+        assert_eq!(cg.n_colors(), 1);
+        assert_eq!(cg.groups[0], vec![0, 1]);
+    }
+
+    #[test]
+    fn overlapping_events_need_separate_colors() {
+        let cg = color_greedy(2, |i| match i {
+            0 => vec![idx(0), idx(1)],
+            1 => vec![idx(1), idx(2)],
+            _ => unreachable!(),
+        });
+        assert_eq!(cg.n_colors(), 2);
+        assert_eq!(cg.groups[0], vec![0]);
+        assert_eq!(cg.groups[1], vec![1]);
+    }
+
+    #[test]
+    fn three_events_two_colors() {
+        // Event 0: {0, 1}; event 1: {2, 3}; event 2: {0, 2}.
+        // Greedy: ev0→c0, ev1→c0 (disjoint), ev2 overlaps both→c1.
+        let cg = color_greedy(3, |i| match i {
+            0 => vec![idx(0), idx(1)],
+            1 => vec![idx(2), idx(3)],
+            2 => vec![idx(0), idx(2)],
+            _ => unreachable!(),
+        });
+        assert_eq!(cg.n_colors(), 2);
+        assert_eq!(cg.groups[0], vec![0, 1]);
+        assert_eq!(cg.groups[1], vec![2]);
+    }
+
+    #[test]
+    fn total_events_counts_correctly() {
+        let cg = color_greedy(4, |_| vec![idx(0)]);
+        // All events touch index 0 → 4 distinct colors.
+        assert_eq!(cg.n_colors(), 4);
+        assert_eq!(cg.total_events(), 4);
+    }
+}

src/convergence.rs

@@ -0,0 +1,31 @@
+//! Convergence configuration and reporting.
+
+use std::time::Duration;
+
+use smallvec::SmallVec;
+
+#[derive(Clone, Copy, Debug)]
+pub struct ConvergenceOptions {
+    pub max_iter: usize,
+    pub epsilon: f64,
+}
+
+impl Default for ConvergenceOptions {
+    fn default() -> Self {
+        Self {
+            max_iter: crate::ITERATIONS,
+            epsilon: crate::EPSILON,
+        }
+    }
+}
+
+/// Post-hoc summary of a `History::converge` call.
+#[derive(Clone, Debug)]
+pub struct ConvergenceReport {
+    pub iterations: usize,
+    pub final_step: (f64, f64),
+    pub log_evidence: f64,
+    pub converged: bool,
+    pub per_iteration_time: SmallVec<[Duration; 32]>,
+    pub slices_skipped: usize,
+}

src/drift.rs

@@ -6,7 +6,7 @@ use crate::time::Time;
 ///
 /// Generic over `T: Time` so seasonal or calendar-aware drift is expressible
 /// without going through `i64`.
-pub trait Drift<T: Time>: Copy + Debug {
+pub trait Drift<T: Time>: Copy + Debug + Send + Sync {
     /// Variance added to the skill prior for elapsed time `from -> to`.
     ///
     /// Called with `from <= to`; returning zero means no drift accumulates.

src/error.rs

@@ -2,12 +2,50 @@ use std::fmt;
 
 #[derive(Debug, Clone, PartialEq)]
 pub enum InferenceError {
+    /// Expected and actual lengths of some array-shaped input differ.
+    MismatchedShape {
+        kind: &'static str,
+        expected: usize,
+        got: usize,
+    },
+    /// A probability value is outside `[0, 1]`.
+    InvalidProbability { value: f64 },
+    /// A scalar parameter is outside its valid range.
+    InvalidParameter { name: &'static str, value: f64 },
+    /// Convergence exceeded `max_iter` without falling below `epsilon`.
+    ConvergenceFailed {
+        last_step: (f64, f64),
+        iterations: usize,
+    },
+    /// Negative precision: a Gaussian with `pi < 0` slipped into an API call.
     NegativePrecision { pi: f64 },
 }
 
 impl fmt::Display for InferenceError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
+            Self::MismatchedShape {
+                kind,
+                expected,
+                got,
+            } => {
+                write!(f, "{kind}: expected length {expected}, got {got}")
+            }
+            Self::InvalidProbability { value } => {
+                write!(f, "probability must be in [0, 1]; got {value}")
+            }
+            Self::InvalidParameter { name, value } => {
+                write!(f, "{name} is invalid: {value}")
+            }
+            Self::ConvergenceFailed {
+                last_step,
+                iterations,
+            } => {
+                write!(
+                    f,
+                    "convergence failed after {iterations} iterations; last step = {last_step:?}"
+                )
+            }
             Self::NegativePrecision { pi } => {
                 write!(f, "precision must be non-negative; got {pi}")
             }

src/event_builder.rs

@@ -0,0 +1,100 @@
+use smallvec::SmallVec;
+
+use crate::{
+    InferenceError, Outcome,
+    drift::Drift,
+    event::{Event, Member, Team},
+    history::History,
+    observer::Observer,
+    time::Time,
+};
+
+pub struct EventBuilder<'h, T, D, O, K>
+where
+    T: Time,
+    D: Drift<T>,
+    O: Observer<T>,
+    K: Eq + std::hash::Hash + Clone,
+{
+    history: &'h mut History<T, D, O, K>,
+    event: Event<T, K>,
+    current_team_idx: Option<usize>,
+}
+
+impl<'h, T, D, O, K> EventBuilder<'h, T, D, O, K>
+where
+    T: Time,
+    D: Drift<T>,
+    O: Observer<T>,
+    K: Eq + std::hash::Hash + Clone,
+{
+    pub(crate) fn new(history: &'h mut History<T, D, O, K>, time: T) -> Self {
+        Self {
+            history,
+            event: Event {
+                time,
+                teams: SmallVec::new(),
+                outcome: Outcome::Ranked(SmallVec::new()),
+            },
+            current_team_idx: None,
+        }
+    }
+
+    /// Add a team by its member keys (weight 1.0 each, no prior overrides).
+    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 });
+        self.current_team_idx = Some(self.event.teams.len() - 1);
+        self
+    }
+
+    /// Set per-member weights for the most recently added team.
+    ///
+    /// Panics in debug builds if called before `.team(...)` or if the length
+    /// doesn't match the team's member count.
+    pub fn weights<I: IntoIterator<Item = f64>>(mut self, weights: I) -> Self {
+        let idx = self
+            .current_team_idx
+            .expect(".weights(...) called before any .team(...)");
+        let ws: Vec<f64> = weights.into_iter().collect();
+        let team = &mut self.event.teams[idx];
+        debug_assert_eq!(
+            ws.len(),
+            team.members.len(),
+            "weights length must match team size"
+        );
+        for (m, w) in team.members.iter_mut().zip(ws) {
+            m.weight = w;
+        }
+        self
+    }
+
+    /// Set explicit ranks per team (length must equal number of teams).
+    pub fn ranking<I: IntoIterator<Item = u32>>(mut self, ranks: I) -> Self {
+        self.event.outcome = Outcome::ranking(ranks);
+        self
+    }
+
+    /// Set explicit per-team continuous scores; higher = better.
+    pub fn scores<I: IntoIterator<Item = f64>>(mut self, scores: I) -> Self {
+        self.event.outcome = crate::Outcome::scores(scores);
+        self
+    }
+
+    /// Mark team `winner_idx` as winner; others tied for last.
+    pub fn winner(mut self, winner_idx: u32) -> Self {
+        self.event.outcome = Outcome::winner(winner_idx, self.event.teams.len() as u32);
+        self
+    }
+
+    /// All teams tied.
+    pub fn draw(mut self) -> Self {
+        self.event.outcome = Outcome::draw(self.event.teams.len() as u32);
+        self
+    }
+
+    /// Commit the event to the history.
+    pub fn commit(self) -> Result<(), InferenceError> {
+        self.history.add_events(std::iter::once(self.event))
+    }
+}

src/factor/margin.rs

@@ -0,0 +1,123 @@
+use crate::{
+    N_INF,
+    factor::{Factor, VarId, VarStore},
+    gaussian::Gaussian,
+    pdf,
+};
+
+/// Gaussian observation factor on a diff variable.
+///
+/// Encodes the soft evidence `m_obs ~ N(diff, sigma²)`. The outgoing message
+/// to `diff` is the constant `N(m_obs, sigma²)`, so this factor converges in a
+/// single propagation: subsequent calls return a zero delta.
+#[derive(Debug)]
+pub struct MarginFactor {
+    pub diff: VarId,
+    pub m_obs: f64,
+    pub sigma: f64,
+    pub(crate) msg: Gaussian,
+    pub(crate) evidence_cached: Option<f64>,
+}
+
+impl MarginFactor {
+    pub fn new(diff: VarId, m_obs: f64, sigma: f64) -> Self {
+        debug_assert!(sigma > 0.0, "score sigma must be positive");
+        Self {
+            diff,
+            m_obs,
+            sigma,
+            msg: N_INF,
+            evidence_cached: None,
+        }
+    }
+}
+
+impl Factor for MarginFactor {
+    fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64) {
+        let marginal = vars.get(self.diff);
+        let cavity = marginal / self.msg;
+
+        if self.evidence_cached.is_none() {
+            self.evidence_cached = Some(cavity_evidence(cavity, self.m_obs, self.sigma));
+        }
+
+        let new_msg = Gaussian::from_ms(self.m_obs, self.sigma);
+        let new_marginal = cavity * new_msg;
+        let old_msg = self.msg;
+        self.msg = new_msg;
+        vars.set(self.diff, new_marginal);
+
+        old_msg.delta(new_msg)
+    }
+
+    fn log_evidence(&self, _vars: &VarStore) -> f64 {
+        self.evidence_cached.unwrap_or(1.0).ln()
+    }
+}
+
+fn cavity_evidence(cavity: Gaussian, m_obs: f64, sigma: f64) -> f64 {
+    let combined_sigma = (cavity.sigma().powi(2) + sigma.powi(2)).sqrt();
+    pdf(m_obs, cavity.mu(), combined_sigma)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn first_propagate_writes_tilted_marginal() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let mut f = MarginFactor::new(diff, 5.0, 1.0);
+
+        f.propagate(&mut vars);
+
+        let result = vars.get(diff);
+        // pi = 1/36 + 1 ≈ 1.027778; tau = 0 + 5 = 5
+        // mu = 5 / 1.027778 ≈ 4.864865; sigma = 1/sqrt(1.027778) ≈ 0.986394
+        assert!((result.mu() - 4.864864864864865).abs() < 1e-12);
+        assert!((result.sigma() - 0.986393923832144).abs() < 1e-12);
+    }
+
+    #[test]
+    fn converges_in_one_step() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let mut f = MarginFactor::new(diff, 5.0, 1.0);
+
+        f.propagate(&mut vars);
+        let (dmu, dsig) = f.propagate(&mut vars);
+        assert!(
+            dmu < 1e-12,
+            "expected ~0 delta on second propagate, got {dmu}"
+        );
+        assert!(dsig < 1e-12);
+    }
+
+    #[test]
+    fn evidence_cached_on_first_propagate() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let mut f = MarginFactor::new(diff, 5.0, 1.0);
+        assert!(f.evidence_cached.is_none());
+
+        f.propagate(&mut vars);
+        let z = f.evidence_cached.unwrap();
+        // pdf(5, 0, sqrt(37)) ≈ 0.046783
+        assert!((z - 0.04678300292616668).abs() < 1e-10);
+
+        // Subsequent propagations don't change it.
+        f.propagate(&mut vars);
+        assert_eq!(f.evidence_cached.unwrap(), z);
+    }
+
+    #[test]
+    fn log_evidence_matches_cached_ln() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let mut f = MarginFactor::new(diff, 5.0, 1.0);
+        f.propagate(&mut vars);
+        let logz = f.log_evidence(&vars);
+        assert!((logz - (-3.062235327364623)).abs() < 1e-10);
+    }
+}

src/factor/mod.rs

@@ -7,44 +7,46 @@ use crate::gaussian::Gaussian;
 /// Variables hold the current Gaussian marginal and are owned by exactly one
 /// `VarStore`. `VarId` is meaningful only within its owning store.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
-pub(crate) struct VarId(pub(crate) u32);
+pub struct VarId(pub u32);
 
 /// Flat storage of variable marginals.
 ///
 /// Variables are allocated by `alloc()` and accessed by `VarId`. The store is
-/// reused across `Game::new` calls (it lives in the `ScratchArena`); call
+/// reused across `Game::ranked_with_arena` calls (it lives in the `ScratchArena`); call
 /// `clear()` before reuse.
 #[derive(Debug, Default)]
-pub(crate) struct VarStore {
+pub struct VarStore {
     pub(crate) marginals: Vec<Gaussian>,
 }
 
 impl VarStore {
-    #[allow(dead_code)]
-    pub(crate) fn new() -> Self {
+    pub fn new() -> Self {
         Self::default()
     }
 
-    pub(crate) fn clear(&mut self) {
+    pub fn clear(&mut self) {
         self.marginals.clear();
     }
 
-    #[allow(dead_code)]
-    pub(crate) fn len(&self) -> usize {
+    pub fn len(&self) -> usize {
         self.marginals.len()
     }
 
-    pub(crate) fn alloc(&mut self, init: Gaussian) -> VarId {
+    pub fn is_empty(&self) -> bool {
+        self.marginals.is_empty()
+    }
+
+    pub fn alloc(&mut self, init: Gaussian) -> VarId {
         let id = VarId(self.marginals.len() as u32);
         self.marginals.push(init);
         id
     }
 
-    pub(crate) fn get(&self, id: VarId) -> Gaussian {
+    pub fn get(&self, id: VarId) -> Gaussian {
         self.marginals[id.0 as usize]
     }
 
-    pub(crate) fn set(&mut self, id: VarId, g: Gaussian) {
+    pub fn set(&mut self, id: VarId, g: Gaussian) {
         self.marginals[id.0 as usize] = g;
     }
 }
@@ -54,7 +56,7 @@ impl VarStore {
 /// Factors hold their own outgoing messages and propagate them by reading
 /// connected variable marginals from a `VarStore` and writing back updated
 /// marginals.
-pub(crate) trait Factor {
+pub trait Factor: Send + Sync {
     /// Update outgoing messages and write back to the var store.
     ///
     /// Returns the max delta `(|Δmu|, |Δsigma|)` across writes this
@@ -62,7 +64,6 @@ pub(crate) trait Factor {
     fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64);
 
     /// Optional log-evidence contribution. Default 0.0 (no contribution).
-    #[allow(dead_code)]
     fn log_evidence(&self, _vars: &VarStore) -> f64 {
         0.0
     }
@@ -73,11 +74,11 @@ pub(crate) trait Factor {
 /// Using an enum instead of `Box<dyn Factor>` keeps factor data inline and
 /// avoids virtual-call overhead in the hot inference loop.
 #[derive(Debug)]
-#[allow(dead_code)]
-pub(crate) enum BuiltinFactor {
+pub enum BuiltinFactor {
     TeamSum(team_sum::TeamSumFactor),
     RankDiff(rank_diff::RankDiffFactor),
     Trunc(trunc::TruncFactor),
+    Margin(margin::MarginFactor),
 }
 
 impl Factor for BuiltinFactor {
@@ -86,20 +87,23 @@ impl Factor for BuiltinFactor {
             Self::TeamSum(f) => f.propagate(vars),
             Self::RankDiff(f) => f.propagate(vars),
             Self::Trunc(f) => f.propagate(vars),
+            Self::Margin(f) => f.propagate(vars),
         }
     }
 
     fn log_evidence(&self, vars: &VarStore) -> f64 {
         match self {
             Self::Trunc(f) => f.log_evidence(vars),
+            Self::Margin(f) => f.log_evidence(vars),
             _ => 0.0,
         }
     }
 }
 
-pub(crate) mod rank_diff;
-pub(crate) mod team_sum;
-pub(crate) mod trunc;
+pub mod margin;
+pub mod rank_diff;
+pub mod team_sum;
+pub mod trunc;
 
 #[cfg(test)]
 mod tests {
@@ -145,4 +149,20 @@ mod tests {
         assert_eq!(store.len(), 0);
         assert_eq!(store.marginals.capacity(), cap);
     }
+
+    #[test]
+    fn builtin_factor_dispatches_to_margin() {
+        use super::margin::MarginFactor;
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let mut f = BuiltinFactor::Margin(MarginFactor::new(diff, 5.0, 1.0));
+
+        f.propagate(&mut vars);
+
+        let result = vars.get(diff);
+        assert!((result.mu() - 4.864864864864865).abs() < 1e-12);
+
+        let logz = f.log_evidence(&vars);
+        assert!((logz - (-3.062235327364623)).abs() < 1e-10);
+    }
 }

src/factor/rank_diff.rs

@@ -13,11 +13,10 @@ use crate::factor::{Factor, VarId, VarStore};
 /// effectively replaced on each propagation. The TruncFactor on the same diff
 /// var holds the EP-divide message that produces the cavity.
 #[derive(Debug)]
-#[allow(dead_code)]
-pub(crate) struct RankDiffFactor {
-    pub(crate) team_a: VarId,
-    pub(crate) team_b: VarId,
-    pub(crate) diff: VarId,
+pub struct RankDiffFactor {
+    pub team_a: VarId,
+    pub team_b: VarId,
+    pub diff: VarId,
 }
 
 impl Factor for RankDiffFactor {

src/factor/team_sum.rs

@@ -10,10 +10,9 @@ use crate::{
 /// already with beta² noise added via `Rating::performance()`). The factor
 /// runs once per game and writes the weighted sum to the output var.
 #[derive(Debug)]
-#[allow(dead_code)]
-pub(crate) struct TeamSumFactor {
-    pub(crate) inputs: Vec<(Gaussian, f64)>,
-    pub(crate) out: VarId,
+pub struct TeamSumFactor {
+    pub inputs: Vec<(Gaussian, f64)>,
+    pub out: VarId,
 }
 
 impl Factor for TeamSumFactor {

src/factor/trunc.rs

@@ -11,10 +11,10 @@ use crate::{
 /// Stores its outgoing message to the diff variable so the cavity computation
 /// produces the correct EP message on each propagation.
 #[derive(Debug)]
-pub(crate) struct TruncFactor {
-    pub(crate) diff: VarId,
-    pub(crate) margin: f64,
-    pub(crate) tie: bool,
+pub struct TruncFactor {
+    pub diff: VarId,
+    pub margin: f64,
+    pub tie: bool,
     /// Outgoing message to the diff variable (initial: N_INF, the EP identity).
     pub(crate) msg: Gaussian,
     /// Cached evidence (linear, not log) computed from the cavity on first propagation.
@@ -22,7 +22,7 @@ pub(crate) struct TruncFactor {
 }
 
 impl TruncFactor {
-    pub(crate) fn new(diff: VarId, margin: f64, tie: bool) -> Self {
+    pub fn new(diff: VarId, margin: f64, tie: bool) -> Self {
         Self {
             diff,
             margin,

src/factors.rs

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

src/game.rs

@@ -5,13 +5,146 @@ use crate::{
     arena::ScratchArena,
     compute_margin,
     drift::Drift,
-    factor::{Factor, trunc::TruncFactor},
+    factor::{VarId, margin::MarginFactor, trunc::TruncFactor},
     gaussian::Gaussian,
     rating::Rating,
     time::Time,
     tuple_gt, tuple_max,
 };
 
+/// Per-adjacent-pair link factor in the game's diff chain.
+///
+/// `Trunc` is used for `Outcome::Ranked` (rank-based truncation).
+/// `Margin` is used for `Outcome::Scored` (Gaussian observation on the diff).
+#[derive(Debug)]
+pub(crate) enum DiffFactor {
+    Trunc(TruncFactor),
+    Margin(MarginFactor),
+}
+
+impl DiffFactor {
+    pub(crate) fn diff(&self) -> VarId {
+        match self {
+            Self::Trunc(f) => f.diff,
+            Self::Margin(f) => f.diff,
+        }
+    }
+
+    pub(crate) fn msg(&self) -> Gaussian {
+        match self {
+            Self::Trunc(f) => f.msg,
+            Self::Margin(f) => f.msg,
+        }
+    }
+
+    pub(crate) fn evidence(&self) -> f64 {
+        match self {
+            Self::Trunc(f) => f.evidence_cached.unwrap_or(1.0),
+            Self::Margin(f) => f.evidence_cached.unwrap_or(1.0),
+        }
+    }
+
+    pub(crate) fn propagate(&mut self, vars: &mut crate::factor::VarStore) -> (f64, f64) {
+        use crate::factor::Factor;
+        match self {
+            Self::Trunc(f) => f.propagate(vars),
+            Self::Margin(f) => f.propagate(vars),
+        }
+    }
+}
+
+/// Per-game inference options.
+///
+/// `p_draw` and `convergence` apply to ranked outcomes (`Game::ranked`).
+/// `score_sigma` applies only to scored outcomes (`Game::scored`); it controls
+/// how much the engine trusts the observed score margin (smaller σ = more trust).
+#[derive(Clone, Copy, Debug)]
+pub struct GameOptions {
+    pub p_draw: f64,
+    pub score_sigma: f64,
+    pub convergence: crate::ConvergenceOptions,
+}
+
+impl Default for GameOptions {
+    fn default() -> Self {
+        Self {
+            p_draw: crate::P_DRAW,
+            score_sigma: 1.0,
+            convergence: crate::ConvergenceOptions::default(),
+        }
+    }
+}
+
+/// Owned variant of `Game` returned by public constructors.
+///
+/// Unlike `Game<'a, T, D>` (which borrows its result/weights slices from
+/// History's internal state), `OwnedGame<T, D>` owns its inputs so it can
+/// be returned freely from public constructors.
+#[derive(Debug)]
+#[allow(dead_code)]
+pub struct OwnedGame<T: Time, D: Drift<T>> {
+    teams: Vec<Vec<Rating<T, D>>>,
+    result: Vec<f64>,
+    weights: Vec<Vec<f64>>,
+    p_draw: f64,
+    pub(crate) likelihoods: Vec<Vec<Gaussian>>,
+    pub(crate) evidence: f64,
+}
+
+impl<T: Time, D: Drift<T>> OwnedGame<T, D> {
+    pub(crate) fn new(
+        teams: Vec<Vec<Rating<T, D>>>,
+        result: Vec<f64>,
+        weights: Vec<Vec<f64>>,
+        p_draw: f64,
+    ) -> Self {
+        let mut arena = ScratchArena::new();
+        let g = Game::ranked_with_arena(teams.clone(), &result, &weights, p_draw, &mut arena);
+        let likelihoods = g.likelihoods;
+        let evidence = g.evidence;
+        Self {
+            teams,
+            result,
+            weights,
+            p_draw,
+            likelihoods,
+            evidence,
+        }
+    }
+
+    pub(crate) fn new_scored(
+        teams: Vec<Vec<Rating<T, D>>>,
+        scores: Vec<f64>,
+        weights: Vec<Vec<f64>>,
+        score_sigma: f64,
+    ) -> Self {
+        let mut arena = ScratchArena::new();
+        let g = Game::scored_with_arena(teams.clone(), &scores, &weights, score_sigma, &mut arena);
+        let likelihoods = g.likelihoods;
+        let evidence = g.evidence;
+        Self {
+            teams,
+            result: scores,
+            weights,
+            p_draw: 0.0,
+            likelihoods,
+            evidence,
+        }
+    }
+
+    pub fn posteriors(&self) -> Vec<Vec<Gaussian>> {
+        self.likelihoods
+            .iter()
+            .zip(self.teams.iter())
+            .map(|(l, t)| l.iter().zip(t.iter()).map(|(&l, r)| l * r.prior).collect())
+            .collect()
+    }
+
+    pub fn log_evidence(&self) -> f64 {
+        self.evidence.ln()
+    }
+}
+
 #[derive(Debug)]
 pub struct Game<'a, T: Time = i64, D: Drift<T> = crate::drift::ConstantDrift> {
     teams: Vec<Vec<Rating<T, D>>>,
@@ -23,7 +156,7 @@ pub struct Game<'a, T: Time = i64, D: Drift<T> = crate::drift::ConstantDrift> {
 }
 
 impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
-    pub fn new(
+    pub(crate) fn ranked_with_arena(
         teams: Vec<Vec<Rating<T, D>>>,
         result: &'a [f64],
         weights: &'a [Vec<f64>],
@@ -67,6 +200,39 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
         this
     }
 
+    pub(crate) fn scored_with_arena(
+        teams: Vec<Vec<Rating<T, D>>>,
+        scores: &'a [f64],
+        weights: &'a [Vec<f64>],
+        score_sigma: f64,
+        arena: &mut ScratchArena,
+    ) -> Self {
+        debug_assert!(
+            scores.len() == teams.len(),
+            "scores must have the same length as teams"
+        );
+        debug_assert!(
+            weights
+                .iter()
+                .zip(teams.iter())
+                .all(|(w, t)| w.len() == t.len()),
+            "weights must have the same dimensions as teams"
+        );
+        debug_assert!(score_sigma > 0.0, "score_sigma must be positive");
+
+        let mut this = Self {
+            teams,
+            result: scores,
+            weights,
+            p_draw: 0.0,
+            likelihoods: Vec::new(),
+            evidence: 0.0,
+        };
+
+        this.likelihoods_scored(arena, score_sigma);
+        this
+    }
+
     fn likelihoods(&mut self, arena: &mut ScratchArena) {
         arena.reset();
 
@@ -90,9 +256,9 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
 
         let n_diffs = n_teams.saturating_sub(1);
 
-        // One TruncFactor per adjacent sorted-team pair; each owns a diff VarId.
-        // trunc stays local (fresh state per game; Vec capacity is typically small).
-        let mut trunc: Vec<TruncFactor> = (0..n_diffs)
+        // One DiffFactor per adjacent sorted-team pair; each owns a diff VarId.
+        // links stays local (fresh state per game; Vec capacity is typically small).
+        let mut links: Vec<DiffFactor> = (0..n_diffs)
             .map(|i| {
                 let tie = self.result[arena.sort_buf[i]] == self.result[arena.sort_buf[i + 1]];
                 let margin = if self.p_draw == 0.0 {
@@ -109,7 +275,7 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
                     compute_margin(self.p_draw, (a + b).sqrt())
                 };
                 let vid = arena.vars.alloc(N_INF);
-                TruncFactor::new(vid, margin, tie)
+                DiffFactor::Trunc(TruncFactor::new(vid, margin, tie))
             })
             .collect();
 
@@ -124,30 +290,30 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
             step = (0.0_f64, 0.0_f64);
 
             // Forward sweep: diffs 0 .. n_diffs-2 (all but the last).
-            for (e, tf) in trunc[..n_diffs.saturating_sub(1)].iter_mut().enumerate() {
+            for (e, lf) in links[..n_diffs.saturating_sub(1)].iter_mut().enumerate() {
                 let pw = arena.team_prior[e] * arena.lhood_lose[e];
                 let pl = arena.team_prior[e + 1] * arena.lhood_win[e + 1];
                 let raw = pw - pl;
-                arena.vars.set(tf.diff, raw * tf.msg);
-                let d = tf.propagate(&mut arena.vars);
+                arena.vars.set(lf.diff(), raw * lf.msg());
+                let d = lf.propagate(&mut arena.vars);
                 step = tuple_max(step, d);
 
-                let new_ll = pw - tf.msg;
+                let new_ll = pw - lf.msg();
                 step = tuple_max(step, arena.lhood_lose[e + 1].delta(new_ll));
                 arena.lhood_lose[e + 1] = new_ll;
             }
 
             // Backward sweep: diffs n_diffs-1 .. 1 (reverse, all but the first).
-            for (rev_i, tf) in trunc[1..].iter_mut().rev().enumerate() {
+            for (rev_i, lf) in links[1..].iter_mut().rev().enumerate() {
                 let e = n_diffs - 1 - rev_i;
                 let pw = arena.team_prior[e] * arena.lhood_lose[e];
                 let pl = arena.team_prior[e + 1] * arena.lhood_win[e + 1];
                 let raw = pw - pl;
-                arena.vars.set(tf.diff, raw * tf.msg);
-                let d = tf.propagate(&mut arena.vars);
+                arena.vars.set(lf.diff(), raw * lf.msg());
+                let d = lf.propagate(&mut arena.vars);
                 step = tuple_max(step, d);
 
-                let new_lw = pl + tf.msg;
+                let new_lw = pl + lf.msg();
                 step = tuple_max(step, arena.lhood_win[e].delta(new_lw));
                 arena.lhood_win[e] = new_lw;
             }
@@ -159,23 +325,20 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
         if n_diffs == 1 {
             let raw = (arena.team_prior[0] * arena.lhood_lose[0])
                 - (arena.team_prior[1] * arena.lhood_win[1]);
-            arena.vars.set(trunc[0].diff, raw * trunc[0].msg);
-            trunc[0].propagate(&mut arena.vars);
+            arena.vars.set(links[0].diff(), raw * links[0].msg());
+            links[0].propagate(&mut arena.vars);
         }
 
         // Boundary updates: close the chain at both ends.
         if n_diffs > 0 {
             let pl1 = arena.team_prior[1] * arena.lhood_win[1];
-            arena.lhood_win[0] = pl1 + trunc[0].msg;
+            arena.lhood_win[0] = pl1 + links[0].msg();
             let pw_last = arena.team_prior[n_teams - 2] * arena.lhood_lose[n_teams - 2];
-            arena.lhood_lose[n_teams - 1] = pw_last - trunc[n_diffs - 1].msg;
+            arena.lhood_lose[n_teams - 1] = pw_last - links[n_diffs - 1].msg();
         }
 
         // Evidence = product of per-diff evidences (each cached on first propagation).
-        self.evidence = trunc
-            .iter()
-            .map(|t| t.evidence_cached.unwrap_or(1.0))
-            .product();
+        self.evidence = links.iter().map(|l| l.evidence()).product();
 
         // Inverse permutation: inv_buf[orig_i] = sorted_i.
         arena.inv_buf.resize(n_teams, 0);
@@ -207,6 +370,120 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
             .collect::<Vec<_>>();
     }
 
+    fn likelihoods_scored(&mut self, arena: &mut ScratchArena, score_sigma: f64) {
+        arena.reset();
+
+        let n_teams = self.teams.len();
+
+        arena.sort_buf.extend(0..n_teams);
+        arena.sort_buf.sort_by(|&i, &j| {
+            self.result[j]
+                .partial_cmp(&self.result[i])
+                .unwrap_or(Ordering::Equal)
+        });
+
+        arena.team_prior.extend(arena.sort_buf.iter().map(|&t| {
+            self.teams[t]
+                .iter()
+                .zip(self.weights[t].iter())
+                .fold(N00, |p, (player, &w)| p + (player.performance() * w))
+        }));
+
+        let n_diffs = n_teams.saturating_sub(1);
+
+        let mut links: Vec<DiffFactor> = (0..n_diffs)
+            .map(|i| {
+                // After descending-by-score sort, m_obs >= 0 for every adjacent pair.
+                let m_obs = self.result[arena.sort_buf[i]] - self.result[arena.sort_buf[i + 1]];
+                let vid = arena.vars.alloc(N_INF);
+                DiffFactor::Margin(MarginFactor::new(vid, m_obs, score_sigma))
+            })
+            .collect();
+
+        arena.lhood_lose.resize(n_teams, N_INF);
+        arena.lhood_win.resize(n_teams, N_INF);
+
+        let mut step = (f64::INFINITY, f64::INFINITY);
+        let mut iter = 0;
+
+        while tuple_gt(step, 1e-6) && iter < 10 {
+            step = (0.0_f64, 0.0_f64);
+
+            for (e, lf) in links[..n_diffs.saturating_sub(1)].iter_mut().enumerate() {
+                let pw = arena.team_prior[e] * arena.lhood_lose[e];
+                let pl = arena.team_prior[e + 1] * arena.lhood_win[e + 1];
+                let raw = pw - pl;
+                arena.vars.set(lf.diff(), raw * lf.msg());
+                let d = lf.propagate(&mut arena.vars);
+                step = tuple_max(step, d);
+
+                let new_ll = pw - lf.msg();
+                step = tuple_max(step, arena.lhood_lose[e + 1].delta(new_ll));
+                arena.lhood_lose[e + 1] = new_ll;
+            }
+
+            for (rev_i, lf) in links[1..].iter_mut().rev().enumerate() {
+                let e = n_diffs - 1 - rev_i;
+                let pw = arena.team_prior[e] * arena.lhood_lose[e];
+                let pl = arena.team_prior[e + 1] * arena.lhood_win[e + 1];
+                let raw = pw - pl;
+                arena.vars.set(lf.diff(), raw * lf.msg());
+                let d = lf.propagate(&mut arena.vars);
+                step = tuple_max(step, d);
+
+                let new_lw = pl + lf.msg();
+                step = tuple_max(step, arena.lhood_win[e].delta(new_lw));
+                arena.lhood_win[e] = new_lw;
+            }
+
+            iter += 1;
+        }
+
+        if n_diffs == 1 {
+            let raw = (arena.team_prior[0] * arena.lhood_lose[0])
+                - (arena.team_prior[1] * arena.lhood_win[1]);
+            arena.vars.set(links[0].diff(), raw * links[0].msg());
+            links[0].propagate(&mut arena.vars);
+        }
+
+        if n_diffs > 0 {
+            let pl1 = arena.team_prior[1] * arena.lhood_win[1];
+            arena.lhood_win[0] = pl1 + links[0].msg();
+            let pw_last = arena.team_prior[n_teams - 2] * arena.lhood_lose[n_teams - 2];
+            arena.lhood_lose[n_teams - 1] = pw_last - links[n_diffs - 1].msg();
+        }
+
+        self.evidence = links.iter().map(|l| l.evidence()).product();
+
+        arena.inv_buf.resize(n_teams, 0);
+        for (si, &orig_i) in arena.sort_buf.iter().enumerate() {
+            arena.inv_buf[orig_i] = si;
+        }
+
+        self.likelihoods = self
+            .teams
+            .iter()
+            .zip(self.weights.iter())
+            .enumerate()
+            .map(|(orig_i, (players, weights))| {
+                let si = arena.inv_buf[orig_i];
+                let m = arena.lhood_win[si] * arena.lhood_lose[si];
+                let performance = players
+                    .iter()
+                    .zip(weights.iter())
+                    .fold(N00, |p, (player, &w)| p + (player.performance() * w));
+                players
+                    .iter()
+                    .zip(weights.iter())
+                    .map(|(player, &w)| {
+                        ((m - performance.exclude(player.performance() * w)) * (1.0 / w))
+                            .forget(player.beta.powi(2))
+                    })
+                    .collect::<Vec<_>>()
+            })
+            .collect::<Vec<_>>();
+    }
+
     pub fn posteriors(&self) -> Vec<Vec<Gaussian>> {
         self.likelihoods
             .iter()
@@ -219,6 +496,110 @@ impl<'a, T: Time, D: Drift<T>> Game<'a, T, D> {
             })
             .collect::<Vec<_>>()
     }
+
+    pub fn log_evidence(&self) -> f64 {
+        self.evidence.ln()
+    }
+}
+
+impl<T: Time, D: Drift<T>> Game<'_, T, D> {
+    pub fn ranked(
+        teams: &[&[Rating<T, D>]],
+        outcome: crate::Outcome,
+        options: &GameOptions,
+    ) -> Result<OwnedGame<T, D>, crate::InferenceError> {
+        if !(0.0..1.0).contains(&options.p_draw) {
+            return Err(crate::InferenceError::InvalidProbability {
+                value: options.p_draw,
+            });
+        }
+        if outcome.team_count() != teams.len() {
+            return Err(crate::InferenceError::MismatchedShape {
+                kind: "outcome ranks vs teams",
+                expected: teams.len(),
+                got: outcome.team_count(),
+            });
+        }
+
+        let ranks = outcome
+            .as_ranks()
+            .ok_or(crate::InferenceError::MismatchedShape {
+                kind: "Game::ranked requires Outcome::Ranked",
+                expected: 0,
+                got: 0,
+            })?;
+        let max_rank = ranks.iter().copied().max().unwrap_or(0) as f64;
+        let result: Vec<f64> = ranks.iter().map(|&r| max_rank - r as f64).collect();
+        let teams_owned: Vec<Vec<Rating<T, D>>> = teams.iter().map(|t| t.to_vec()).collect();
+        let weights: Vec<Vec<f64>> = teams.iter().map(|t| vec![1.0; t.len()]).collect();
+
+        Ok(OwnedGame::new(teams_owned, result, weights, options.p_draw))
+    }
+
+    pub fn scored(
+        teams: &[&[Rating<T, D>]],
+        outcome: crate::Outcome,
+        options: &GameOptions,
+    ) -> Result<OwnedGame<T, D>, crate::InferenceError> {
+        if options.score_sigma <= 0.0 || options.score_sigma.is_nan() {
+            return Err(crate::InferenceError::InvalidParameter {
+                name: "score_sigma",
+                value: options.score_sigma,
+            });
+        }
+        if outcome.team_count() != teams.len() {
+            return Err(crate::InferenceError::MismatchedShape {
+                kind: "outcome scores vs teams",
+                expected: teams.len(),
+                got: outcome.team_count(),
+            });
+        }
+        let scores = outcome
+            .as_scores()
+            .ok_or(crate::InferenceError::MismatchedShape {
+                kind: "Game::scored requires Outcome::Scored",
+                expected: 0,
+                got: 0,
+            })?
+            .to_vec();
+        let teams_owned: Vec<Vec<Rating<T, D>>> = teams.iter().map(|t| t.to_vec()).collect();
+        let weights: Vec<Vec<f64>> = teams.iter().map(|t| vec![1.0; t.len()]).collect();
+        Ok(OwnedGame::new_scored(
+            teams_owned,
+            scores,
+            weights,
+            options.score_sigma,
+        ))
+    }
+
+    pub fn one_v_one(
+        a: &Rating<T, D>,
+        b: &Rating<T, D>,
+        outcome: crate::Outcome,
+    ) -> Result<(Gaussian, Gaussian), crate::InferenceError> {
+        let game = Self::ranked(&[&[*a], &[*b]], outcome, &GameOptions::default())?;
+        let post = game.posteriors();
+        Ok((post[0][0], post[1][0]))
+    }
+
+    pub fn free_for_all(
+        players: &[&Rating<T, D>],
+        outcome: crate::Outcome,
+        options: &GameOptions,
+    ) -> Result<OwnedGame<T, D>, crate::InferenceError> {
+        let teams: Vec<Vec<Rating<T, D>>> = players.iter().map(|p| vec![**p]).collect();
+        let team_refs: Vec<&[Rating<T, D>]> = teams.iter().map(|t| t.as_slice()).collect();
+        Self::ranked(&team_refs, outcome, options)
+    }
+
+    #[doc(hidden)]
+    pub fn custom<S: crate::factors::Schedule>(
+        factors: &mut [crate::factors::BuiltinFactor],
+        vars: &mut crate::factors::VarStore,
+        schedule: &S,
+    ) -> crate::factors::ScheduleReport {
+        schedule.run(factors, vars)
+    }
 }
 
 #[cfg(test)]
@@ -244,7 +625,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b]],
             &[0.0, 1.0],
             &w,
@@ -271,7 +652,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b]],
             &[0.0, 1.0],
             &w,
@@ -290,7 +671,7 @@ mod tests {
         let t_b = R::new(Gaussian::from_ms(15.568, 0.51), 1.0, ConstantDrift(0.2125));
 
         let w = [vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b]],
             &[0.0, 1.0],
             &w,
@@ -323,7 +704,7 @@ mod tests {
         ];
 
         let w = [vec![1.0], vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             teams.clone(),
             &[1.0, 2.0, 0.0],
             &w,
@@ -339,7 +720,7 @@ mod tests {
         assert_ulps_eq!(b, Gaussian::from_ms(31.311358, 6.698818), epsilon = 1e-6);
 
         let w = [vec![1.0], vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             teams.clone(),
             &[2.0, 1.0, 0.0],
             &w,
@@ -355,7 +736,7 @@ mod tests {
         assert_ulps_eq!(b, Gaussian::from_ms(25.000000, 6.238469), epsilon = 1e-6);
 
         let w = [vec![1.0], vec![1.0], vec![1.0]];
-        let g = Game::new(teams, &[1.0, 2.0, 0.0], &w, 0.5, &mut ScratchArena::new());
+        let g = Game::ranked_with_arena(teams, &[1.0, 2.0, 0.0], &w, 0.5, &mut ScratchArena::new());
         let p = g.posteriors();
 
         let a = p[0][0];
@@ -382,7 +763,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b]],
             &[0.0, 0.0],
             &w,
@@ -409,7 +790,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b]],
             &[0.0, 0.0],
             &w,
@@ -444,7 +825,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b], vec![t_c]],
             &[0.0, 0.0, 0.0],
             &w,
@@ -480,7 +861,7 @@ mod tests {
         );
 
         let w = [vec![1.0], vec![1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![vec![t_a], vec![t_b], vec![t_c]],
             &[0.0, 0.0, 0.0],
             &w,
@@ -531,7 +912,7 @@ mod tests {
         ];
 
         let w = [vec![1.0, 1.0], vec![1.0], vec![1.0, 1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a, t_b, t_c],
             &[1.0, 0.0, 0.0],
             &w,
@@ -564,7 +945,7 @@ mod tests {
         )];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a.clone(), t_b.clone()],
             &[1.0, 0.0],
             &w,
@@ -588,7 +969,7 @@ mod tests {
         let w_b = vec![0.7];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a.clone(), t_b.clone()],
             &[1.0, 0.0],
             &w,
@@ -612,7 +993,7 @@ mod tests {
         let w_b = vec![0.7];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a, t_b],
             &[1.0, 0.0],
             &w,
@@ -639,7 +1020,7 @@ mod tests {
         let t_b = vec![R::new(Gaussian::from_ms(2.0, 6.0), 1.0, ConstantDrift(0.0))];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a, t_b],
             &[1.0, 0.0],
             &w,
@@ -666,7 +1047,7 @@ mod tests {
         let t_b = vec![R::new(Gaussian::from_ms(2.0, 6.0), 1.0, ConstantDrift(0.0))];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a, t_b],
             &[1.0, 0.0],
             &w,
@@ -678,6 +1059,131 @@ mod tests {
         assert_ulps_eq!(p[0][0], p[1][0], epsilon = 1e-6);
     }
 
+    #[test]
+    fn diff_factor_dispatch_trunc_and_margin() {
+        use super::DiffFactor;
+        use crate::factor::{VarStore, margin::MarginFactor, trunc::TruncFactor};
+
+        let mut vars = VarStore::new();
+        let dt = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+        let dm = vars.alloc(Gaussian::from_ms(0.0, 6.0));
+
+        let mut t = DiffFactor::Trunc(TruncFactor::new(dt, 0.0, false));
+        let mut m = DiffFactor::Margin(MarginFactor::new(dm, 5.0, 1.0));
+
+        let _ = t.propagate(&mut vars);
+        let _ = m.propagate(&mut vars);
+
+        // Smoke: both diffs got written; their msgs are non-N_INF.
+        assert!(t.msg().pi() > 0.0);
+        assert!(m.msg().pi() > 0.0);
+        assert_eq!(t.diff(), dt);
+        assert_eq!(m.diff(), dm);
+    }
+
+    #[test]
+    fn scored_path_sharper_when_margin_is_large() {
+        let prior = R::new(
+            Gaussian::from_ms(25.0, 25.0 / 3.0),
+            25.0 / 6.0,
+            ConstantDrift(25.0 / 300.0),
+        );
+        let teams = vec![vec![prior], vec![prior]];
+        let result = vec![10.0, 0.0]; // a beat b by 10
+        let weights = [vec![1.0], vec![1.0]];
+        let mut arena = ScratchArena::new();
+        let g = Game::scored_with_arena(
+            teams, &result, &weights, 1.0, // score_sigma
+            &mut arena,
+        );
+        let p = g.posteriors();
+        let a = p[0][0];
+        let b = p[1][0];
+        assert!(
+            a.mu() > b.mu(),
+            "expected team a posterior mu > team b; got {} vs {}",
+            a.mu(),
+            b.mu()
+        );
+
+        // Tighter score_sigma should produce a stronger update.
+        let mut arena2 = ScratchArena::new();
+        let g_tight = Game::scored_with_arena(
+            vec![vec![prior], vec![prior]],
+            &result,
+            &weights,
+            0.1, // tighter score_sigma
+            &mut arena2,
+        );
+        let p_tight = g_tight.posteriors();
+        let a_tight = p_tight[0][0];
+        assert!(
+            a_tight.mu() > a.mu(),
+            "expected tighter sigma to push posterior further; {} vs {}",
+            a_tight.mu(),
+            a.mu()
+        );
+    }
+
+    #[test]
+    fn game_scored_public_ctor() {
+        use crate::Outcome;
+        let prior = R::new(
+            Gaussian::from_ms(25.0, 25.0 / 3.0),
+            25.0 / 6.0,
+            ConstantDrift(25.0 / 300.0),
+        );
+        let opts = GameOptions {
+            score_sigma: 1.0,
+            ..GameOptions::default()
+        };
+        let g = Game::scored(&[&[prior], &[prior]], Outcome::scores([8.0, 2.0]), &opts).unwrap();
+        let p = g.posteriors();
+        assert!(p[0][0].mu() > p[1][0].mu());
+    }
+
+    #[test]
+    fn game_scored_rejects_ranked_outcome() {
+        let prior = R::new(
+            Gaussian::from_ms(25.0, 25.0 / 3.0),
+            25.0 / 6.0,
+            ConstantDrift(25.0 / 300.0),
+        );
+        let err = Game::scored(
+            &[&[prior], &[prior]],
+            crate::Outcome::winner(0, 2),
+            &GameOptions::default(),
+        )
+        .unwrap_err();
+        assert!(matches!(err, crate::InferenceError::MismatchedShape { .. }));
+    }
+
+    #[test]
+    fn game_scored_rejects_zero_score_sigma() {
+        let prior = R::new(
+            Gaussian::from_ms(25.0, 25.0 / 3.0),
+            25.0 / 6.0,
+            ConstantDrift(25.0 / 300.0),
+        );
+        let opts = GameOptions {
+            score_sigma: 0.0,
+            ..GameOptions::default()
+        };
+        let err = Game::scored(
+            &[&[prior], &[prior]],
+            crate::Outcome::scores([1.0, 0.0]),
+            &opts,
+        )
+        .unwrap_err();
+        assert!(matches!(
+            err,
+            crate::InferenceError::InvalidParameter {
+                name: "score_sigma",
+                ..
+            }
+        ));
+    }
+
     #[test]
     fn test_2vs2_weighted() {
         let t_a = vec![
@@ -709,7 +1215,7 @@ mod tests {
         let w_b = vec![0.9, 0.6];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a.clone(), t_b.clone()],
             &[1.0, 0.0],
             &w,
@@ -743,7 +1249,7 @@ mod tests {
         let w_b = vec![0.7, 0.4];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a.clone(), t_b.clone()],
             &[1.0, 0.0],
             &w,
@@ -777,7 +1283,7 @@ mod tests {
         let w_b = vec![0.7, 2.4];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a.clone(), t_b.clone()],
             &[1.0, 0.0],
             &w,
@@ -808,7 +1314,7 @@ mod tests {
         );
 
         let w = [vec![1.0, 1.0], vec![1.0]];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![
                 t_a.clone(),
                 vec![R::new(
@@ -828,7 +1334,7 @@ mod tests {
         let w_b = vec![1.0, 0.0];
 
         let w = [w_a, w_b];
-        let g = Game::new(
+        let g = Game::ranked_with_arena(
             vec![t_a, t_b.clone()],
             &[1.0, 0.0],
             &w,

src/key_table.rs

@@ -22,7 +22,7 @@ where
         Self(HashMap::new())
     }
 
-    pub fn get<Q: ?Sized + Hash + Eq + ToOwned<Owned = K>>(&self, k: &Q) -> Option<Index>
+    pub fn get<Q: ?Sized + Hash + Eq>(&self, k: &Q) -> Option<Index>
     where
         K: Borrow<Q>,
     {

src/lib.rs

@@ -8,12 +8,16 @@ mod approx;
 pub(crate) mod arena;
 mod time;
 mod time_slice;
-pub use time_slice::TimeSlice;
+pub use time_slice::{EventKind, TimeSlice};
+mod color_group;
 mod competitor;
+mod convergence;
 pub mod drift;
 mod error;
 mod event;
+mod event_builder;
 pub(crate) mod factor;
+pub mod factors;
 mod game;
 pub mod gaussian;
 mod history;
@@ -26,10 +30,12 @@ pub(crate) mod schedule;
 pub mod storage;
 
 pub use competitor::Competitor;
+pub use convergence::{ConvergenceOptions, ConvergenceReport};
 pub use drift::{ConstantDrift, Drift};
 pub use error::InferenceError;
 pub use event::{Event, Member, Team};
-pub use game::Game;
+pub use event_builder::EventBuilder;
+pub use game::{Game, GameOptions, OwnedGame};
 pub use gaussian::Gaussian;
 pub use history::History;
 pub use key_table::KeyTable;

src/observer.rs

@@ -9,9 +9,8 @@ use crate::time::Time;
 /// Receives progress callbacks during `History::converge`.
 ///
 /// All methods have default no-op implementations; implement only what's
-/// interesting. Send/Sync is NOT required in T2 (added in T3 along with
-/// Rayon support).
-pub trait Observer<T: Time> {
+/// interesting.
+pub trait Observer<T: Time>: Send + Sync {
     /// Called after each convergence iteration across the whole history.
     fn on_iteration_end(&self, _iter: usize, _max_step: (f64, f64)) {}
 

src/outcome.rs

@@ -1,8 +1,7 @@
 //! Outcome of a match.
 //!
-//! In T2, only `Ranked` is supported; `Scored` will be added together with
-//! `MarginFactor` in T4. The enum is `#[non_exhaustive]` so adding `Scored`
-//! is non-breaking for downstream `match` expressions.
+//! `Ranked(ranks)` for ordinal results; `Scored(scores)` for continuous
+//! per-team scores (engages `MarginFactor` in the engine).
 
 use smallvec::SmallVec;
 
@@ -10,14 +9,19 @@ use smallvec::SmallVec;
 ///
 /// `Ranked(ranks)`: lower rank = better. Equal ranks mean a tie between those
 /// teams. `ranks.len()` must equal the number of teams in the event.
+///
+/// `Scored(scores)`: higher score = better. Adjacent (sorted) pairs feed
+/// observed margins to `MarginFactor`. `scores.len()` must equal the number
+/// of teams in the event.
 #[derive(Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub enum Outcome {
     Ranked(SmallVec<[u32; 4]>),
+    Scored(SmallVec<[f64; 4]>),
 }
 
 impl Outcome {
-    /// `N`-team outcome where team `winner` won and everyone else tied for last.
+    /// `n`-team outcome where team `winner` won and everyone else tied for last.
     ///
     /// Panics if `winner >= n`.
     pub fn winner(winner: u32, n: u32) -> Self {
@@ -36,16 +40,29 @@ impl Outcome {
         Self::Ranked(ranks.into_iter().collect())
     }
 
+    /// Explicit per-team continuous scores; higher = better.
+    pub fn scores<I: IntoIterator<Item = f64>>(scores: I) -> Self {
+        Self::Scored(scores.into_iter().collect())
+    }
+
     pub fn team_count(&self) -> usize {
         match self {
             Self::Ranked(r) => r.len(),
+            Self::Scored(s) => s.len(),
         }
     }
 
-    #[allow(dead_code)]
-    pub(crate) fn as_ranks(&self) -> &[u32] {
+    pub(crate) fn as_ranks(&self) -> Option<&[u32]> {
         match self {
-            Self::Ranked(r) => r,
+            Self::Ranked(r) => Some(r),
+            Self::Scored(_) => None,
+        }
+    }
+
+    pub(crate) fn as_scores(&self) -> Option<&[f64]> {
+        match self {
+            Self::Scored(s) => Some(s),
+            Self::Ranked(_) => None,
         }
     }
 }
@@ -57,26 +74,26 @@ mod tests {
     #[test]
     fn winner_two_teams() {
         let o = Outcome::winner(0, 2);
-        assert_eq!(o.as_ranks(), &[0u32, 1]);
+        assert_eq!(o.as_ranks(), Some(&[0u32, 1][..]));
         assert_eq!(o.team_count(), 2);
     }
 
     #[test]
     fn winner_three_teams_second_wins() {
         let o = Outcome::winner(1, 3);
-        assert_eq!(o.as_ranks(), &[1u32, 0, 1]);
+        assert_eq!(o.as_ranks(), Some(&[1u32, 0, 1][..]));
     }
 
     #[test]
     fn draw_three_teams() {
         let o = Outcome::draw(3);
-        assert_eq!(o.as_ranks(), &[0u32, 0, 0]);
+        assert_eq!(o.as_ranks(), Some(&[0u32, 0, 0][..]));
     }
 
     #[test]
     fn ranking_from_iter() {
         let o = Outcome::ranking([2, 0, 1]);
-        assert_eq!(o.as_ranks(), &[2u32, 0, 1]);
+        assert_eq!(o.as_ranks(), Some(&[2u32, 0, 1][..]));
     }
 
     #[test]
@@ -84,4 +101,25 @@ mod tests {
     fn winner_out_of_range_panics() {
         let _ = Outcome::winner(2, 2);
     }
+
+    #[test]
+    fn scored_two_teams() {
+        let o = Outcome::scores([10.0, 4.0]);
+        assert_eq!(o.team_count(), 2);
+        assert_eq!(o.as_scores(), Some(&[10.0, 4.0][..]));
+        assert_eq!(o.as_ranks(), None);
+    }
+
+    #[test]
+    fn scored_team_count_matches_input() {
+        let o = Outcome::scores([3.0, 1.0, 2.0, 0.0]);
+        assert_eq!(o.team_count(), 4);
+    }
+
+    #[test]
+    fn ranked_as_scores_returns_none() {
+        let o = Outcome::winner(0, 2);
+        assert!(o.as_scores().is_none());
+        assert!(o.as_ranks().is_some());
+    }
 }

src/schedule.rs

@@ -16,8 +16,7 @@ pub struct ScheduleReport {
 }
 
 /// Drives factor propagation to convergence.
-#[allow(dead_code)]
-pub(crate) trait Schedule {
+pub trait Schedule: Send + Sync {
     fn run(&self, factors: &mut [BuiltinFactor], vars: &mut VarStore) -> ScheduleReport;
 }
 
@@ -26,8 +25,7 @@ pub(crate) trait Schedule {
 /// Matches the existing `Game::likelihoods` loop bit-for-bit when given the
 /// same factor layout (TeamSums first, then alternating RankDiff/Trunc pairs).
 #[derive(Debug, Clone, Copy)]
-#[allow(dead_code)]
-pub(crate) struct EpsilonOrMax {
+pub struct EpsilonOrMax {
     pub eps: f64,
     pub max: usize,
 }

src/time.rs

@@ -8,7 +8,7 @@
 ///
 /// Must be `Ord + Copy` so slices can sort events, and `'static` so
 /// `History` can store it by value without lifetimes.
-pub trait Time: Copy + Ord + 'static {
+pub trait Time: Copy + Ord + Send + Sync + 'static {
     /// How much time elapsed between `self` and `later`.
     ///
     /// Used by `Drift<T>::variance_delta` to compute skill drift. Returning

src/time_slice.rs

@@ -7,6 +7,7 @@ use std::collections::HashMap;
 use crate::{
     Index, N_INF,
     arena::ScratchArena,
+    color_group::ColorGroups,
     drift::Drift,
     game::Game,
     gaussian::Gaussian,
@@ -43,6 +44,13 @@ impl Default for Skill {
     }
 }
 
+#[derive(Debug, Clone, Copy)]
+#[non_exhaustive]
+pub enum EventKind {
+    Ranked,
+    Scored { score_sigma: f64 },
+}
+
 #[derive(Debug)]
 struct Item {
     agent: Index,
@@ -81,9 +89,16 @@ pub(crate) struct Event {
     teams: Vec<Team>,
     evidence: f64,
     weights: Vec<Vec<f64>>,
+    kind: EventKind,
 }
 
 impl Event {
+    pub(crate) fn iter_agents(&self) -> impl Iterator<Item = Index> + '_ {
+        self.teams
+            .iter()
+            .flat_map(|t| t.items.iter().map(|it| it.agent))
+    }
+
     fn outputs(&self) -> Vec<f64> {
         self.teams
             .iter()
@@ -108,6 +123,40 @@ impl Event {
             })
             .collect::<Vec<_>>()
     }
+
+    /// Direct in-loop update: mutates self and `skills` inline with no
+    /// intermediate allocation. Used by both the sequential sweep path and,
+    /// via unsafe, by the parallel rayon path for events in the same color
+    /// group (which have disjoint agent sets — see `sweep_color_groups`).
+    fn iteration_direct<T: Time, D: Drift<T>>(
+        &mut self,
+        skills: &mut SkillStore,
+        agents: &CompetitorStore<T, D>,
+        p_draw: f64,
+        arena: &mut ScratchArena,
+    ) {
+        let teams = self.within_priors(false, false, skills, agents);
+        let result = self.outputs();
+        let g = match self.kind {
+            EventKind::Ranked => {
+                Game::ranked_with_arena(teams, &result, &self.weights, p_draw, arena)
+            }
+            EventKind::Scored { score_sigma } => {
+                Game::scored_with_arena(teams, &result, &self.weights, score_sigma, arena)
+            }
+        };
+
+        for (t, team) in self.teams.iter_mut().enumerate() {
+            for (i, item) in team.items.iter_mut().enumerate() {
+                let old_likelihood = skills.get(item.agent).unwrap().likelihood;
+                let new_likelihood = (old_likelihood / item.likelihood) * g.likelihoods[t][i];
+                skills.get_mut(item.agent).unwrap().likelihood = new_likelihood;
+                item.likelihood = g.likelihoods[t][i];
+            }
+        }
+
+        self.evidence = g.evidence;
+    }
 }
 
 #[derive(Debug)]
@@ -117,6 +166,7 @@ pub struct TimeSlice<T: Time = i64> {
     pub(crate) time: T,
     p_draw: f64,
     arena: ScratchArena,
+    pub(crate) color_groups: ColorGroups,
 }
 
 impl<T: Time> TimeSlice<T> {
@@ -127,14 +177,50 @@ impl<T: Time> TimeSlice<T> {
             time,
             p_draw,
             arena: ScratchArena::new(),
+            color_groups: ColorGroups::new(),
         }
     }
 
+    /// Recompute the color-group partition and reorder `self.events` into
+    /// color-contiguous ranges. After this call, `self.color_groups.groups[c]`
+    /// contains a contiguous ascending range of indices in `self.events`.
+    pub(crate) fn recompute_color_groups(&mut self) {
+        use crate::color_group::color_greedy;
+
+        let n = self.events.len();
+        if n == 0 {
+            self.color_groups = ColorGroups::new();
+            return;
+        }
+
+        let cg = color_greedy(n, |ev_idx| {
+            self.events[ev_idx].iter_agents().collect::<Vec<_>>()
+        });
+
+        let mut reordered: Vec<Event> = Vec::with_capacity(n);
+        let mut new_groups: Vec<Vec<usize>> = Vec::with_capacity(cg.groups.len());
+        let mut taken: Vec<Option<Event>> = self.events.drain(..).map(Some).collect();
+
+        for group in &cg.groups {
+            let mut new_indices: Vec<usize> = Vec::with_capacity(group.len());
+            for &old_idx in group {
+                let ev = taken[old_idx].take().expect("event already taken");
+                new_indices.push(reordered.len());
+                reordered.push(ev);
+            }
+            new_groups.push(new_indices);
+        }
+
+        self.events = reordered;
+        self.color_groups = ColorGroups { groups: new_groups };
+    }
+
     pub fn add_events<D: Drift<T>>(
         &mut self,
         composition: Vec<Vec<Vec<Index>>>,
         results: Vec<Vec<f64>>,
         weights: Vec<Vec<Vec<f64>>>,
+        kinds: Vec<EventKind>,
         agents: &CompetitorStore<T, D>,
     ) {
         let mut unique = Vec::with_capacity(10);
@@ -204,6 +290,7 @@ impl<T: Time> TimeSlice<T> {
                 teams,
                 evidence: 0.0,
                 weights,
+                kind: kinds[e],
             }
         });
 
@@ -212,6 +299,7 @@ impl<T: Time> TimeSlice<T> {
         self.events.extend(events);
 
         self.iteration(from, agents);
+        self.recompute_color_groups();
     }
 
     pub(crate) fn posteriors(&self) -> HashMap<Index, Gaussian> {
@@ -222,22 +310,124 @@ impl<T: Time> TimeSlice<T> {
     }
 
     pub fn iteration<D: Drift<T>>(&mut self, from: usize, agents: &CompetitorStore<T, D>) {
-        for event in self.events.iter_mut().skip(from) {
-            let teams = event.within_priors(false, false, &self.skills, agents);
-            let result = event.outputs();
+        if from > 0 || self.color_groups.is_empty() {
+            // Initial pass (add_events) or no color groups yet: simple sequential sweep.
+            for event in self.events.iter_mut().skip(from) {
+                let teams = event.within_priors(false, false, &self.skills, agents);
+                let result = event.outputs();
 
-            let g = Game::new(teams, &result, &event.weights, self.p_draw, &mut self.arena);
+                let g = match event.kind {
+                    EventKind::Ranked => Game::ranked_with_arena(
+                        teams,
+                        &result,
+                        &event.weights,
+                        self.p_draw,
+                        &mut self.arena,
+                    ),
+                    EventKind::Scored { score_sigma } => Game::scored_with_arena(
+                        teams,
+                        &result,
+                        &event.weights,
+                        score_sigma,
+                        &mut self.arena,
+                    ),
+                };
 
-            for (t, team) in event.teams.iter_mut().enumerate() {
-                for (i, item) in team.items.iter_mut().enumerate() {
-                    let old_likelihood = self.skills.get(item.agent).unwrap().likelihood;
-                    let new_likelihood = (old_likelihood / item.likelihood) * g.likelihoods[t][i];
-                    self.skills.get_mut(item.agent).unwrap().likelihood = new_likelihood;
-                    item.likelihood = g.likelihoods[t][i];
+                for (t, team) in event.teams.iter_mut().enumerate() {
+                    for (i, item) in team.items.iter_mut().enumerate() {
+                        let old_likelihood = self.skills.get(item.agent).unwrap().likelihood;
+                        let new_likelihood =
+                            (old_likelihood / item.likelihood) * g.likelihoods[t][i];
+                        self.skills.get_mut(item.agent).unwrap().likelihood = new_likelihood;
+                        item.likelihood = g.likelihoods[t][i];
+                    }
+                }
+
+                event.evidence = g.evidence;
+            }
+        } else {
+            self.sweep_color_groups(agents);
+        }
+    }
+
+    /// Full event sweep using the color-group partition. Colors are processed
+    /// sequentially; within each color the inner loop is parallel under rayon.
+    ///
+    /// Events within each color group touch disjoint agent sets (guaranteed by
+    /// the greedy coloring). This lets each rayon thread write directly to its
+    /// events' skill likelihoods without a deferred-apply step, matching the
+    /// sequential path's allocation profile. The unsafe block is sound because:
+    ///   1. `self.events[range]` and `self.skills` are separate fields → disjoint.
+    ///   2. Events in the same color group access disjoint `Index` values in
+    ///      `self.skills`, so concurrent writes land on different memory locations.
+    ///   3. Each event only writes to its own items' likelihoods (no sharing).
+    #[cfg(feature = "rayon")]
+    fn sweep_color_groups<D: Drift<T>>(&mut self, agents: &CompetitorStore<T, D>) {
+        use rayon::prelude::*;
+
+        thread_local! {
+            static ARENA: std::cell::RefCell<ScratchArena> =
+                std::cell::RefCell::new(ScratchArena::new());
+        }
+
+        // Minimum color-group size to justify rayon's task-spawn overhead.
+        // Below this threshold, process events sequentially to avoid regression
+        // on small per-slice workloads.
+        const RAYON_THRESHOLD: usize = 64;
+
+        for color_idx in 0..self.color_groups.groups.len() {
+            let group_len = self.color_groups.groups[color_idx].len();
+            if group_len == 0 {
+                continue;
+            }
+            let range = self.color_groups.color_range(color_idx);
+            let p_draw = self.p_draw;
+
+            if group_len >= RAYON_THRESHOLD {
+                // Obtain a raw pointer from the unique `&mut self.skills` reference.
+                // Casting back to `&mut` inside the closure is sound because:
+                //   1. The pointer originates from a `&mut` — no aliasing with shared refs.
+                //   2. Events in the same color group touch disjoint `Index` slots in the
+                //      underlying Vec, so concurrent writes from different threads land on
+                //      different memory locations — no data race.
+                //   3. `self.events[range]` and `self.skills` are separate struct fields,
+                //      so the borrow splits cleanly.
+                let skills_addr: usize = (&mut self.skills as *mut SkillStore) as usize;
+                self.events[range].par_iter_mut().for_each(move |ev| {
+                    // SAFETY: see above.
+                    let skills: &mut SkillStore = unsafe { &mut *(skills_addr as *mut SkillStore) };
+                    ARENA.with(|cell| {
+                        let mut arena = cell.borrow_mut();
+                        arena.reset();
+                        ev.iteration_direct(skills, agents, p_draw, &mut arena);
+                    });
+                });
+            } else {
+                for ev in &mut self.events[range] {
+                    ev.iteration_direct(&mut self.skills, agents, p_draw, &mut self.arena);
                 }
             }
+        }
+    }
 
-            event.evidence = g.evidence;
+    /// Full event sweep using the color-group partition, sequential direct-write path.
+    /// Events within each color group are updated inline — no EventOutput allocation —
+    /// matching the T2 performance profile.
+    #[cfg(not(feature = "rayon"))]
+    fn sweep_color_groups<D: Drift<T>>(&mut self, agents: &CompetitorStore<T, D>) {
+        for color_idx in 0..self.color_groups.groups.len() {
+            if self.color_groups.groups[color_idx].is_empty() {
+                continue;
+            }
+            let range = self.color_groups.color_range(color_idx);
+
+            // Borrow self.events as a mutable slice for this color range.
+            // self.skills and self.arena are separate fields — disjoint borrows are
+            // allowed within a single method body.
+            let p_draw = self.p_draw;
+            for ev in &mut self.events[range] {
+                ev.iteration_direct(&mut self.skills, agents, p_draw, &mut self.arena);
+            }
         }
     }
 
@@ -310,21 +500,28 @@ impl<T: Time> TimeSlice<T> {
         // log_evidence is infrequent; a local arena avoids needing &mut self.
         let mut arena = ScratchArena::new();
 
+        let run_event = |event: &Event, arena: &mut ScratchArena| -> f64 {
+            let teams = event.within_priors(online, forward, &self.skills, agents);
+            let result = event.outputs();
+            match event.kind {
+                EventKind::Ranked => {
+                    Game::ranked_with_arena(teams, &result, &event.weights, self.p_draw, arena)
+                        .evidence
+                        .ln()
+                }
+                EventKind::Scored { score_sigma } => {
+                    Game::scored_with_arena(teams, &result, &event.weights, score_sigma, arena)
+                        .evidence
+                        .ln()
+                }
+            }
+        };
+
         if targets.is_empty() {
             if online || forward {
                 self.events
                     .iter()
-                    .map(|event| {
-                        Game::new(
-                            event.within_priors(online, forward, &self.skills, agents),
-                            &event.outputs(),
-                            &event.weights,
-                            self.p_draw,
-                            &mut arena,
-                        )
-                        .evidence
-                        .ln()
-                    })
+                    .map(|event| run_event(event, &mut arena))
                     .sum()
             } else {
                 self.events.iter().map(|event| event.evidence.ln()).sum()
@@ -332,25 +529,14 @@ impl<T: Time> TimeSlice<T> {
         } else if online || forward {
             self.events
                 .iter()
-                .enumerate()
-                .filter(|(_, event)| {
+                .filter(|event| {
                     event
                         .teams
                         .iter()
                         .flat_map(|team| &team.items)
                         .any(|item| targets.contains(&item.agent))
                 })
-                .map(|(_, event)| {
-                    Game::new(
-                        event.within_priors(online, forward, &self.skills, agents),
-                        &event.outputs(),
-                        &event.weights,
-                        self.p_draw,
-                        &mut arena,
-                    )
-                    .evidence
-                    .ln()
-                })
+                .map(|event| run_event(event, &mut arena))
                 .sum()
         } else {
             self.events
@@ -445,6 +631,7 @@ mod tests {
             ],
             vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
             vec![],
+            vec![EventKind::Ranked; 3],
             &agents,
         );
 
@@ -521,6 +708,7 @@ mod tests {
             ],
             vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
             vec![],
+            vec![EventKind::Ranked; 3],
             &agents,
         );
 
@@ -600,6 +788,7 @@ mod tests {
             ],
             vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
             vec![],
+            vec![EventKind::Ranked; 3],
             &agents,
         );
 
@@ -631,6 +820,7 @@ mod tests {
             ],
             vec![vec![1.0, 0.0], vec![0.0, 1.0], vec![1.0, 0.0]],
             vec![],
+            vec![EventKind::Ranked; 3],
             &agents,
         );
 
@@ -656,4 +846,68 @@ mod tests {
             epsilon = 1e-6
         );
     }
+
+    #[test]
+    fn time_slice_color_groups_reorders_events() {
+        // ev0: [a, b]; ev1: [c, d]; ev2: [a, c]
+        // Greedy coloring: ev0→c0, ev1→c0 (disjoint), ev2→c1 (overlaps both).
+        // After recompute_color_groups, physical order is [ev0, ev1, ev2]
+        // and groups == [[0, 1], [2]].
+        let mut index_map = KeyTable::new();
+
+        let a = index_map.get_or_create("a");
+        let b = index_map.get_or_create("b");
+        let c = index_map.get_or_create("c");
+        let d = index_map.get_or_create("d");
+
+        let mut agents: CompetitorStore<i64, ConstantDrift> = CompetitorStore::new();
+
+        for agent in [a, b, c, d] {
+            agents.insert(
+                agent,
+                Competitor {
+                    rating: Rating::new(
+                        Gaussian::from_ms(25.0, 25.0 / 3.0),
+                        25.0 / 6.0,
+                        ConstantDrift(25.0 / 300.0),
+                    ),
+                    ..Default::default()
+                },
+            );
+        }
+
+        let mut ts = TimeSlice::new(0i64, 0.0);
+
+        ts.add_events(
+            vec![
+                vec![vec![a], vec![b]],
+                vec![vec![c], vec![d]],
+                vec![vec![a], vec![c]],
+            ],
+            vec![vec![1.0, 0.0], vec![1.0, 0.0], vec![1.0, 0.0]],
+            vec![],
+            vec![EventKind::Ranked; 3],
+            &agents,
+        );
+
+        assert_eq!(ts.color_groups.n_colors(), 2);
+        assert_eq!(ts.color_groups.groups[0], vec![0, 1]);
+        assert_eq!(ts.color_groups.groups[1], vec![2]);
+
+        assert_eq!(ts.color_groups.color_range(0), 0..2);
+        assert_eq!(ts.color_groups.color_range(1), 2..3);
+
+        // Events at positions 0 and 1 (color 0) must be disjoint — verify by
+        // checking that the agent sets of self.events[0] and self.events[1] do
+        // not include the agent at self.events[2].
+        let agents_in_ev2: Vec<Index> = ts.events[2].iter_agents().collect();
+        let agents_in_ev0: Vec<Index> = ts.events[0].iter_agents().collect();
+        let agents_in_ev1: Vec<Index> = ts.events[1].iter_agents().collect();
+        // ev0 and ev1 must be disjoint from each other (color-0 invariant).
+        assert!(agents_in_ev0.iter().all(|ag| !agents_in_ev1.contains(ag)));
+        // ev2 must share an agent with ev0 or ev1 (it needed its own color).
+        let ev2_overlaps_ev0 = agents_in_ev2.iter().any(|ag| agents_in_ev0.contains(ag));
+        let ev2_overlaps_ev1 = agents_in_ev2.iter().any(|ag| agents_in_ev1.contains(ag));
+        assert!(ev2_overlaps_ev0 || ev2_overlaps_ev1);
+    }
 }

tests/api_shape.rs

@@ -0,0 +1,248 @@
+//! Tests for the new T2 public API surface: typed add_events(iter) and the
+//! fluent event builder (added in Task 16).
+
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, ConvergenceOptions, Event, History, Member, Outcome, Team};
+
+#[test]
+fn add_events_bulk_via_iter() {
+    let mut h = History::builder()
+        .mu(0.0)
+        .sigma(2.0)
+        .beta(1.0)
+        .p_draw(0.0)
+        .drift(ConstantDrift(0.0))
+        .convergence(ConvergenceOptions {
+            max_iter: 30,
+            epsilon: 1e-6,
+        })
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![
+        Event {
+            time: 1,
+            teams: smallvec![
+                Team::with_members([Member::new("a")]),
+                Team::with_members([Member::new("b")]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+        Event {
+            time: 2,
+            teams: smallvec![
+                Team::with_members([Member::new("b")]),
+                Team::with_members([Member::new("c")]),
+            ],
+            outcome: Outcome::winner(0, 2),
+        },
+    ];
+
+    h.add_events(events).unwrap();
+    let report = h.converge().unwrap();
+    assert!(report.converged);
+    assert!(h.lookup(&"a").is_some());
+    assert!(h.lookup(&"b").is_some());
+    assert!(h.lookup(&"c").is_some());
+}
+
+#[test]
+fn add_events_draw() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.25)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("alice")]),
+            Team::with_members([Member::new("bob")]),
+        ],
+        outcome: Outcome::draw(2),
+    }];
+    h.add_events(events).unwrap();
+    h.converge().unwrap();
+}
+
+#[test]
+fn add_events_rejects_mismatched_outcome_ranks() {
+    use trueskill_tt::InferenceError;
+    let mut h: History = History::builder().build();
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::ranking([0, 1, 2]), // 3 ranks but 2 teams
+    }];
+    let err = h.add_events(events).unwrap_err();
+    assert!(matches!(err, InferenceError::MismatchedShape { .. }));
+}
+
+#[test]
+fn fluent_event_builder_basic() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .build();
+
+    h.event(1)
+        .team(["alice", "bob"])
+        .weights([1.0, 0.7])
+        .team(["carol"])
+        .ranking([1, 0])
+        .commit()
+        .unwrap();
+
+    let report = h.converge().unwrap();
+    assert!(report.converged);
+    assert!(h.lookup(&"alice").is_some());
+    assert!(h.lookup(&"bob").is_some());
+    assert!(h.lookup(&"carol").is_some());
+}
+
+#[test]
+fn fluent_event_builder_winner_convenience() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .build();
+
+    h.event(1)
+        .team(["alice"])
+        .team(["bob"])
+        .winner(0)
+        .commit()
+        .unwrap();
+    h.converge().unwrap();
+}
+
+#[test]
+fn fluent_event_builder_draw() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.25)
+        .build();
+
+    h.event(1)
+        .team(["alice"])
+        .team(["bob"])
+        .draw()
+        .commit()
+        .unwrap();
+    h.converge().unwrap();
+}
+
+#[test]
+fn current_skill_and_learning_curve() {
+    use trueskill_tt::History;
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .build();
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.record_winner(&"a", &"b", 2).unwrap();
+    h.converge().unwrap();
+
+    let a = h.current_skill(&"a").unwrap();
+    assert!(a.mu() > 25.0);
+    let b = h.current_skill(&"b").unwrap();
+    assert!(b.mu() < 25.0);
+
+    let a_curve = h.learning_curve(&"a");
+    assert_eq!(a_curve.len(), 2);
+    assert_eq!(a_curve[0].0, 1);
+    assert_eq!(a_curve[1].0, 2);
+
+    let all = h.learning_curves();
+    assert_eq!(all.len(), 2);
+    assert!(all.contains_key("a"));
+    assert!(all.contains_key("b"));
+}
+
+#[test]
+fn log_evidence_total_vs_subset() {
+    use trueskill_tt::{ConstantDrift, History};
+    let mut h = History::builder()
+        .mu(0.0)
+        .sigma(6.0)
+        .beta(1.0)
+        .p_draw(0.0)
+        .drift(ConstantDrift(0.0))
+        .build();
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.record_winner(&"b", &"a", 2).unwrap();
+    let total = h.log_evidence();
+    let a_only = h.log_evidence_for(&[&"a"]);
+    assert!(total.is_finite());
+    assert!(a_only.is_finite());
+}
+
+#[test]
+fn predict_quality_two_teams() {
+    use trueskill_tt::History;
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .build();
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.converge().unwrap();
+
+    let q = h.predict_quality(&[&[&"a"], &[&"b"]]);
+    assert!(q > 0.0 && q <= 1.0);
+}
+
+#[test]
+fn predict_outcome_two_teams_sums_to_one() {
+    use trueskill_tt::History;
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .p_draw(0.0)
+        .build();
+    h.record_winner(&"a", &"b", 1).unwrap();
+    h.converge().unwrap();
+
+    let p = h.predict_outcome(&[&[&"a"], &[&"b"]]);
+    assert_eq!(p.len(), 2);
+    assert!((p[0] + p[1] - 1.0).abs() < 1e-9);
+    assert!(p[0] > p[1]);
+}
+
+#[test]
+fn fluent_event_builder_scores() {
+    use trueskill_tt::ConstantDrift;
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(0.0))
+        .build();
+
+    h.event(1)
+        .team(["alice"])
+        .team(["bob"])
+        .scores([12.0, 4.0])
+        .commit()
+        .unwrap();
+    h.converge().unwrap();
+
+    let a = h.current_skill(&"alice").unwrap();
+    let b = h.current_skill(&"bob").unwrap();
+    assert!(a.mu() > b.mu());
+}

tests/determinism.rs

@@ -0,0 +1,100 @@
+//! Determinism tests: identical posteriors across RAYON_NUM_THREADS
+//! values. Only compiled with the `rayon` feature.
+
+#![cfg(feature = "rayon")]
+
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, ConvergenceOptions, Event, History, Member, Outcome, Team};
+
+/// Build a deterministic workload using a simple LCG (no external rand crate).
+fn build_and_converge(seed: u64) -> Vec<(i64, trueskill_tt::Gaussian)> {
+    let mut h = History::<i64, _, _, String>::builder_with_key()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .convergence(ConvergenceOptions {
+            max_iter: 30,
+            epsilon: 1e-6,
+        })
+        .build();
+
+    // LCG for deterministic pseudo-random ints.
+    let mut rng = seed;
+    let mut next = || {
+        rng = rng
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(1442695040888963407);
+        rng
+    };
+
+    let mut events: Vec<Event<i64, String>> = Vec::with_capacity(200);
+    for ev_i in 0..200 {
+        let a = (next() % 40) as usize;
+        let mut b = (next() % 40) as usize;
+        while b == a {
+            b = (next() % 40) as usize;
+        }
+        // ~10 events per slice so color groups have material parallelism.
+        events.push(Event {
+            time: (ev_i as i64 / 10) + 1,
+            teams: smallvec![
+                Team::with_members([Member::new(format!("p{a}"))]),
+                Team::with_members([Member::new(format!("p{b}"))]),
+            ],
+            outcome: Outcome::winner((next() % 2) as u32, 2),
+        });
+    }
+    h.add_events(events).unwrap();
+    h.converge().unwrap();
+    // Sample one competitor's curve for the comparison.
+    h.learning_curve("p0")
+}
+
+#[test]
+fn posteriors_identical_across_thread_counts() {
+    let sizes = [1usize, 2, 4, 8];
+    let mut results: Vec<Vec<(i64, trueskill_tt::Gaussian)>> = Vec::new();
+    for &n in &sizes {
+        let pool = rayon::ThreadPoolBuilder::new()
+            .num_threads(n)
+            .build()
+            .expect("rayon pool build");
+        let curve = pool.install(|| build_and_converge(42));
+        results.push(curve);
+    }
+
+    let reference = &results[0];
+    for (i, curve) in results.iter().enumerate().skip(1) {
+        assert_eq!(
+            curve.len(),
+            reference.len(),
+            "curve length differs at {n} threads",
+            n = sizes[i],
+        );
+        for (j, (&(t_ref, g_ref), &(t, g))) in reference.iter().zip(curve.iter()).enumerate() {
+            assert_eq!(
+                t_ref,
+                t,
+                "time point {j} differs at {n} threads: ref={t_ref} vs got={t}",
+                n = sizes[i],
+            );
+            assert_eq!(
+                g_ref.mu().to_bits(),
+                g.mu().to_bits(),
+                "mu bits differ at {n} threads, time {t}: ref={ref_mu} got={got_mu}",
+                n = sizes[i],
+                ref_mu = g_ref.mu(),
+                got_mu = g.mu(),
+            );
+            assert_eq!(
+                g_ref.sigma().to_bits(),
+                g.sigma().to_bits(),
+                "sigma bits differ at {n} threads, time {t}: ref={ref_sigma} got={got_sigma}",
+                n = sizes[i],
+                ref_sigma = g_ref.sigma(),
+                got_sigma = g.sigma(),
+            );
+        }
+    }
+}

tests/equivalence.rs

@@ -0,0 +1,62 @@
+//! Equivalence tests: every historical golden from the pre-T2 tests is
+//! reproduced here at the integration level via the new public API.
+//!
+//! The in-crate tests in `src/history.rs::tests` and
+//! `src/time_slice.rs::tests` are the primary regression net for numerical
+//! behavior. This file provides Game-level goldens that stand alone and are
+//! more naturally expressed as integration tests.
+
+use approx::assert_ulps_eq;
+use trueskill_tt::{ConstantDrift, Game, GameOptions, Gaussian, Outcome, Rating};
+
+type R = Rating<i64, ConstantDrift>;
+
+fn ts_rating(mu: f64, sigma: f64, beta: f64, gamma: f64) -> R {
+    R::new(Gaussian::from_ms(mu, sigma), beta, ConstantDrift(gamma))
+}
+
+#[test]
+fn game_1v1_golden_matches_historical() {
+    let a = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
+    let b = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
+    let (a_post, b_post) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2)).unwrap();
+    // Historical golden from pre-T2 test_1vs1 (team 0 wins):
+    assert_ulps_eq!(
+        a_post,
+        Gaussian::from_ms(29.205220, 7.194481),
+        epsilon = 1e-6
+    );
+    assert_ulps_eq!(
+        b_post,
+        Gaussian::from_ms(20.794779, 7.194481),
+        epsilon = 1e-6
+    );
+}
+
+#[test]
+fn game_1v1_draw_golden() {
+    let a = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
+    let b = ts_rating(25.0, 25.0 / 3.0, 25.0 / 6.0, 25.0 / 300.0);
+    let g = Game::<i64, _>::ranked(
+        &[&[a], &[b]],
+        Outcome::draw(2),
+        &GameOptions {
+            p_draw: 0.25,
+            score_sigma: 1.0,
+            convergence: Default::default(),
+        },
+    )
+    .unwrap();
+    let p = g.posteriors();
+    // Historical golden from pre-T2 test_1vs1_draw:
+    assert_ulps_eq!(
+        p[0][0],
+        Gaussian::from_ms(24.999999, 6.469480),
+        epsilon = 1e-6
+    );
+    assert_ulps_eq!(
+        p[1][0],
+        Gaussian::from_ms(24.999999, 6.469480),
+        epsilon = 1e-6
+    );
+}

tests/game.rs

@@ -0,0 +1,97 @@
+use trueskill_tt::{
+    ConstantDrift, ConvergenceOptions, Game, GameOptions, Gaussian, InferenceError, Outcome, Rating,
+};
+
+type R = Rating<i64, ConstantDrift>;
+
+fn default_rating() -> R {
+    R::new(
+        Gaussian::from_ms(25.0, 25.0 / 3.0),
+        25.0 / 6.0,
+        ConstantDrift(25.0 / 300.0),
+    )
+}
+
+#[test]
+fn game_ranked_1v1_golden() {
+    let a = default_rating();
+    let b = default_rating();
+    let g = Game::<i64, _>::ranked(
+        &[&[a], &[b]],
+        Outcome::winner(0, 2),
+        &GameOptions::default(),
+    )
+    .unwrap();
+    let p = g.posteriors();
+    assert!(p[0][0].mu() > 25.0);
+    assert!(p[1][0].mu() < 25.0);
+    assert!((p[0][0].sigma() - p[1][0].sigma()).abs() < 1e-6);
+}
+
+#[test]
+fn game_one_v_one_shortcut() {
+    let a = default_rating();
+    let b = default_rating();
+    let (a_post, b_post) = Game::<i64, _>::one_v_one(&a, &b, Outcome::winner(0, 2)).unwrap();
+    assert!(a_post.mu() > 25.0);
+    assert!(b_post.mu() < 25.0);
+}
+
+#[test]
+fn game_ranked_rejects_bad_p_draw() {
+    let a = R::new(Gaussian::default(), 1.0, ConstantDrift(0.0));
+    let err = Game::<i64, _>::ranked(
+        &[&[a], &[a]],
+        Outcome::winner(0, 2),
+        &GameOptions {
+            p_draw: 1.5,
+            score_sigma: 1.0,
+            convergence: ConvergenceOptions::default(),
+        },
+    )
+    .unwrap_err();
+    assert!(matches!(err, InferenceError::InvalidProbability { .. }));
+}
+
+#[test]
+fn game_ranked_rejects_mismatched_ranks() {
+    let a = R::new(Gaussian::default(), 1.0, ConstantDrift(0.0));
+    let err = Game::<i64, _>::ranked(
+        &[&[a], &[a]],
+        Outcome::ranking([0, 1, 2]),
+        &GameOptions::default(),
+    )
+    .unwrap_err();
+    assert!(matches!(err, InferenceError::MismatchedShape { .. }));
+}
+
+#[test]
+fn game_free_for_all_three_players() {
+    let a = default_rating();
+    let b = default_rating();
+    let c = default_rating();
+    let g = Game::<i64, _>::free_for_all(
+        &[&a, &b, &c],
+        Outcome::ranking([0, 1, 2]),
+        &GameOptions::default(),
+    )
+    .unwrap();
+    let p = g.posteriors();
+    assert_eq!(p.len(), 3);
+    assert!(p[0][0].mu() > p[1][0].mu());
+    assert!(p[1][0].mu() > p[2][0].mu());
+}
+
+#[test]
+fn game_log_evidence_is_finite() {
+    let a = default_rating();
+    let b = default_rating();
+    let g = Game::<i64, _>::ranked(
+        &[&[a], &[b]],
+        Outcome::winner(0, 2),
+        &GameOptions::default(),
+    )
+    .unwrap();
+    assert!(g.log_evidence().is_finite());
+    assert!(g.log_evidence() < 0.0);
+}

tests/record_winner.rs

@@ -0,0 +1,54 @@
+use trueskill_tt::{ConstantDrift, ConvergenceOptions, History};
+
+#[test]
+fn record_winner_builds_history() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .convergence(ConvergenceOptions {
+            max_iter: 30,
+            epsilon: 1e-6,
+        })
+        .build();
+
+    h.record_winner(&"alice", &"bob", 1).unwrap();
+    h.converge().unwrap();
+
+    let a_idx = h.lookup(&"alice").unwrap();
+    let b_idx = h.lookup(&"bob").unwrap();
+
+    assert_ne!(a_idx, b_idx);
+}
+
+#[test]
+fn intern_is_idempotent() {
+    let mut h: History = History::builder().build();
+    let a1 = h.intern(&"alice");
+    let a2 = h.intern(&"alice");
+    assert_eq!(a1, a2);
+}
+
+#[test]
+fn lookup_returns_none_for_missing() {
+    let h: History = History::builder().build();
+    assert!(h.lookup(&"nobody").is_none());
+}
+
+#[test]
+fn record_draw_with_p_draw_set() {
+    let mut h = History::builder()
+        .mu(25.0)
+        .sigma(25.0 / 3.0)
+        .beta(25.0 / 6.0)
+        .drift(ConstantDrift(25.0 / 300.0))
+        .p_draw(0.25)
+        .build();
+
+    h.record_draw(&"alice", &"bob", 1).unwrap();
+    h.converge().unwrap();
+
+    assert!(h.lookup(&"alice").is_some());
+    assert!(h.lookup(&"bob").is_some());
+}

tests/scored.rs

@@ -0,0 +1,139 @@
+//! Integration tests for `Outcome::Scored` routing through `History::add_events`.
+
+use smallvec::smallvec;
+use trueskill_tt::{ConstantDrift, Event, History, Member, Outcome, Team};
+
+#[test]
+fn scored_two_team_one_event_pulls_winner_up() {
+    let mut h: History = History::builder()
+        .mu(0.0)
+        .sigma(2.0)
+        .beta(1.0)
+        .drift(ConstantDrift(0.0))
+        .score_sigma(1.0)
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::scores([10.0, 4.0]),
+    }];
+    h.add_events(events).unwrap();
+
+    let mu_a = h.current_skill(&"a").unwrap().mu();
+    let mu_b = h.current_skill(&"b").unwrap().mu();
+
+    assert!(
+        mu_a > 0.0,
+        "winner mu should be pulled up; got mu_a = {mu_a}"
+    );
+    assert!(
+        mu_b < 0.0,
+        "loser mu should be pulled down; got mu_b = {mu_b}"
+    );
+    assert!(
+        mu_a > mu_b,
+        "winner mu should exceed loser mu; got mu_a = {mu_a}, mu_b = {mu_b}"
+    );
+}
+
+#[test]
+fn scored_zero_margin_treats_as_tie() {
+    let mut h: History = History::builder()
+        .mu(0.0)
+        .sigma(2.0)
+        .beta(1.0)
+        .drift(ConstantDrift(0.0))
+        .score_sigma(1.0)
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::scores([5.0, 5.0]),
+    }];
+    h.add_events(events).unwrap();
+
+    let mu_a = h.current_skill(&"a").unwrap().mu();
+    let mu_b = h.current_skill(&"b").unwrap().mu();
+    let sigma_a = h.current_skill(&"a").unwrap().sigma();
+
+    // Equal scores: posterior means stay symmetric around the prior mean.
+    assert!(
+        (mu_a - mu_b).abs() < 1e-9,
+        "equal scores should leave mu_a == mu_b; got {mu_a} vs {mu_b}"
+    );
+    assert!(
+        mu_a.abs() < 1e-9,
+        "equal scores against equal priors should leave mu near zero; got {mu_a}"
+    );
+
+    // A zero-margin scored event still reduces uncertainty.
+    assert!(
+        sigma_a < 2.0,
+        "expected sigma to tighten below prior 2.0; got {}",
+        sigma_a
+    );
+}
+
+#[test]
+fn scored_three_team_partial_order() {
+    let mut h: History = History::builder()
+        .mu(0.0)
+        .sigma(2.0)
+        .beta(1.0)
+        .drift(ConstantDrift(0.0))
+        .score_sigma(1.0)
+        .build();
+
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+            Team::with_members([Member::new("c")]),
+        ],
+        outcome: Outcome::scores([9.0, 5.0, 1.0]),
+    }];
+    h.add_events(events).unwrap();
+
+    let mu_a = h.current_skill(&"a").unwrap().mu();
+    let mu_b = h.current_skill(&"b").unwrap().mu();
+    let mu_c = h.current_skill(&"c").unwrap().mu();
+
+    assert!(
+        mu_a > mu_b,
+        "team with highest score should rank highest; mu_a = {mu_a}, mu_b = {mu_b}"
+    );
+    assert!(
+        mu_b > mu_c,
+        "middle score should outrank lowest; mu_b = {mu_b}, mu_c = {mu_c}"
+    );
+}
+
+#[test]
+fn scored_rejects_outcome_team_count_mismatch() {
+    use trueskill_tt::InferenceError;
+
+    let mut h: History = History::builder().build();
+    let events: Vec<Event<i64, &'static str>> = vec![Event {
+        time: 1,
+        teams: smallvec![
+            Team::with_members([Member::new("a")]),
+            Team::with_members([Member::new("b")]),
+        ],
+        outcome: Outcome::scores([10.0, 4.0, 1.0]), // 3 scores, 2 teams
+    }];
+
+    let err = h.add_events(events).unwrap_err();
+    assert!(
+        matches!(err, InferenceError::MismatchedShape { .. }),
+        "expected MismatchedShape error, got {err:?}"
+    );
+}