T0 + T1 + T2: engine redesign through new API surface (#1)

Implements tiers T0, T1, T2 of `docs/superpowers/specs/2026-04-23-trueskill-engine-redesign-design.md`. All three tiers have landed together on this branch because they build on one another; this PR rolls them up for a single review pass. Per-tier plans: - T0: `docs/superpowers/plans/2026-04-23-t0-numerical-parity.md` - T1: `docs/superpowers/plans/2026-04-24-t1-factor-graph.md` - T2: `docs/superpowers/plans/2026-04-24-t2-new-api-surface.md` ## Summary ### T0 — Numerical parity (internal) - `Gaussian` switched to natural-parameter storage `(pi, tau)`; mul/div now ~7× faster (218 ps vs 1.57 ns). - `HashMap<Index, _>` → dense `Vec<_>` keyed by `Index.0` (via `AgentStore<D>`, `SkillStore`). - `ScratchArena` eliminates per-event allocations in `Game::likelihoods`. - `InferenceError` seed type added (1 variant). - 38 → 53 tests passing through T1. - Benchmark: `Batch::iteration` 29.84 → 21.25 µs. ### T1 — Factor graph machinery (internal) - `Factor` trait + `BuiltinFactor` enum (TeamSum / RankDiff / Trunc) driving within-game inference. - `VarStore` flat storage for variable marginals. - `Schedule` trait + `EpsilonOrMax` impl replacing the hand-rolled EP loop. - `Game::likelihoods` rebuilt on the factor-graph machinery; iteration counts and goldens preserved to within 1e-6. - 53 tests passing. - Benchmark: `Batch::iteration` 23.01 µs (slight regression absorbed in T2). ### T2 — New API surface (breaking) **Renames:** - `IndexMap → KeyTable`, `Player → Rating`, `Agent → Competitor`, `Batch → TimeSlice` **New types:** - `Time` trait with `Untimed` ZST and `i64` impls; `Drift<T>`, `Rating<T, D>`, `Competitor<T, D>`, `TimeSlice<T>`, `History<T, D, O, K>` all generic. - `Event<T, K>`, `Team<K>`, `Member<K>`, `Outcome` (`Ranked` variant; `#[non_exhaustive]`). - `Observer<T>` trait + `NullObserver`. - `ConvergenceOptions`, `ConvergenceReport`. - `GameOptions`, `OwnedGame<T, D>`. **Three-tier ingestion:** - `history.record_winner(&K, &K, T)` / `record_draw(&K, &K, T)` — 1v1 convenience. - `history.add_events(iter)` — typed bulk. - `history.event(T).team([...]).weights([...]).ranking([...]).commit()` — fluent. **Query API:** `current_skill`, `learning_curve`, `learning_curves` (keyed on `K`), `log_evidence`, `log_evidence_for`, `predict_quality`, `predict_outcome`. **Game constructors:** `ranked`, `one_v_one`, `free_for_all`, `custom` — all returning `Result<_, InferenceError>`. **`factors` module:** `Factor`, `Schedule`, `VarStore`, `VarId`, `BuiltinFactor`, `EpsilonOrMax`, `ScheduleReport`, `TeamSumFactor`, `RankDiffFactor`, `TruncFactor` now public. **Errors:** `InferenceError` gains `MismatchedShape`, `InvalidProbability`, `ConvergenceFailed`; boundary panics converted to `Result`. **Removed (breaking):** `History::convergence(iters, eps, verbose)`, `HistoryBuilder::gamma(f64)`, `HistoryBuilder::time(bool)`, `History.time: bool`, `learning_curves_by_index`, nested-Vec public `add_events`. ## Behavior change (documented in CHANGELOG) `Time = Untimed` has `elapsed_to → 0`, so no drift accumulates between slices. The old `time=false` mode implicitly forced `elapsed=1` on reappearance via an `i64::MAX` sentinel — that quirk is not reproducible under a typed time axis. Tests that depended on it now use `History::<i64, _>` with explicit `1..=n` timestamps. One test (`test_env_ttt`) had 3 Gaussian goldens updated to reflect the corrected semantics; documented in commit `33a7d90`. ## Final numbers | Metric | Before T0 | After T2 | Delta | |---|---|---|---| | `Batch::iteration` | 29.84 µs | 21.36 µs | **-28%** | | `Gaussian::mul` | 1.57 ns | 219 ps | **-86%** | | `Gaussian::div` | 1.57 ns | 219 ps | **-86%** | | Tests passing | 38 | 90 | +52 | All other Gaussian ops unchanged (~219 ps add/sub, ~264 ps pi/tau reads). ## Test plan - [x] `cargo test --features approx` — 90/90 pass (68 lib + 10 api_shape + 6 game + 4 record_winner + 2 equivalence) - [x] `cargo clippy --all-targets --features approx -- -D warnings` — clean - [x] `cargo +nightly fmt --check` — clean - [x] `cargo bench --bench batch` — 21.36 µs - [x] `cargo bench --bench gaussian` — unchanged from T1 - [x] `cargo run --example atp --features approx` — rewritten in new API, runs clean - [x] Historical Game-level goldens preserved in `tests/equivalence.rs` - [x] Public API matches spec Section 4 (verified by integration tests in `tests/api_shape.rs`) ## Commit history ~45 commits total across T0 + T1 + T2. Each task is self-contained and individually tested; the branch is bisectable. See `git log main..t2-new-api-surface` for the full list. ## Deferred to later tiers - `Outcome::Scored` + `MarginFactor` — T4 - `Damped` / `Residual` schedules — T4 - `Send + Sync` bounds + Rayon parallelism — T3 - N-team `predict_outcome` — T4 - `Game::custom` full ergonomics — T4 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: #1 Co-authored-by: Anders Olsson <anders.e.olsson@gmail.com> Co-committed-by: Anders Olsson <anders.e.olsson@gmail.com>
2026-04-24 11:20:04 +00:00
parent a14df02089
commit d2aab82c1e
44 changed files with 10541 additions and 1325 deletions
@@ -0,0 +1,130 @@
+use crate::{
+    N_INF, approx, cdf,
+    factor::{Factor, VarId, VarStore},
+    gaussian::Gaussian,
+};
+
+/// EP truncation factor on a diff variable.
+///
+/// Implements the rectified-Gaussian approximation that turns a diff
+/// distribution into a "this team rank-beats that team" or "tied" likelihood.
+/// Stores its outgoing message to the diff variable so the cavity computation
+/// produces the correct EP message on each propagation.
+#[derive(Debug)]
+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.
+    pub(crate) evidence_cached: Option<f64>,
+}
+
+impl TruncFactor {
+    pub fn new(diff: VarId, margin: f64, tie: bool) -> Self {
+        Self {
+            diff,
+            margin,
+            tie,
+            msg: N_INF,
+            evidence_cached: None,
+        }
+    }
+}
+
+impl Factor for TruncFactor {
+    fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64) {
+        let marginal = vars.get(self.diff);
+        // Cavity: marginal divided by our outgoing message.
+        let cavity = marginal / self.msg;
+
+        // First-time-only: cache the evidence contribution from the cavity.
+        if self.evidence_cached.is_none() {
+            self.evidence_cached = Some(cavity_evidence(cavity, self.margin, self.tie));
+        }
+
+        // Apply the truncation approximation to the cavity.
+        let trunc = approx(cavity, self.margin, self.tie);
+
+        // New outgoing message such that cavity * new_msg = trunc.
+        let new_msg = trunc / cavity;
+        let old_msg = self.msg;
+        self.msg = new_msg;
+
+        // Update the marginal: marginal_new = cavity * new_msg = trunc.
+        vars.set(self.diff, trunc);
+
+        old_msg.delta(new_msg)
+    }
+
+    fn log_evidence(&self, _vars: &VarStore) -> f64 {
+        self.evidence_cached.unwrap_or(1.0).ln()
+    }
+}
+
+/// P(diff > margin) for non-tie, P(|diff| < margin) for tie.
+fn cavity_evidence(diff: Gaussian, margin: f64, tie: bool) -> f64 {
+    if tie {
+        cdf(margin, diff.mu(), diff.sigma()) - cdf(-margin, diff.mu(), diff.sigma())
+    } else {
+        1.0 - cdf(margin, diff.mu(), diff.sigma())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::factor::VarStore;
+
+    #[test]
+    fn idempotent_after_convergence() {
+        // After enough iterations, propagate should return ~0 delta.
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(2.0, 3.0));
+
+        let mut f = TruncFactor::new(diff, 0.0, false);
+
+        // Propagate many times; delta should drop toward 0.
+        let mut last = (f64::INFINITY, f64::INFINITY);
+        for _ in 0..20 {
+            last = f.propagate(&mut vars);
+        }
+        assert!(last.0 < 1e-10, "expected converged delta, got {}", last.0);
+        assert!(last.1 < 1e-10);
+    }
+
+    #[test]
+    fn evidence_cached_on_first_propagate() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(2.0, 3.0));
+
+        let mut f = TruncFactor::new(diff, 0.0, false);
+        assert!(f.evidence_cached.is_none());
+
+        f.propagate(&mut vars);
+        assert!(f.evidence_cached.is_some());
+        let first = f.evidence_cached.unwrap();
+
+        // Evidence should be P(diff > 0) for diff ~ N(2, 9) ≈ 0.748
+        assert!(first > 0.7);
+        assert!(first < 0.8);
+
+        // Subsequent propagations don't change it.
+        f.propagate(&mut vars);
+        assert_eq!(f.evidence_cached.unwrap(), first);
+    }
+
+    #[test]
+    fn tie_evidence_uses_two_sided() {
+        let mut vars = VarStore::new();
+        let diff = vars.alloc(Gaussian::from_ms(0.0, 2.0));
+
+        let mut f = TruncFactor::new(diff, 1.0, true);
+        f.propagate(&mut vars);
+
+        // For diff ~ N(0, 4), tie=true with margin=1: P(-1 < diff < 1) ≈ 0.383
+        let ev = f.evidence_cached.unwrap();
+        assert!(ev > 0.35 && ev < 0.42);
+    }
+}