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

# TrueSkill-TT Engine Redesign — Design

**Date:** 2026-04-23
**Status:** Approved (pending implementation plan)

## Summary

Comprehensive redesign of the TrueSkill-TT engine targeting four orthogonal goals:

1. **Performance** — substantially faster offline convergence and incremental online updates.
2. **Accuracy and richer match formats** — support for score margins, free-for-all with partial orders, correlated skills.
3. **Better convergence** — replace ad-hoc capped iteration with a pluggable `Schedule` trait covering all three nested loops.
4. **Better API surface** — typed event description, observer-based progress reporting, generic time axis, structured errors, ergonomic builders.

The design is comprehensive (Approach 1 of three considered) but delivered in five tiers so each step is independently shippable and validated by benchmarks.

## Goals & non-goals

**Goals**

- 10–30× speedup on the offline convergence path for representative workloads (1000+ players, 1000+ events, 30 iterations)
- Order-of-magnitude speedup on incremental "add a single event" workloads
- Pluggable factor graph allowing new factor types without engine changes
- Optional Rayon-backed parallelism on top of `Send + Sync`-correct internals
- Typed, ergonomic public API; replace nested `Vec<Vec<Vec<_>>>` shapes with `Event<T, K>` / `Team<K>` / `Member<K>`
- Generic time axis: `Untimed`, `i64`, or user-supplied
- Observer-based progress instead of `verbose: bool` + `println!`
- Structured `Result<_, InferenceError>` at API boundaries

**Non-goals**

- WebAssembly support is not a goal; we may break it if a crate or feature requires.
- No GPU offload.
- No `no_std` support.
- No persistent format / serde — possible future feature.
- No replacement of the Gaussian/EP approximation itself in this design (the underlying inference math stays the same; we change layout, dispatch, scheduling, and API around it).

## Workload assumptions

Baseline workload that drives perf decisions:

- ~1000+ players
- ~1000+ events total
- ~50–60 events per time slice (per day)
- Both online (incremental adds) and offline (full convergence) are common
- Offline convergence runs frequently

## Section 1 — Core types & traits

The foundation everything else builds on.

### `Gaussian` — natural-parameter storage

Switch storage from `(mu, sigma)` to natural parameters `(pi, tau)` where `pi = sigma⁻²`, `tau = mu · pi`. Multiplication and division dominate the hot path; in nat-params they are direct adds/subs of the components, no `sqrt`. Reads of `mu`/`sigma` become accessor methods (`tau / pi`, `1.0 / pi.sqrt()`). The trade is correct because reads are vanishingly rare compared to writes in EP.

```rust
pub struct Gaussian { pi: f64, tau: f64 }
pub const UNIFORM: Gaussian = Gaussian { pi: 0.0, tau: 0.0 }; // replaces N_INF
```

### `Time` trait

Replaces the bare `i64` time field. Keeps `History` parametric.

```rust
pub trait Time: Copy + Ord + Send + Sync + 'static {
    fn elapsed_to(&self, later: &Self) -> i64;
}
pub struct Untimed; // ZST for the no-time-axis case
impl Time for Untimed { fn elapsed_to(&self, _: &Self) -> i64 { 0 } }
impl Time for i64 { fn elapsed_to(&self, later: &Self) -> i64 { later - self } }
// Optional impls behind feature flags: time::OffsetDateTime, chrono types
```

### `Drift<T>` trait

Generic over `T: Time` so seasonal/calendar-aware drift is possible without going through `i64`.

```rust
pub trait Drift<T: Time>: Copy + Send + Sync {
    fn variance_delta(&self, from: &T, to: &T) -> f64;
}
```

`ConstantDrift(f64)` impl: `to.elapsed_to(from) as f64 * gamma * gamma`.

### `Index` and `KeyTable<K>`

`Index(usize)` is the handle into dense per-`History` `Vec` storage. Public, but intended for use by power users on hot paths who want to skip the `KeyTable` lookup. Casual API takes `&K`. `KeyTable<K>` (renamed from `IndexMap`, to avoid colliding with the `indexmap` crate's type) maps user keys → `Index`.

### `Observer` trait

Replaces `verbose: bool` + `println!`. Default no-op impls; user overrides what they need.

```rust
pub trait Observer<T: Time>: Send + Sync {
    fn on_iteration_end(&self, _iter: usize, _max_step: (f64, f64)) {}
    fn on_batch_processed(&self, _time: &T, _idx: usize, _n_events: usize) {}
    fn on_converged(&self, _iters: usize, _final_step: (f64, f64)) {}
}
pub struct NullObserver;
impl<T: Time> Observer<T> for NullObserver {}
```

### Trade-offs

- `Gaussian` natural-param representation: anyone reading `mu`/`sigma` in a hot loop pays a sqrt — but that's correct, hot reads are rare.
- `Time` as a trait (not enum) keeps it open-ended at zero runtime cost; default `History<i64, _>` keeps the call sites familiar.
- `Observer` is a trait (not a closure) so different sites can have different signatures without losing type safety. `NullObserver` is a ZST.

## Section 2 — Factor graph architecture

The current `Game::likelihoods` is a hand-rolled, hard-coded graph. To unlock richer formats and let us experiment with EP schedules, the graph itself becomes a data structure.

### Variable / Factor model

Variables hold their current Gaussian marginal. Factors hold their outgoing messages to each connected variable plus do the local computation. Standard EP: factor's update is "divide marginal by old outgoing → cavity → apply local approximation → multiply marginal by new outgoing."

```rust
pub trait Factor: Send + Sync {
    fn variables(&self) -> &[VarId];
    fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64); // returns max delta
    fn log_evidence(&self, _vars: &VarStore) -> f64 { 0.0 }
}
```

### Built-in factor catalog

| Factor | Purpose | Status |
|---|---|---|
| `PerformanceFactor` | skill → performance (add β² noise, optional weight) | replaces inline `performance() * weight` |
| `TeamSumFactor` | weighted sum of player perfs → team perf | replaces inline `fold` |
| `RankDiffFactor` | (team_a perf) − (team_b perf) → diff var | currently `team[e].posterior_win() − team[e+1].posterior_lose()` |
| `TruncFactor` | EP truncation: `P(diff > margin)` or `P(|diff| < margin)` for draws | wraps current `v_w` / `approx` |
| `MarginFactor` *(future)* | use observed score margin as soft evidence | enables richer match formats |
| `SynergyFactor` *(future)* | couples teammates' skills | enables different topology |
| `ScoreFactor` *(future)* | continuous outcome (e.g., points scored) | enables score-based outcomes |

The first four together exactly reproduce today's algorithm. The last three are extension slots.

### Game = factor graph + schedule

```rust
pub struct Game<S: Schedule = DefaultSchedule> {
    vars: VarStore,            // SoA: Vec<Gaussian> marginals
    factors: FactorList,       // enum dispatch over BuiltinFactor (see Open Questions)
    schedule: S,
}
```

Lean toward **enum dispatch** (`enum BuiltinFactor { Perf(...), Sum(...), RankDiff(...), Trunc(...), ... }`) over `Box<dyn Factor>` for the built-ins:

- avoids per-message vtable overhead in the hottest loop
- keeps factor data inline (no heap indirection)
- still allows user-defined factors via a `BuiltinFactor::Custom(Box<dyn Factor>)` variant

### Schedule trait

Controls iteration order and stopping. Default = current behavior (sweep forward, then backward, until ε or max iters). Pluggable so we can later try damped EP or junction-tree schedules.

### High-level constructors

```rust
Game::ranked(teams, results, options)    // dominant case
Game::free_for_all(players, ranking)     // FFA with possible ties
Game::custom(builder)                    // power users build their own graph
```

`GameOptions` carries iteration cap, epsilon, p_draw, and approximation choice. Today these are scattered between method args and module constants.

### Trade-offs

- Enum dispatch over trait objects for built-ins; richer factors drop in via new enum variants.
- Variables and factor messages stored as `Vec<Gaussian>` indexed by `VarId` / edge slot — flat, cache-friendly.
- `Schedule` is a generic parameter (zero-cost); most users get default; experimentation is open.

### Open question

Whether `enum BuiltinFactor` will feel too closed-world. The `Custom(Box<dyn Factor>)` escape hatch helps but inner-loop perf for user factors will be slower. Acceptable for now; flagged for future revisit if it becomes a problem.

## Section 3 — Storage layout (SoA + arenas)

### Dense Vec keyed by `Index`

Every `HashMap<Index, T>` becomes a `Vec<T>` (or `Vec<Option<T>>` for sparse) indexed directly by `Index.0`. The public-facing `KeyTable<K>` continues to map arbitrary keys → `Index`.

### SoA at hot layers, AoS at boundaries

The `Skill` struct stays as a public type for the API (returned from `learning_curves`, etc.), but inside `TimeSlice` we lay it out column-wise:

```rust
struct TimeSliceSkills {
    forward:    Vec<Gaussian>,   // [n_agents]
    backward:   Vec<Gaussian>,
    likelihood: Vec<Gaussian>,
    online:     Vec<Gaussian>,
    elapsed:    Vec<i64>,
    present:    Vec<bool>,
}
```

Within a slice, the inner loops touch one column repeatedly across many events — keeping the column contiguous improves cache utilization and makes the eventual SIMD step (Section 6) straightforward.

`Gaussian` itself stays as a single 16-byte struct in the `Vec<Gaussian>`. Splitting into two parallel `Vec<f64>`s wins for pure SIMD over thousands of Gaussians but loses for the random-access patterns dominant in EP. Revisit if benchmarks demand it.

### Arena allocator inside `Game`

Replace per-event allocations with a `ScratchArena` reused across calls.

```rust
pub struct ScratchArena {
    var_buf:     Vec<Gaussian>,
    factor_buf:  Vec<Gaussian>,    // edge messages
    bool_buf:    Vec<bool>,
    f64_buf:     Vec<f64>,
}
impl ScratchArena {
    fn reset(&mut self);                    // sets len=0, keeps capacity
    fn alloc_vars(&mut self, n: usize) -> &mut [Gaussian];
}
```

`TimeSlice` owns one `ScratchArena`; each event borrows it for the duration of its `Game` construction and inference. For the parallel-slice story (Section 6), each Rayon task gets its own arena.

### Per-event storage layout

Inside a `TimeSlice`, each event is stored column-wise as well, with `Item` inlined into team-level parallel arrays:

```rust
struct EventStorage {
    teams:   SmallVec<[TeamStorage; 4]>,
    outcome: Outcome,
    weights: SmallVec<[SmallVec<[f64; 4]>; 4]>,
    evidence: f64,
}
struct TeamStorage {
    competitors:   SmallVec<[Index; 4]>,    // who's on the team
    edge_messages: SmallVec<[Gaussian; 4]>, // outgoing message per slot
    output:        f64,
}
```

Iteration over `(competitor, edge_message)` pairs zips two slices — no per-element struct.

### SmallVec for typical shapes

Teams ≤ ~5 players, games ≤ ~8 teams. `SmallVec<[T; 8]>` for team membership and `SmallVec<[T; 4]>` for team rosters keeps the common case allocation-free.

### Trade-offs

- Dense `Vec<T>` keyed by `Index` is faster but means agent removal needs tombstones (or just leaves slots present-but-inactive). Acceptable: TrueSkill histories rarely remove players.
- SoA at `TimeSlice` level only, not at `History` level. `History` keeps `Vec<TimeSlice>` because slices are heterogeneous in size.
- One `ScratchArena` per `TimeSlice` keeps the lifetime story simple.

### Open question

The `TimeSliceSkills` sketch above uses (b) **dense + present mask**: one slot per agent in the history, indexed directly by `Index`, with a `present: Vec<bool>` mask for batches the agent didn't participate in. The alternative is (a) **sparse columnar**: a `Vec<Index>` of present agents and parallel `Vec<Gaussian>` columns of length `n_present`, with a separate lookup (binary search or auxiliary table) to find a given `Index`'s slot.

(b) gives O(1) lookup and SIMD-friendly columns but wastes memory for sparsely populated slices. (a) is leaner per-slice but pays per-lookup cost in the inner loop. Bench both during T0 and pick. Default proposal: (b), since modern systems are memory-rich and the parallelism story is cleaner.

## Section 4 — API surface

### Typed event description

```rust
pub struct Event<T: Time, K> {
    pub time: T,
    pub teams: SmallVec<[Team<K>; 4]>,
    pub outcome: Outcome,
}

pub struct Team<K> {
    pub members: SmallVec<[Member<K>; 4]>,
}

pub struct Member<K> {
    pub key: K,
    pub weight: f64,                 // default 1.0
    pub prior: Option<Rating>,       // per-event override
}

pub enum Outcome {
    Ranked(SmallVec<[u32; 4]>),  // rank per team; equal ranks = tie
    Scored(SmallVec<[f64; 4]>),  // continuous score per team (engages MarginFactor)
}
```

`Outcome::winner(0)`, `Outcome::draw()`, `Outcome::ranking([0,1,2])` are convenience constructors.

### Builders

```rust
let mut history = History::<i64, _>::builder()
    .mu(25.0).sigma(25.0/3.0).beta(25.0/6.0)
    .drift(ConstantDrift(0.03))
    .p_draw(0.10)
    .convergence(ConvergenceOptions { max_iter: 30, epsilon: 1e-6 })
    .observer(LogObserver::default())
    .build();
```

For the no-time case, type inference picks `Untimed`:

```rust
let mut history = History::<Untimed, _>::builder().build();
```

### Three-tier event ingestion

```rust
// 1. Bulk ingestion (high-throughput path)
history.add_events(events_iter)?;

// 2. One-off match (very common in practice)
history.record_winner("alice", "bob", time)?;
history.record_draw("alice", "bob", time)?;

// 3. Builder for irregular shapes
history.event(time)
    .team(["alice", "bob"]).weights([1.0, 0.7])
    .team(["carol"])
    .ranking([1, 0])
    .commit()?;
```

### Convergence & queries

```rust
let report: ConvergenceReport = history.converge()?;

let curve: Vec<(i64, Gaussian)> = history.learning_curve(&"alice");
let all = history.learning_curves();           // HashMap<&K, Vec<(T, Gaussian)>>
let now = history.current_skill(&"alice");     // Option<Gaussian>

let ev = history.log_evidence();
let ev_for = history.log_evidence_for(&["alice", "bob"]);

let q = history.predict_quality(&[&["alice"], &["bob"]]);
let p_win = history.predict_outcome(&[&["alice"], &["bob"]]);
```

### Standalone Game

```rust
let g = Game::ranked(&[&[alice], &[bob]], Outcome::winner(0), &options);
let post = g.posteriors();

// Convenience
let (a, b) = Game::one_v_one(&alice, &bob, Outcome::winner(0));
```

### Errors

Replace `debug_assert!`/`panic!` at the API boundary with `Result`.

```rust
pub enum InferenceError {
    MismatchedShape { kind: &'static str, expected: usize, got: usize },
    InvalidProbability { value: f64 },
    ConvergenceFailed { last_step: (f64, f64), iterations: usize },
    NegativePrecision { pi: f64 },
}
```

Hot inner loops still use `debug_assert!` for invariants the API has already enforced.

### Trade-offs

- Generic over user's `K`; engine works in `Index`. Public outputs use `&K`.
- `SmallVec` everywhere on the event-description path.
- Three-tier API so casual users don't drown in types and bulk users still get throughput.
- `Outcome` enum replaces the "lower number wins" `&[f64]` convention.

### Open question

Whether to expose `Index` directly to users via an `intern_key(&K) -> Index` method, letting hot-path callers skip the `KeyTable` lookup on every call. Recommendation: yes — public `Index` handle plus `history.lookup<Q: Borrow<K>>(&Q) -> Option<Index>`. The casual API still takes `&K` everywhere; power users can promote to `Index` when profiling demands.

## Section 4½ — Naming pass

| Current | New | Rationale |
|---|---|---|
| `History` | `History` (kept) | Matches upstream; reads cleanly. |
| `Batch` | `TimeSlice` | Says what it is: every event sharing one timestamp. |
| `Player` | `Rating` | The struct holds prior/beta/drift — that's a rating configuration. Resolves the `Player`/`Agent` confusion. |
| `Agent` | `Competitor` | Holds dynamic state for someone competing in the history; fits the domain. |
| `Skill` | `Skill` (kept) | Per-time-slice skill estimate; clearer than `BatchSkill`. |
| `Item` | inlined into `TeamStorage` columns (engine) / `Member<K>` (public) | Eliminates the per-element struct in the hot path; gives API users a clear "team member" name. |
| `Game` | `Game` (kept) | `Match` collides with Rust's `match`. |
| `Index` | `Index` (kept) | Internal handle. |
| `IndexMap` | `KeyTable` | Avoids confusion with the `indexmap` crate. |

## Section 5 — Convergence & message scheduling

### Three nested loops, one mechanism

The system has three nested convergence loops:

1. Within-game: EP sweeps over the factor graph
2. Within-time-slice: re-running games as inputs change
3. Cross-history: forward-pass then backward-pass over all slices

All three implement `Workload`; one `Schedule` impl drives all of them.

```rust
pub trait Schedule {
    fn run<W: Workload>(&self, workload: &mut W) -> ScheduleReport;
}

pub trait Workload {
    fn step(&mut self) -> (f64, f64);
    fn snapshot_evidence(&self) -> f64 { 0.0 }
}

pub struct ScheduleReport {
    pub iterations: usize,
    pub final_step: (f64, f64),
    pub converged: bool,
}
```

### Built-in schedules

| Schedule | Behavior | Use |
|---|---|---|
| `EpsilonOrMax { eps, max }` | Default. Sweep until `(dpi, dtau) ≤ eps` or `max` iters. | All three loops. Replicates current behavior. |
| `Damped { eps, max, alpha }` | Same, but writes `α·new + (1−α)·old`. | Stuck oscillations. |
| `Residual { eps, max }` | Priority-queue: re-update factor with largest pending delta first. | Faster convergence on uneven graphs. |
| `OneShot` | Exactly one pass, no convergence check. | Online incremental adds. |

### Stopping in natural-param space

Switch from `(|Δmu|, |Δsigma|) ≤ epsilon` to `(|Δpi|, |Δtau|) ≤ (eps_pi, eps_tau)`:

- `mu` and `sigma` are on different scales; one tolerance is wrong for both
- We store in nat-params anyway — checking convergence in mu/sigma costs free sqrts
- Nat-param delta is the natural geometry of the EP fixed point

Default `EpsilonOrMax::default()` exposes a single `epsilon` for simplicity; advanced ctor exposes both tolerances.

### Within-game improvements

- Replace hard-cap of 10 iterations with `GameOptions::schedule` that propagates `ScheduleReport` upward
- Fast path: graphs with no diff chain (1v1 with 1 iter sufficient) skip the loop entirely
- FFA / many-team ranks benefit from `Residual`; opt-in

### Within-slice and cross-history improvements

- **No more old/new HashMap snapshotting**: track deltas inline as we write under SoA
- **Per-slice dirty bits**: a `TimeSlice` whose neighbor messages haven't changed since its last full sweep doesn't need to re-run. Track `time_slice.dirty` and skip clean ones during the cross-history sweep. Big win for online-add (the locality case).

### `ConvergenceReport`

```rust
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 batches_skipped: usize,
}
```

`Observer` continues to receive per-iteration callbacks for live UI; `ConvergenceReport` is the post-hoc summary.

### Trade-offs

- One `Schedule` trait shared across loops — fewer concepts, more composable.
- Convergence checks in nat-param space — slightly different exact threshold than today; tests' epsilons re-tuned mechanically.
- Dirty-bit skipping changes iteration order vs. today; fixed point is the same, iteration counts may shift downward.
- `Residual` and `Damped` are opt-in; default behavior matches today closely.

### Open question

Whether `Schedule::run` should take an optional `Observer` reference. Recommendation: observation lives at a higher layer (`History::converge` calls observer hooks; `Schedule` is purely the loop driver).

## Section 6 — Concurrency & parallelism

### What's parallelizable

| Operation | Parallelism | Strategy |
|---|---|---|
| `History::converge()` (full forward+backward) | Sequential across slices | Within each slice: color-group events in parallel via Rayon |
| `History::add_events(...)` | Sequential append, but ingestion of typed events into `EventStorage` parallelizes trivially | n/a |
| `History::learning_curves()` | Per-key parallel | `into_par_iter()` |
| `History::log_evidence_for(targets)` | Per-batch parallel, reduce sum | `par_iter().map(...).sum()` |
| `Game` inference | Sequential | n/a (too small to amortize Rayon overhead) |

### Within-slice color-group parallelism

When events are added to a slice, partition them into color groups where events in the same color touch no shared `Index`. Within a color, run events in parallel via Rayon. Across colors, run sequentially. Preserves asynchronous-EP semantics exactly.

Alternative: synchronous EP with snapshot. All events read from a frozen skill snapshot, write deltas to thread-local buffers, barrier merges. Trivially parallel but weaker per-iteration convergence — needs damping. Available as a `Schedule` impl, opt-in.

### `Send + Sync` requirements

All public traits (`Time`, `Drift`, `Observer`, `Factor`, `Schedule`) require `Send + Sync`. `Observer` impls must be thread-safe (called from arbitrary worker threads).

### Rayon as default-on feature

`rayon` as default-on feature; with `default-features = false`, parallel paths fall back to sequential iterators behind `cfg(feature = "rayon")`.

### Expected speedup ballpark

For 1000 players, 60 events/slice × 1000 slices, 30 convergence iterations:

| Source | Estimated speedup vs. today |
|---|---|
| `HashMap` → dense `Vec` | 2–4× |
| Natural-param `Gaussian`, no-sqrt mul/div | 1.5–2× |
| Pre-allocated `ScratchArena` | 1.2–1.5× |
| Color-group parallel events in slice (8 cores) | 2–4× |
| Dirty-bit slice skipping (online add case) | 5–50× |
| **Combined (offline converge)** | ~10–30× |
| **Combined (online add)** | ~50–500× depending on locality |

These are pre-implementation estimates. Each tier validates with criterion.

### Trade-offs

- Color-group parallelism requires up-front graph coloring at ingestion. Cost: linear in events, run once per `add_events`. Cheap.
- Default = asynchronous EP (preserves current semantics). Synchronous opt-in only.
- Cross-slice sweep stays sequential; no speculative parallel sweeps.
- Rayon default-on but feature-gated.

### Open question

Whether to expose color-group partitioning to users. Recommendation: hidden by default, escape hatch via `add_events_with_partition(...)` for power users who already know their event independence.

## Section 7 — Migration, testing, and delivery plan

The crate is unreleased, so version-bump ceremony doesn't apply. Tiers are sequencing of work and milestones, not releases.

### Tier sequence

**T0 — Numerical parity (no API change)**

Internal-only. Public surface unchanged.

- Switch `Gaussian` storage to natural parameters `(pi, tau)`. `mu()`/`sigma()` become accessors.
- Replace `HashMap<Index, _>` with dense `Vec<_>` keyed by `Index.0` everywhere.
- Introduce `ScratchArena` inside `Batch` so `Game::new` stops allocating per-event.
- Drop the `panic!` in `mu_sigma`; return `Result` propagated upward.

**Acceptance:** existing test suite passes (bit-equal where possible, ULP-bounded where natural-param arithmetic shifts a rounding); `cargo bench` shows ≥3× win on `batch` benchmark; no API breakage.

**T1 — Factor graph machinery (internal-only)**

- Introduce `Factor`, `VarStore`, `Schedule` as `pub(crate)` types.
- Re-implement `Game::likelihoods()` on top of `BuiltinFactor::{Perf, TeamSum, RankDiff, Trunc}` driven by `EpsilonOrMax`.
- Replace within-game iteration tracking with `ScheduleReport`.

**Acceptance:** existing test suite passes (ULP-bounded); within-game iteration counts unchanged; benchmarks ≥ T0.

**T2 — New API surface (breaking)**

All renames and the new public API land together. No half-renamed intermediate state.

- New types: `Rating`, `TimeSlice`, `Competitor`, `Member<K>`, `Outcome`, `Event<T, K>`, `KeyTable<K>`.
- `Time` trait introduced; `History<T: Time, D: Drift<T>>` is generic.
- Three-tier API surface: `record_winner`, `event(...).team(...).commit()`, bulk `add_events(iter)`.
- `Observer` trait + `ConvergenceReport`; `verbose: bool` deleted.
- `panic!`/`debug_assert!` at API boundary become `Result<_, InferenceError>`.
- Promote `Factor`/`Schedule`/`VarStore` to `pub` under a `factors` module.

**Acceptance:** full test suite rewritten in new API; equivalence tests prove identical posteriors vs. old API on the same inputs.

**T3 — Concurrency**

- `Send + Sync` audit and bounds on all public traits.
- Color-group partitioning at `TimeSlice` ingestion.
- `rayon` as default-on feature with `#[cfg(feature = "rayon")]` fallback.
- Parallel paths: within-slice color groups, `learning_curves`, `log_evidence_for`.

**Acceptance:** deterministic posteriors across `RAYON_NUM_THREADS={1,2,4,8}`; benchmarks show >2× on 8-core for offline converge.

**T4 — Richer factor types & schedules**

Each shipped independently after T3.

- `MarginFactor` → enables `Outcome::Scored`.
- `Damped` and `Residual` schedules.
- `SynergyFactor`, `ScoreFactor` → same pattern when wanted.

Each comes with its own benchmark and a worked example in `examples/`.

### Testing strategy

| Layer | Approach |
|---|---|
| **Numerical correctness** | Keep existing hardcoded golden values from `test_1vs1`, `test_1vs1_draw`, `test_2vs1vs2_mixed`, etc. through T0–T1 unchanged. They are a regression net against the original Python port. |
| **API parity** | T2 adds an `equivalence` test module that runs identical inputs through old vs. new construction and compares posteriors within ULPs. |
| **Property tests** | Add `proptest` for: factor graph fixed-point invariance under message order, `Outcome` round-trip, `Gaussian` mul/div associativity in nat-params, schedule convergence regardless of starting state. |
| **Determinism** | T3 adds tests that run identical input across multiple Rayon thread counts and assert identical posteriors. |
| **Benchmark gates** | Each tier has a "must not regress" gate vs. the previous tier on the existing `batch` and `gaussian` criterion suites. T0 must beat baseline by ≥3×; T1 ≥ T0; etc. |

### Risk management

- **T0 risk: rounding drift in tests.** Mitigation: where natural-param arithmetic legitimately changes the last ULPs, update goldens *and* simultaneously add a parity test against a snapshot taken from baseline to prove the difference is bounded.
- **T2 risk: API design mistakes.** Mitigation: review the spec and a worked example before implementing; iterate on feedback.
- **T3 risk: subtle race conditions in color-group partitioning.** Mitigation: `loom` tests for the merge step; deterministic-output assertion across thread counts.
- **Cross-tier risk: scope creep.** Each tier has a closed checklist; new ideas go to the next tier's wishlist.

### What we're explicitly *not* doing

- No GPU offload.
- No `no_std` support.
- No serde / persistence in this design.
- No incremental online API beyond `record_winner` / `add_events`.

## Open questions summary

Collected here for the review pass:

1. **`enum BuiltinFactor` extensibility** — may feel too closed-world; revisit if user-defined factors via `Custom(Box<dyn Factor>)` become common.
2. **Sparse vs. dense per-slice skill storage** — default to dense + `present` mask; sparse columnar is the alternative. Decided by T0 benchmarks.
3. **`Index` exposure for hot paths** — expose `intern_key`/`lookup` so power users can promote `&K` to `Index` and skip the `KeyTable` lookup; casual API still takes `&K` everywhere.
4. **`Schedule::run` and observer wiring** — observation stays at higher layer (`History::converge` calls observer hooks; `Schedule` is purely the loop driver).
5. **Color-group partition exposure** — hidden by default, escape hatch via `add_events_with_partition(...)`.