fix(arena): thread competition RNG through sim builder and RandomAgent (#266)

Two holes made "seeded competition" runs non-deterministic:

1. `StandardSimulationIterator::next()` built each simulation via
   `HoldemSimulationBuilder::build()`, which called `rand::rng()`
   unconditionally to draw the simulation ID. Two runs with the same
   competition seed produced different IDs, which flow into hand
   histories and CFR node keys.

2. `RandomAgentGenerator::generate()` constructed each `RandomAgent`
   via `RandomAgent::new`, which seeds from OS entropy. Any game
   involving a `RandomAgent` pulled fresh randomness per hand.

Add a `with_rng` constructor to `StandardSimulationIterator` that stores
a `StdRng` and feeds it into `build_with_rng`. Add a `seeded(seed)`
constructor to `RandomAgentGenerator` that derives a per-player seed
(`seed + player_idx`) for each generated agent, so repeated runs produce
identical action streams. Cover both with regression tests.

Author: elliottneilclark

src/arena/agent/random.rs

@@ -141,6 +141,11 @@ pub struct RandomAgentGenerator {
     name: Option<String>,
     percent_fold: Vec<f64>,
     percent_call: Vec<f64>,
+    /// Optional base seed. When set, each generated `RandomAgent` is
+    /// seeded from `base.wrapping_add(player_idx as u64)` so that
+    /// repeated runs of the same competition produce bit-identical
+    /// decisions. When `None` the agents draw fresh OS entropy.
+    seed: Option<u64>,
 }
 
 impl RandomAgentGenerator {
@@ -149,6 +154,19 @@ impl RandomAgentGenerator {
             name: None,
             percent_fold,
             percent_call,
+            seed: None,
+        }
+    }
+
+    /// Create a generator whose produced agents are seeded from a
+    /// deterministic base. Each player's `RandomAgent` is seeded from
+    /// `seed.wrapping_add(player_idx as u64)`.
+    pub fn seeded(percent_fold: Vec<f64>, percent_call: Vec<f64>, seed: u64) -> Self {
+        Self {
+            name: None,
+            percent_fold,
+            percent_call,
+            seed: Some(seed),
         }
     }
 
@@ -157,6 +175,12 @@ impl RandomAgentGenerator {
         self
     }
 
+    /// Set (or clear) the seed used to construct generated agents.
+    pub fn with_seed(mut self, seed: Option<u64>) -> Self {
+        self.seed = seed;
+        self
+    }
+
     fn resolve_name(&self, player_idx: usize) -> String {
         self.name
             .clone()
@@ -166,11 +190,20 @@ impl RandomAgentGenerator {
 
 impl AgentGenerator for RandomAgentGenerator {
     fn generate(&self, player_idx: usize, _game_state: &GameState) -> Box<dyn Agent> {
-        Box::new(RandomAgent::new(
-            self.resolve_name(player_idx),
-            self.percent_fold.clone(),
-            self.percent_call.clone(),
-        ))
+        let name = self.resolve_name(player_idx);
+        match self.seed {
+            Some(base) => Box::new(RandomAgent::new_with_seed(
+                name,
+                self.percent_fold.clone(),
+                self.percent_call.clone(),
+                base.wrapping_add(player_idx as u64),
+            )),
+            None => Box::new(RandomAgent::new(
+                name,
+                self.percent_fold.clone(),
+                self.percent_call.clone(),
+            )),
+        }
     }
 }
 
@@ -387,6 +420,51 @@ mod tests {
         }
     }
 
+    /// Regression test for M2: `RandomAgentGenerator::seeded` must
+    /// produce deterministic agents — two generators built with the
+    /// same seed must generate agents whose action streams are
+    /// identical across runs.
+    #[test]
+    fn test_seeded_random_agent_generator_is_deterministic() {
+        let game_state = GameStateBuilder::new()
+            .num_players_with_stack(2, 500.0)
+            .blinds(10.0, 5.0)
+            .build()
+            .unwrap();
+
+        let collect_actions = || {
+            let generator =
+                RandomAgentGenerator::seeded(vec![0.1, 0.2], vec![0.4, 0.3], 0xdeadbeef);
+            let mut agent = generator.generate(1, &game_state);
+            let mut actions = Vec::new();
+            for i in 0..64u128 {
+                actions.push(agent.act(i, &game_state));
+            }
+            actions
+        };
+
+        let run_a = collect_actions();
+        let run_b = collect_actions();
+        assert_eq!(run_a, run_b);
+    }
+
+    /// Different player indices must still produce independent streams
+    /// even when seeded from the same base.
+    #[test]
+    fn test_seeded_random_agent_generator_differs_across_players() {
+        let game_state = GameStateBuilder::new()
+            .num_players_with_stack(2, 500.0)
+            .blinds(10.0, 5.0)
+            .build()
+            .unwrap();
+        let generator = RandomAgentGenerator::seeded(vec![0.1, 0.2], vec![0.4, 0.3], 0xdeadbeef);
+        let mut p0 = generator.generate(0, &game_state);
+        let mut p1 = generator.generate(1, &game_state);
+        let actions0: Vec<_> = (0..32u128).map(|i| p0.act(i, &game_state)).collect();
+        let actions1: Vec<_> = (0..32u128).map(|i| p1.act(i, &game_state)).collect();
+        assert_ne!(actions0, actions1);
+    }
+
     #[test]
     fn test_random_generator_uses_custom_name() {
         let generator = RandomAgentGenerator::new(vec![0.0], vec![1.0]).with_name("RandomHero");

src/arena/competition/sim_iterator.rs

@@ -1,30 +1,64 @@
+use rand::{SeedableRng, rng as os_rng, rngs::StdRng};
+
 use crate::arena::{
     AgentGenerator, GameState, HoldemSimulation, HoldemSimulationBuilder,
     historian::HistorianGenerator,
 };
 
+/// Iterator that materialises one [`HoldemSimulation`] per item pulled from
+/// the underlying game-state iterator.
+///
+/// The iterator owns an RNG used exclusively to generate per-simulation
+/// IDs (see [`HoldemSimulationBuilder::build_with_rng`]). By default the
+/// RNG is seeded from OS entropy, so repeated runs produce distinct IDs.
+/// For deterministic runs (e.g., reproducing a seeded competition), build
+/// with [`StandardSimulationIterator::with_rng`] and pass an RNG forked
+/// from the competition's own RNG.
 pub struct StandardSimulationIterator<G>
 where
     G: Iterator<Item = GameState>,
 {
     agent_generators: Vec<Box<dyn AgentGenerator>>,
     historian_generators: Vec<Box<dyn HistorianGenerator>>,
     game_state_iterator: G,
+    rng: StdRng,
 }
 
 impl<G> StandardSimulationIterator<G>
 where
     G: Iterator<Item = GameState>,
 {
+    /// Create a new iterator seeded from OS entropy.
+    ///
+    /// Equivalent to [`Self::with_rng`] seeded from `rand::rng()`.
     pub fn new(
         agent_generators: Vec<Box<dyn AgentGenerator>>,
         historian_generators: Vec<Box<dyn HistorianGenerator>>,
         game_state_iterator: G,
+    ) -> StandardSimulationIterator<G> {
+        Self::with_rng(
+            agent_generators,
+            historian_generators,
+            game_state_iterator,
+            StdRng::from_rng(&mut os_rng()),
+        )
+    }
+
+    /// Create a new iterator that draws simulation IDs from the provided
+    /// RNG. Use this when you need repeated runs of the same competition
+    /// to produce identical simulation IDs (and therefore identical hand
+    /// histories and CFR keys).
+    pub fn with_rng(
+        agent_generators: Vec<Box<dyn AgentGenerator>>,
+        historian_generators: Vec<Box<dyn HistorianGenerator>>,
+        game_state_iterator: G,
+        rng: StdRng,
     ) -> StandardSimulationIterator<G> {
         StandardSimulationIterator {
             agent_generators,
             historian_generators,
             game_state_iterator,
+            rng,
         }
     }
 }
@@ -50,7 +84,7 @@ where
             .agents(agents)
             .historians(historians)
             .game_state(game_state)
-            .build()
+            .build_with_rng(&mut self.rng)
             .ok()
     }
 }
@@ -100,4 +134,37 @@ mod tests {
             .next()
             .expect("There should always be a first simulation");
     }
+
+    /// Regression test for M2: two iterators seeded from the same RNG
+    /// must produce identical simulation IDs. Previously the builder
+    /// called `rand::rng()` unconditionally, so repeated runs diverged
+    /// even with identical inputs.
+    #[test]
+    fn test_with_rng_is_deterministic() {
+        let build = || {
+            let generators: Vec<Box<dyn AgentGenerator>> = vec![
+                Box::<FoldingAgentGenerator>::default(),
+                Box::<FoldingAgentGenerator>::default(),
+            ];
+            let game_state = GameStateBuilder::new()
+                .stacks(vec![100.0; 2])
+                .blinds(10.0, 5.0)
+                .build()
+                .unwrap();
+            StandardSimulationIterator::with_rng(
+                generators,
+                vec![],
+                CloneGameStateGenerator::new(game_state),
+                StdRng::seed_from_u64(42),
+            )
+        };
+
+        let mut a = build();
+        let mut b = build();
+        for _ in 0..5 {
+            let sa = a.next().unwrap();
+            let sb = b.next().unwrap();
+            assert_eq!(sa.id, sb.id);
+        }
+    }
 }