trueskill-tt/CHANGELOG.md

Changelog

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

• feat: added a Drift trait and a "default" ConstantDrift implementation

Miscellaneous Tasks

• chore: added cliff.toml, release.toml and rustfmt.toml
• chore: clean up

Other (unconventional)

• Initial commit.
• Begin working on batch.
• Passing tests for Batch
• Working on History struct. First test is passing.
• More test passing for History
• Added more functions to History
• Remove Display impl, better to use Debug
• Use flatten instead of flat_map
• Handle case where there is no time
• It works, or so it seems
• Use PlayerIndex instead of String
• Inline a lot of functions
• Refactor some code
• Refactor some stuff
• Port from julia version instead
• More things, better things, awesome
• More tests, more code
• More things, more tests
• Fix tests
• More tests
• More tests
• Added builder for History, and start migrating test to use builder instead.
• Update test to use builder
• Remove unused code
• Use and Index struct instead of str and String for player id
• Update example so now it works, and thats, well, good
• Update test to use assert_ulps_eq
• Fixed test
• Change time to use i64 instead of u64
• Small change
• Clean up example
• Update crates and added methods to get a key or all keys in an IndexMap
• Added a get function to IndexMap
• Agents doens't have to be behind a mutable reference in within_prior
• Agents doens't have to be behind a mutable reference in within_priors
• Refactor so we can see if there is any way to improve the performance
• Fix clippy warning
• More refactoring
• Remove warnings and refactor some code
• Added benchmark for Batch
• Added default implementation for TeamMessage
• Remove unused mut reference
• Make it more rusty
• More rustifying
• Small refactor
• Rename d to diff, and t to team
• Added more links to readme
• Fix broken link in README
• Update crates
• Clean up
• Dry my eyes
• Remove unnecessary allocations
• Fix clippy warning
• Refactor history
• Rename variables
• Move stuff around
• Added quality function
• Make quality a free standing function instead
• Improve performance
• Change assert to debug_assert
• Added todo to readme, and documentation for quality function
• Basic test for quality
• Ignore temp folder
• Update edition
• Small changes for new 2024 edition
• remove notepad
• added benchmark

Styling

• style: cargo fmt