diff --git a/docs/superpowers/plans/2026-05-08-damped-schedule.md b/docs/superpowers/plans/2026-05-08-damped-schedule.md new file mode 100644 index 0000000..724a190 --- /dev/null +++ b/docs/superpowers/plans/2026-05-08-damped-schedule.md @@ -0,0 +1,1088 @@ +# Damped EP Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add an opt-in `ConvergenceOptions::alpha` knob that damps within-game EP message updates, plumbed through `run_chain` to `TruncFactor` and `MarginFactor` via a new `Gaussian::damp_natural` helper. `alpha = 1.0` (default) keeps every existing golden bit-equal. + +**Architecture:** Game-local. The `Schedule` trait at `src/schedule.rs` is **not** touched — it's shipped infrastructure that `run_chain` doesn't currently call. Damping is implemented directly inside `TruncFactor::propagate_with_alpha` / `MarginFactor::propagate_with_alpha` (inherent methods, not the public `Factor` trait). `DiffFactor::propagate` (game-private) gains an `alpha` parameter and dispatches into them. `Game<'a, T, D>` and `OwnedGame` gain a `convergence: ConvergenceOptions` field set at construction; `run_chain` reads `self.convergence.{epsilon, max_iter, alpha}` instead of hardcoded values. + +**Tech Stack:** Rust 2024, `cargo +nightly fmt`, `cargo clippy`, `cargo test --lib`. + +--- + +## Spec reference + +`docs/superpowers/specs/2026-05-08-damped-schedule-design.md` + +## File map + +| File | Why touched | +|---|---| +| `src/gaussian.rs` | Add `damp_natural` helper + tests | +| `src/convergence.rs` | Add `alpha: f64` field to `ConvergenceOptions` | +| `src/factor/trunc.rs` | Add inherent `propagate_with_alpha`; trait `propagate` delegates with `alpha=1.0` | +| `src/factor/margin.rs` | Same shape as `trunc.rs` | +| `src/game.rs` | `DiffFactor::propagate` gains `alpha`; `Game`/`OwnedGame` gain `convergence` field; `ranked_with_arena`/`scored_with_arena` accept it; `run_chain` reads it; ~20 test callsites updated | + +## Pre-flight context for the implementer + +- `Gaussian` stores natural parameters `pi = 1/sigma²` and `tau = mu/sigma²`. The accessors are `pi()`, `tau()`. Constructor `Gaussian::from_natural(pi, tau)` is `pub(crate)`. +- `Gaussian::Mul` already exists but it is **distribution scaling** (`sigma → sigma·|scalar|`), NOT nat-param scaling. Do not reuse it for damping. +- `Factor::propagate(&mut self, vars: &mut VarStore) -> (f64, f64)` is the public trait method. Keep it intact (signature must not change) — `Schedule::run` depends on it. +- `DiffFactor` (`src/game.rs:20-54`) is `pub(crate)`. Its current signature is `propagate(&mut self, vars: &mut VarStore) -> (f64, f64)`. Adding `alpha: f64` here is fine — only `run_chain` calls it. +- `ConvergenceOptions` lives at `src/convergence.rs`. It is `Copy + Clone + Debug`. Keep it `Copy`. +- `run_chain` body (`src/game.rs:236-348`) currently hardcodes `tuple_gt(step, 1e-6) && iter < 10`. Three call sites use `lf.propagate(&mut arena.vars)` — forward sweep, backward sweep, and the `n_diffs == 1` special case. +- `Game<'a, T, D>` (`src/game.rs:148-156`) and `OwnedGame` (`src/game.rs:83-92`) both have public-API entry points (`Game::ranked`, `Game::scored`, `Game::free_for_all`, `Game::one_v_one`). These take `&GameOptions`. The `convergence` field on `GameOptions` is silently dropped today by `OwnedGame::new` / `OwnedGame::new_scored` — fixing this is part of the work. +- All ~20 `ranked_with_arena` / `scored_with_arena` callsites are in tests inside `src/game.rs`. None are in `tests/` integration files. + +--- + +### Task 1: Add `Gaussian::damp_natural` helper + +**Files:** +- Modify: `src/gaussian.rs` (add method to existing `impl Gaussian` block + tests in the existing `#[cfg(test)] mod tests`) + +- [ ] **Step 1: Write the failing tests** + +In `src/gaussian.rs`, find the existing `#[cfg(test)] mod tests { ... }` block (near the end of the file). Add these three tests at the end of that module: + +```rust +#[test] +fn damp_natural_alpha_one_returns_new() { + let old = Gaussian::from_ms(1.0, 2.0); + let new = Gaussian::from_ms(5.0, 0.5); + let damped = old.damp_natural(new, 1.0); + assert_eq!(damped.pi(), new.pi()); + assert_eq!(damped.tau(), new.tau()); +} + +#[test] +fn damp_natural_alpha_zero_returns_self() { + let old = Gaussian::from_ms(1.0, 2.0); + let new = Gaussian::from_ms(5.0, 0.5); + let damped = old.damp_natural(new, 0.0); + assert_eq!(damped.pi(), old.pi()); + assert_eq!(damped.tau(), old.tau()); +} + +#[test] +fn damp_natural_alpha_half_is_midpoint_in_natural_params() { + let old = Gaussian::from_ms(1.0, 2.0); + let new = Gaussian::from_ms(5.0, 0.5); + let damped = old.damp_natural(new, 0.5); + let expected_pi = 0.5 * new.pi() + 0.5 * old.pi(); + let expected_tau = 0.5 * new.tau() + 0.5 * old.tau(); + assert!((damped.pi() - expected_pi).abs() < 1e-12); + assert!((damped.tau() - expected_tau).abs() < 1e-12); +} +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `cargo test --lib gaussian::tests::damp_natural` + +Expected: 3 errors, all of the form "no method named `damp_natural` found for struct `Gaussian`". + +- [ ] **Step 3: Implement `damp_natural`** + +In `src/gaussian.rs`, find the existing `impl Gaussian { ... }` block (the one containing `from_ms`, `from_natural`, `pi()`, `tau()`, `mu()`, `sigma()`). Add this method at the end of that impl block, immediately before the closing `}`: + +```rust +/// EP damping in natural-parameter space: `α·new + (1−α)·self`. +/// +/// Used by within-game inference to stabilise oscillating fixed-point +/// loops on hard graphs. `alpha = 1.0` returns `new` exactly; +/// `alpha < 1.0` shrinks each per-step update. +pub fn damp_natural(self, new: Gaussian, alpha: f64) -> Gaussian { + Gaussian::from_natural( + alpha * new.pi() + (1.0 - alpha) * self.pi(), + alpha * new.tau() + (1.0 - alpha) * self.tau(), + ) +} +``` + +- [ ] **Step 4: Run the tests to verify they pass** + +Run: `cargo test --lib gaussian::tests::damp_natural` + +Expected: 3 passed. + +- [ ] **Step 5: Run the full test suite to confirm no regression** + +Run: `cargo test --lib` + +Expected: all passing, total count = previous baseline + 3. + +- [ ] **Step 6: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --lib -- -D warnings` + +Expected: no diff, no warnings. + +- [ ] **Step 7: Commit** + +```bash +git add src/gaussian.rs +git commit -m "$(cat <<'EOF' +feat(gaussian): add damp_natural helper for EP damping + +Computes α·new + (1−α)·self in natural-parameter space. Will be used +by TruncFactor and MarginFactor to support opt-in EP damping via +ConvergenceOptions::alpha. +EOF +)" +``` + +--- + +### Task 2: Add `ConvergenceOptions::alpha` field + +**Files:** +- Modify: `src/convergence.rs` (add field + update Default; add test) + +- [ ] **Step 1: Write the failing test** + +In `src/convergence.rs`, add a `#[cfg(test)] mod tests` block at the end of the file (the file currently has none): + +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn default_alpha_is_one_for_undamped_behavior() { + let opts = ConvergenceOptions::default(); + assert_eq!(opts.alpha, 1.0); + } +} +``` + +- [ ] **Step 2: Run the test to verify it fails** + +Run: `cargo test --lib convergence::tests::default_alpha_is_one` + +Expected: compile error "no field `alpha` on type `ConvergenceOptions`". + +- [ ] **Step 3: Add the field** + +In `src/convergence.rs`, modify the existing `ConvergenceOptions` struct and its `Default` impl: + +```rust +#[derive(Clone, Copy, Debug)] +pub struct ConvergenceOptions { + pub max_iter: usize, + pub epsilon: f64, + /// EP damping factor in natural-parameter space: each per-factor + /// update writes `α·new + (1−α)·old`. `1.0` is undamped (default); + /// `< 1.0` stabilises oscillating fixed-point loops at the cost of + /// more iterations. Must be in `(0.0, 1.0]`. + pub alpha: f64, +} + +impl Default for ConvergenceOptions { + fn default() -> Self { + Self { + max_iter: crate::ITERATIONS, + epsilon: crate::EPSILON, + alpha: 1.0, + } + } +} +``` + +- [ ] **Step 4: Run the test to verify it passes** + +Run: `cargo test --lib convergence::tests::default_alpha_is_one` + +Expected: 1 passed. + +- [ ] **Step 5: Confirm full suite still compiles** + +Run: `cargo test --lib` + +Expected: all passing. The new field has a `Default` value so existing `..Default::default()` constructions in tests continue to work without modification. + +- [ ] **Step 6: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --lib -- -D warnings` + +Expected: no diff, no warnings. + +- [ ] **Step 7: Commit** + +```bash +git add src/convergence.rs +git commit -m "$(cat <<'EOF' +feat(convergence): add ConvergenceOptions::alpha damping field + +Adds an EP damping coefficient defaulting to 1.0 (undamped). Will be +read by run_chain in a follow-up commit. By itself this commit changes +no behavior — existing constructors using ..Default::default() pick up +the new field automatically. +EOF +)" +``` + +--- + +### Task 3: `TruncFactor::propagate_with_alpha` + +**Files:** +- Modify: `src/factor/trunc.rs` (add inherent method; trait impl delegates) + +The current `TruncFactor::propagate` body computes `cavity`, `trunc`, `new_msg`, then writes `vars.set(diff, trunc)`. The damped version writes `vars.set(diff, cavity * damped)` — which equals `trunc` when `alpha = 1.0` (since `cavity * new_msg = trunc` by construction) but reflects partial-update math otherwise. + +- [ ] **Step 1: Write the failing test** + +In `src/factor/trunc.rs`, inside the existing `#[cfg(test)] mod tests` block, add: + +```rust +#[test] +fn propagate_with_alpha_one_matches_undamped_propagate() { + let mut vars_a = VarStore::new(); + let diff_a = vars_a.alloc(Gaussian::from_ms(2.0, 3.0)); + let mut f_a = TruncFactor::new(diff_a, 0.0, false); + let delta_a = f_a.propagate(&mut vars_a); + let result_a = vars_a.get(diff_a); + + let mut vars_b = VarStore::new(); + let diff_b = vars_b.alloc(Gaussian::from_ms(2.0, 3.0)); + let mut f_b = TruncFactor::new(diff_b, 0.0, false); + let delta_b = f_b.propagate_with_alpha(&mut vars_b, 1.0); + let result_b = vars_b.get(diff_b); + + assert_eq!(result_a.pi(), result_b.pi()); + assert_eq!(result_a.tau(), result_b.tau()); + assert_eq!(delta_a, delta_b); + assert_eq!(f_a.msg.pi(), f_b.msg.pi()); + assert_eq!(f_a.msg.tau(), f_b.msg.tau()); +} + +#[test] +fn propagate_with_alpha_half_blends_msg_in_natural_params() { + // Run undamped to capture (initial_msg, undamped_new_msg). + let mut vars_full = VarStore::new(); + let diff_full = vars_full.alloc(Gaussian::from_ms(2.0, 3.0)); + let mut f_full = TruncFactor::new(diff_full, 0.0, false); + let initial_msg_pi = f_full.msg.pi(); + let initial_msg_tau = f_full.msg.tau(); + f_full.propagate(&mut vars_full); + let undamped_msg_pi = f_full.msg.pi(); + let undamped_msg_tau = f_full.msg.tau(); + + // Run damped at α = 0.5 from the same initial state. + let mut vars_half = VarStore::new(); + let diff_half = vars_half.alloc(Gaussian::from_ms(2.0, 3.0)); + let mut f_half = TruncFactor::new(diff_half, 0.0, false); + f_half.propagate_with_alpha(&mut vars_half, 0.5); + + let expected_pi = 0.5 * undamped_msg_pi + 0.5 * initial_msg_pi; + let expected_tau = 0.5 * undamped_msg_tau + 0.5 * initial_msg_tau; + assert!((f_half.msg.pi() - expected_pi).abs() < 1e-12); + assert!((f_half.msg.tau() - expected_tau).abs() < 1e-12); +} +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `cargo test --lib factor::trunc::tests::propagate_with_alpha` + +Expected: 2 errors, "no method named `propagate_with_alpha` found". + +- [ ] **Step 3: Implement `propagate_with_alpha` and rewire trait impl** + +In `src/factor/trunc.rs`, replace the existing `impl Factor for TruncFactor { ... }` block (currently lines 36-64 — the entire `impl Factor` block) with: + +```rust +impl TruncFactor { + /// Propagate this factor's message, optionally damping the update in + /// natural-parameter space. `alpha = 1.0` matches `Factor::propagate` + /// exactly; `alpha < 1.0` writes `α·new_msg + (1−α)·old_msg`. + pub(crate) fn propagate_with_alpha( + &mut self, + vars: &mut VarStore, + alpha: f64, + ) -> (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.margin, self.tie)); + } + + let trunc = approx(cavity, self.margin, self.tie); + let new_msg = trunc / cavity; + + let damped = self.msg.damp_natural(new_msg, alpha); + let old_msg = self.msg; + self.msg = damped; + + // marginal_new = cavity * stored_msg. With alpha = 1.0 this equals + // `trunc` (since cavity * new_msg = trunc by construction); with + // alpha < 1.0 it reflects the partially-applied update. + vars.set(self.diff, cavity * damped); + + old_msg.delta(damped) + } +} + +impl Factor for TruncFactor { + fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64) { + self.propagate_with_alpha(vars, 1.0) + } + + fn log_evidence(&self, _vars: &VarStore) -> f64 { + self.evidence_cached.unwrap_or(1.0).ln() + } +} +``` + +- [ ] **Step 4: Run the new tests** + +Run: `cargo test --lib factor::trunc::tests::propagate_with_alpha` + +Expected: 2 passed. + +- [ ] **Step 5: Run the full library test suite** + +Run: `cargo test --lib` + +Expected: all passing. Critically, the existing `idempotent_after_convergence`, `evidence_cached_on_first_propagate`, and `tie_evidence_uses_two_sided` tests in `src/factor/trunc.rs` must still pass — they exercise the trait `propagate` which now goes through `propagate_with_alpha(_, 1.0)`. Bit-equal because `cavity * new_msg = trunc` by construction. + +- [ ] **Step 6: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --lib -- -D warnings` + +- [ ] **Step 7: Commit** + +```bash +git add src/factor/trunc.rs +git commit -m "$(cat <<'EOF' +feat(factor): add TruncFactor::propagate_with_alpha for EP damping + +Inherent method that applies α-damping to the outgoing message via +Gaussian::damp_natural. The Factor trait impl delegates with α=1.0, +preserving today's behavior bit-equal. Variable write switched from +`trunc` to `cavity * damped` — algebraically identical when α=1.0 +(cavity * new_msg = trunc by construction); reflects partial-update +math when α<1.0. +EOF +)" +``` + +--- + +### Task 4: `MarginFactor::propagate_with_alpha` + +**Files:** +- Modify: `src/factor/margin.rs` (mirror Task 3's shape) + +- [ ] **Step 1: Write the failing test** + +In `src/factor/margin.rs`, inside the existing `#[cfg(test)] mod tests` block, add: + +```rust +#[test] +fn propagate_with_alpha_one_matches_undamped_propagate() { + let mut vars_a = VarStore::new(); + let diff_a = vars_a.alloc(Gaussian::from_ms(0.0, 6.0)); + let mut f_a = MarginFactor::new(diff_a, 5.0, 1.0); + let delta_a = f_a.propagate(&mut vars_a); + let result_a = vars_a.get(diff_a); + + let mut vars_b = VarStore::new(); + let diff_b = vars_b.alloc(Gaussian::from_ms(0.0, 6.0)); + let mut f_b = MarginFactor::new(diff_b, 5.0, 1.0); + let delta_b = f_b.propagate_with_alpha(&mut vars_b, 1.0); + let result_b = vars_b.get(diff_b); + + assert_eq!(result_a.pi(), result_b.pi()); + assert_eq!(result_a.tau(), result_b.tau()); + assert_eq!(delta_a, delta_b); + assert_eq!(f_a.msg.pi(), f_b.msg.pi()); + assert_eq!(f_a.msg.tau(), f_b.msg.tau()); +} + +#[test] +fn propagate_with_alpha_half_blends_msg_in_natural_params() { + // Run undamped to capture (initial_msg, undamped_new_msg). + let mut vars_full = VarStore::new(); + let diff_full = vars_full.alloc(Gaussian::from_ms(0.0, 6.0)); + let mut f_full = MarginFactor::new(diff_full, 5.0, 1.0); + let initial_msg_pi = f_full.msg.pi(); + let initial_msg_tau = f_full.msg.tau(); + f_full.propagate(&mut vars_full); + let undamped_msg_pi = f_full.msg.pi(); + let undamped_msg_tau = f_full.msg.tau(); + + // Run damped at α = 0.5 from the same initial state. + let mut vars_half = VarStore::new(); + let diff_half = vars_half.alloc(Gaussian::from_ms(0.0, 6.0)); + let mut f_half = MarginFactor::new(diff_half, 5.0, 1.0); + f_half.propagate_with_alpha(&mut vars_half, 0.5); + + let expected_pi = 0.5 * undamped_msg_pi + 0.5 * initial_msg_pi; + let expected_tau = 0.5 * undamped_msg_tau + 0.5 * initial_msg_tau; + assert!((f_half.msg.pi() - expected_pi).abs() < 1e-12); + assert!((f_half.msg.tau() - expected_tau).abs() < 1e-12); +} +``` + +- [ ] **Step 2: Run the tests to verify they fail** + +Run: `cargo test --lib factor::margin::tests::propagate_with_alpha` + +Expected: 2 errors, "no method named `propagate_with_alpha` found". + +- [ ] **Step 3: Implement and rewire** + +In `src/factor/margin.rs`, replace the existing `impl Factor for MarginFactor { ... }` block (currently lines 35-56) with: + +```rust +impl MarginFactor { + /// Propagate this factor's message, optionally damping the update in + /// natural-parameter space. `alpha = 1.0` matches `Factor::propagate` + /// exactly; `alpha < 1.0` writes `α·new_msg + (1−α)·old_msg`. + pub(crate) fn propagate_with_alpha( + &mut self, + vars: &mut VarStore, + alpha: f64, + ) -> (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 damped = self.msg.damp_natural(new_msg, alpha); + let old_msg = self.msg; + self.msg = damped; + vars.set(self.diff, cavity * damped); + + old_msg.delta(damped) + } +} + +impl Factor for MarginFactor { + fn propagate(&mut self, vars: &mut VarStore) -> (f64, f64) { + self.propagate_with_alpha(vars, 1.0) + } + + fn log_evidence(&self, _vars: &VarStore) -> f64 { + self.evidence_cached.unwrap_or(1.0).ln() + } +} +``` + +- [ ] **Step 4: Run the new tests** + +Run: `cargo test --lib factor::margin::tests::propagate_with_alpha` + +Expected: 2 passed. + +- [ ] **Step 5: Run the full library test suite** + +Run: `cargo test --lib` + +Expected: all passing. The existing `first_propagate_writes_tilted_marginal`, `converges_in_one_step`, `evidence_cached_on_first_propagate`, `log_evidence_matches_cached_ln` tests must still pass (they go through the trait `propagate`, which now calls `propagate_with_alpha(_, 1.0)`; bit-equal because the marginal write reduces to the original `cavity * new_msg` form when α=1.0). + +- [ ] **Step 6: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --lib -- -D warnings` + +- [ ] **Step 7: Commit** + +```bash +git add src/factor/margin.rs +git commit -m "$(cat <<'EOF' +feat(factor): add MarginFactor::propagate_with_alpha for EP damping + +Mirrors TruncFactor: inherent damped-propagate method, trait impl +delegates with α=1.0. Existing goldens unchanged because cavity*new_msg +equals the previous marginal write when α=1.0. +EOF +)" +``` + +--- + +### Task 5: Plumb `ConvergenceOptions` through `Game` to `run_chain` and add `alpha` to `DiffFactor::propagate` + +This is the integration task. It does five things, all required atomically for the suite to compile: + +1. Add `convergence: ConvergenceOptions` field to both `OwnedGame` and `Game<'a, T, D>`. +2. Extend `OwnedGame::new` and `OwnedGame::new_scored` to accept `convergence: ConvergenceOptions`. Update `Game::ranked` and `Game::scored` to forward `options.convergence`. +3. Extend `Game::ranked_with_arena` and `Game::scored_with_arena` to accept `convergence: ConvergenceOptions`. Store on `self`. +4. Change `DiffFactor::propagate` signature to `propagate(&mut self, vars: &mut VarStore, alpha: f64)`. Dispatch into `propagate_with_alpha`. +5. Replace `run_chain`'s hardcoded `1e-6` / `10` / undamped with `self.convergence.{epsilon, max_iter, alpha}`. Pass alpha to all three `lf.propagate` callsites. Add `debug_assert!` for alpha range. + +There are ~20 test callsites to update. Most pass `&mut ScratchArena::new()` as the last argument; the new convergence parameter slots in just before that. + +**Files:** +- Modify: `src/game.rs` (struct fields, two constructors, two `_with_arena` entry points, `DiffFactor::propagate`, `run_chain`, ~20 test callsites) + +- [ ] **Step 1: Add the `convergence` field to `OwnedGame` and `Game`** + +In `src/game.rs`, modify the `OwnedGame` struct (currently `src/game.rs:83-92`) to add the field. The struct should become: + +```rust +#[derive(Debug)] +#[allow(dead_code)] +pub struct OwnedGame> { + teams: Vec>>, + result: Vec, + weights: Vec>, + p_draw: f64, + pub(crate) convergence: crate::ConvergenceOptions, + pub(crate) likelihoods: Vec>, + pub(crate) evidence: f64, +} +``` + +In the same file, modify the `Game<'a, T, D>` struct (currently `src/game.rs:148-156`) to add the field: + +```rust +#[derive(Debug)] +pub struct Game<'a, T: Time = i64, D: Drift = crate::drift::ConstantDrift> { + teams: Vec>>, + result: &'a [f64], + weights: &'a [Vec], + p_draw: f64, + pub(crate) convergence: crate::ConvergenceOptions, + pub(crate) likelihoods: Vec>, + pub(crate) evidence: f64, +} +``` + +(Code won't compile yet — the constructors don't yet supply the field. Fix in Step 2.) + +- [ ] **Step 2: Update `OwnedGame::new` and `OwnedGame::new_scored` to accept and forward convergence** + +Replace the existing `OwnedGame::new` (currently `src/game.rs:95-113`) with: + +```rust +pub(crate) fn new( + teams: Vec>>, + result: Vec, + weights: Vec>, + p_draw: f64, + convergence: crate::ConvergenceOptions, +) -> Self { + let mut arena = ScratchArena::new(); + let g = Game::ranked_with_arena( + teams.clone(), + &result, + &weights, + p_draw, + convergence, + &mut arena, + ); + let likelihoods = g.likelihoods; + let evidence = g.evidence; + Self { + teams, + result, + weights, + p_draw, + convergence, + likelihoods, + evidence, + } +} +``` + +Replace `OwnedGame::new_scored` (currently `src/game.rs:115-133`) with: + +```rust +pub(crate) fn new_scored( + teams: Vec>>, + scores: Vec, + weights: Vec>, + score_sigma: f64, + convergence: crate::ConvergenceOptions, +) -> Self { + let mut arena = ScratchArena::new(); + let g = Game::scored_with_arena( + teams.clone(), + &scores, + &weights, + score_sigma, + convergence, + &mut arena, + ); + let likelihoods = g.likelihoods; + let evidence = g.evidence; + Self { + teams, + result: scores, + weights, + p_draw: 0.0, + convergence, + likelihoods, + evidence, + } +} +``` + +- [ ] **Step 3: Update `Game::ranked` and `Game::scored` to forward `options.convergence`** + +In `src/game.rs:402-433`, replace the body's final `Ok(...)` line in `Game::ranked` (currently `Ok(OwnedGame::new(teams_owned, result, weights, options.p_draw))`) with: + +```rust +Ok(OwnedGame::new( + teams_owned, + result, + weights, + options.p_draw, + options.convergence, +)) +``` + +In `src/game.rs:435-469`, replace the final `Ok(OwnedGame::new_scored(...))` in `Game::scored` with: + +```rust +Ok(OwnedGame::new_scored( + teams_owned, + scores, + weights, + options.score_sigma, + options.convergence, +)) +``` + +- [ ] **Step 4: Update `Game::ranked_with_arena` and `Game::scored_with_arena` to accept convergence** + +Replace `Game::ranked_with_arena` (currently `src/game.rs:159-201`) signature and body to add the parameter and store it on `self`: + +```rust +pub(crate) fn ranked_with_arena( + teams: Vec>>, + result: &'a [f64], + weights: &'a [Vec], + p_draw: f64, + convergence: crate::ConvergenceOptions, + arena: &mut ScratchArena, +) -> Self { + debug_assert!( + result.len() == teams.len(), + "result 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!( + (0.0..1.0).contains(&p_draw), + "draw probability must be >= 0.0 and < 1.0" + ); + debug_assert!( + p_draw > 0.0 || { + let mut r = result.to_vec(); + r.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap()); + r.windows(2).all(|w| w[0] != w[1]) + }, + "draw must be > 0.0 if there are teams with draw" + ); + debug_assert!( + convergence.alpha > 0.0 && convergence.alpha <= 1.0, + "convergence alpha must be in (0.0, 1.0]" + ); + + let mut this = Self { + teams, + result, + weights, + p_draw, + convergence, + likelihoods: Vec::new(), + evidence: 0.0, + }; + + this.likelihoods(arena); + this +} +``` + +Replace `Game::scored_with_arena` (currently `src/game.rs:203-234`) similarly: + +```rust +pub(crate) fn scored_with_arena( + teams: Vec>>, + scores: &'a [f64], + weights: &'a [Vec], + score_sigma: f64, + convergence: crate::ConvergenceOptions, + 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"); + debug_assert!( + convergence.alpha > 0.0 && convergence.alpha <= 1.0, + "convergence alpha must be in (0.0, 1.0]" + ); + + let mut this = Self { + teams, + result: scores, + weights, + p_draw: 0.0, + convergence, + likelihoods: Vec::new(), + evidence: 0.0, + }; + + this.likelihoods_scored(arena, score_sigma); + this +} +``` + +- [ ] **Step 5: Change `DiffFactor::propagate` signature to take `alpha`** + +In `src/game.rs`, replace the existing `impl DiffFactor` block (currently `src/game.rs:25-54`) with: + +```rust +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, + alpha: f64, + ) -> (f64, f64) { + match self { + Self::Trunc(f) => f.propagate_with_alpha(vars, alpha), + Self::Margin(f) => f.propagate_with_alpha(vars, alpha), + } + } +} +``` + +(Note the `use crate::factor::Factor;` line in the old impl is no longer needed — it was there to bring the trait method into scope. The new code calls the inherent `propagate_with_alpha` directly. Remove the import if it's now unused.) + +- [ ] **Step 6: Update `run_chain` to read `self.convergence` and pass `alpha` to propagate** + +In `src/game.rs`, modify `run_chain` (currently starts at `src/game.rs:236`). Three site changes: + +(a) At the top of `run_chain`'s body (immediately after `arena.reset();`), add: + +```rust +let alpha = self.convergence.alpha; +let epsilon = self.convergence.epsilon; +let max_iter = self.convergence.max_iter; +``` + +(b) Replace the loop guard `while tuple_gt(step, 1e-6) && iter < 10 {` with: + +```rust +while tuple_gt(step, epsilon) && iter < max_iter { +``` + +(c) Replace each of the three `lf.propagate(&mut arena.vars)` callsites: + +- In the forward sweep: `let d = lf.propagate(&mut arena.vars, alpha);` +- In the backward sweep: `let d = lf.propagate(&mut arena.vars, alpha);` +- In the `n_diffs == 1` special case: `links[0].propagate(&mut arena.vars, alpha);` + +- [ ] **Step 7: Update all test callsites of `ranked_with_arena` and `scored_with_arena`** + +Run `cargo build` to surface compile errors. Each error will be at a callsite of `Game::ranked_with_arena(...)` or `Game::scored_with_arena(...)` missing the new `convergence` parameter. The fix at every site: add `crate::ConvergenceOptions::default(),` as the second-to-last argument (immediately before `&mut ScratchArena::new()` or `&mut arena`). + +Example transformation. Before: + +```rust +let g = Game::ranked_with_arena( + teams, + &result, + &weights, + p_draw, + &mut arena, +); +``` + +After: + +```rust +let g = Game::ranked_with_arena( + teams, + &result, + &weights, + p_draw, + crate::ConvergenceOptions::default(), + &mut arena, +); +``` + +Apply the same transformation to all 16+ `ranked_with_arena` callsites and the 2 `scored_with_arena` callsites in `src/game.rs`. They are all in `#[cfg(test)] mod` sections at the bottom of the file. After every callsite is updated, `cargo build` must succeed. + +If a test uses inline `&mut ScratchArena::new()` rather than a `let mut arena = ...` binding, the same insertion applies — `crate::ConvergenceOptions::default(),` slots in immediately before the arena argument. + +- [ ] **Step 8: Run the full test suite — bit-equal regression net** + +Run: `cargo test --lib` + +Expected: every existing test passes unchanged. Total count = previous baseline + 0 (no new tests added in this task). If ANY existing assertion fails, the integration leaked damping into the undamped (α=1.0) trajectory — debug before proceeding. + +- [ ] **Step 9: Run integration tests too** + +Run: `cargo test` + +Expected: all integration tests pass. + +- [ ] **Step 10: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --all-targets -- -D warnings` + +Expected: no diff, no warnings. + +- [ ] **Step 11: Commit** + +```bash +git add src/game.rs +git commit -m "$(cat <<'EOF' +feat(game): plumb ConvergenceOptions through to run_chain + +Game and OwnedGame gain a convergence: ConvergenceOptions field set at +construction. Game::{ranked,scored} forward options.convergence into +OwnedGame::{new,new_scored} (previously dropped on the floor). +{ranked,scored}_with_arena take it as a parameter. run_chain reads +self.convergence.{epsilon, max_iter, alpha} instead of hardcoded +1e-6 / 10 / undamped. DiffFactor::propagate gains an alpha parameter +and dispatches into Trunc/MarginFactor::propagate_with_alpha. + +Existing test callsites updated to pass ConvergenceOptions::default(). +Default alpha is 1.0, so all 88 lib + 27 integration test goldens +remain bit-equal. +EOF +)" +``` + +--- + +### Task 6: End-to-end integration tests for `alpha` and `max_iter` + +**Files:** +- Modify: `src/game.rs` (add tests at the end of an existing `#[cfg(test)] mod tests` block, OR a new `mod convergence_options_tests` block at the very end of the file — pick whichever existing block currently holds the most-recent game-level tests) + +This task adds the integration coverage that proves `run_chain` actually reads `ConvergenceOptions`. Two assertions: + +1. `max_iter = 1` on a graph that needs more iterations produces a measurably different posterior than `max_iter = 30`. +2. `alpha = 0.5` on the same graph reaches the same converged posterior as `alpha = 1.0` (just slower) — proves damping doesn't break correctness on convergent graphs. + +- [ ] **Step 1: Write the failing tests** + +Add to the existing `#[cfg(test)] mod tests` block in `src/game.rs` (the one near the bottom containing the other game-level tests): + +```rust +#[test] +fn run_chain_honours_max_iter_in_convergence_options() { + use crate::{ConvergenceOptions, drift::ConstantDrift, rating::Rating}; + + let players: Vec> = (0..4) + .map(|_| Rating::default()) + .collect(); + let teams: Vec> = players.iter().map(|p| vec![*p]).collect(); + let result = vec![3.0, 2.0, 1.0, 0.0]; + let weights = vec![vec![1.0]; 4]; + + // Capped at 1 iteration: cannot fully propagate down a 4-team chain. + let mut arena = ScratchArena::new(); + let g_capped = Game::ranked_with_arena( + teams.clone(), + &result, + &weights, + 0.0, + ConvergenceOptions { + max_iter: 1, + ..ConvergenceOptions::default() + }, + &mut arena, + ); + let posteriors_capped = g_capped.posteriors(); + + // Same inputs, plenty of iterations: fully converged. + let mut arena = ScratchArena::new(); + let g_full = Game::ranked_with_arena( + teams, + &result, + &weights, + 0.0, + ConvergenceOptions::default(), + &mut arena, + ); + let posteriors_full = g_full.posteriors(); + + // The two posteriors should differ — capped did not converge. + let mut max_diff: f64 = 0.0; + for (team_capped, team_full) in posteriors_capped.iter().zip(posteriors_full.iter()) { + for (g_capped, g_full) in team_capped.iter().zip(team_full.iter()) { + max_diff = max_diff.max((g_capped.mu() - g_full.mu()).abs()); + max_diff = max_diff.max((g_capped.sigma() - g_full.sigma()).abs()); + } + } + assert!( + max_diff > 1e-6, + "max_iter=1 should differ from full convergence; max_diff={max_diff}" + ); +} + +#[test] +fn run_chain_with_damping_converges_to_same_posterior() { + use crate::{ConvergenceOptions, drift::ConstantDrift, rating::Rating}; + + let players: Vec> = (0..4) + .map(|_| Rating::default()) + .collect(); + let teams: Vec> = players.iter().map(|p| vec![*p]).collect(); + let result = vec![3.0, 2.0, 1.0, 0.0]; + let weights = vec![vec![1.0]; 4]; + + let mut arena = ScratchArena::new(); + let g_undamped = Game::ranked_with_arena( + teams.clone(), + &result, + &weights, + 0.0, + ConvergenceOptions::default(), + &mut arena, + ); + let posteriors_undamped = g_undamped.posteriors(); + + // alpha=0.5 with extra iterations: should reach the same fixed point. + let mut arena = ScratchArena::new(); + let g_damped = Game::ranked_with_arena( + teams, + &result, + &weights, + 0.0, + ConvergenceOptions { + alpha: 0.5, + max_iter: 100, + ..ConvergenceOptions::default() + }, + &mut arena, + ); + let posteriors_damped = g_damped.posteriors(); + + let mut max_diff: f64 = 0.0; + for (team_u, team_d) in posteriors_undamped.iter().zip(posteriors_damped.iter()) { + for (g_u, g_d) in team_u.iter().zip(team_d.iter()) { + max_diff = max_diff.max((g_u.mu() - g_d.mu()).abs()); + max_diff = max_diff.max((g_u.sigma() - g_d.sigma()).abs()); + } + } + assert!( + max_diff < 1e-4, + "α=0.5 should reach the same fixed point as α=1.0; max_diff={max_diff}" + ); +} +``` + +- [ ] **Step 2: Run the new tests to verify they pass** + +Run: `cargo test --lib run_chain_honours_max_iter_in_convergence_options run_chain_with_damping_converges_to_same_posterior` + +Expected: 2 passed. + +If the `max_iter=1` test fails because the 4-team chain happens to converge in 1 iteration with default starting state, replace `max_iter: 1` with `max_iter: 0` and adjust the test name accordingly — `max_iter=0` will skip the loop entirely and return uniform-prior likelihoods that obviously differ from converged. + +If the `alpha=0.5` convergence test fails (max_diff is too large), increase `max_iter: 100` to `max_iter: 200` — heavier damping needs more iterations. + +- [ ] **Step 3: Run the full library test suite** + +Run: `cargo test --lib` + +Expected: all passing, count = previous baseline + 2. + +- [ ] **Step 4: Run integration tests** + +Run: `cargo test` + +Expected: all passing. + +- [ ] **Step 5: Format and lint** + +Run: `cargo +nightly fmt && cargo clippy --all-targets -- -D warnings` + +Expected: no diff, no warnings. + +- [ ] **Step 6: Commit** + +```bash +git add src/game.rs +git commit -m "$(cat <<'EOF' +test(game): integration tests for ConvergenceOptions behavior + +Two end-to-end tests on a 4-team ranked game: +- max_iter=1 produces measurably different posteriors than the default, + proving run_chain reads convergence.max_iter +- alpha=0.5 with extra iterations reaches the same fixed point as + alpha=1.0, proving damping doesn't break convergence on benign graphs +EOF +)" +``` + +--- + +## Self-review (writer's note) + +**Spec coverage:** +- Spec § "What ships" item 1 (`alpha` field) → Task 2 ✓ +- Spec § "What ships" item 2 (`run_chain` reads ConvergenceOptions) → Task 5 (steps 6, 7) ✓ +- Spec § "What ships" item 3 (`Gaussian::damp_natural`) → Task 1 ✓ +- Spec § "What ships" item 4 (`TruncFactor::propagate_with_alpha` + delegate) → Task 3 ✓ +- Spec § "What ships" item 4 (`MarginFactor::propagate_with_alpha` + delegate) → Task 4 ✓ +- Spec § "What ships" item 5 (`DiffFactor::propagate` gains `alpha`) → Task 5 step 5 ✓ +- Spec § "Convergence semantics" (delta of damped msg, not raw) → enforced in Task 3 step 3 and Task 4 step 3 (`old_msg.delta(damped)`) +- Spec § "Testing strategy" §1 (regression net) → Task 5 step 8, Task 6 step 3 +- Spec § "Testing strategy" §2 (damp_natural) → Task 1 ✓ +- Spec § "Testing strategy" §3 (TruncFactor damping shrinks step) → Task 3 ✓ +- Spec § "Testing strategy" §4 (MarginFactor parity) → Task 4 ✓ +- Spec § "Testing strategy" §5 (run_chain honours max_iter) → Task 6 ✓ +- Spec § "Testing strategy" §6 (default alpha = 1.0) → Task 2 ✓ + +**Out-of-scope items correctly absent:** No Schedule trait integration, no nat-param convergence switch, no oscillation auto-detect, no Residual / OneShot / SynergyFactor / ScoreFactor work. + +**Type / signature consistency:** +- `Gaussian::damp_natural(self, new: Gaussian, alpha: f64) -> Gaussian` — same signature in Task 1 (definition) and Tasks 3/4 (call sites) ✓ +- `propagate_with_alpha(&mut self, vars: &mut VarStore, alpha: f64) -> (f64, f64)` — consistent in Tasks 3 and 4 ✓ +- `DiffFactor::propagate(&mut self, vars: &mut crate::factor::VarStore, alpha: f64) -> (f64, f64)` — Task 5 step 5; matches `lf.propagate(&mut arena.vars, alpha)` in step 6 ✓ +- `OwnedGame::new(..., convergence: ConvergenceOptions)` — Task 5 step 2; matches `Game::ranked` forwarding `options.convergence` in step 3 ✓ +- `ranked_with_arena(..., convergence: crate::ConvergenceOptions, arena: &mut ScratchArena)` — Task 5 step 4; matches the expected callsite shape in step 7 ✓ + +**No placeholders detected.** + +**Note on Task 5 size:** This task is unusually large (11 steps) because the field addition, struct/constructor changes, signature changes, and test callsite updates must land atomically — splitting them produces non-compiling intermediate states. The 11 steps are organised so the final `cargo build` only succeeds after Step 7 completes.