random: port Alea, one generator per character

pqcli used Python's global Mersenne Twister, seeded once from the clock.
Upstream uses Johannes Baagøe's Alea, with Random(n) = uint32() % n, and
keeps the generator state with each character. The port matches the JS
output bit for bit, including UTF-16 seeding of non-BMP characters.

Each Player now owns an Alea that is pickled with the save, and
Simulation.tick draws from it. Saves without one get a fresh generator.
As upstream does, a new character's game continues from the state the
kept stat roll was made from.

The parity traces are re-recorded, since every random number changes.

tests/game_trace.py

@@ -6,6 +6,7 @@ from pqcli import random
 from pqcli.config import StatType
 from pqcli.game_data import load_game_data
 from pqcli.mechanic import Player, Simulation, Stats, monster_task
+from pqcli.random import Alea
 
 STATS = {
     StatType.strength: 12,
@@ -28,6 +29,7 @@ def run_trace(seed: str, ticks: int = 3000) -> T.List[str]:
         race=data.races[0],
         class_=data.classes[0],
         stats=Stats(dict(STATS)),
+        rng=Alea(seed),
     )
     random.seed(seed)
     simulation = Simulation(player, data)
@@ -40,17 +42,18 @@ def run_trace(seed: str, ticks: int = 3000) -> T.List[str]:
     for _ in range(ticks):
         simulation.tick(100000.0)
 
-    # plot cinematics and quests are rare in a short run, so force them
-    for _ in range(30):
-        simulation.interplot_cinematic()
-        simulation.complete_quest()
-    lines.extend(f"queued: {task.description}" for task in player.queue)
-    player.queue.clear()
+    with random.using(player.rng):
+        # plot cinematics and quests are rare in a short run, so force them
+        for _ in range(30):
+            simulation.interplot_cinematic()
+            simulation.complete_quest()
+        lines.extend(f"queued: {task.description}" for task in player.queue)
+        player.queue.clear()
 
-    # high level monsters are unreachable in a short run
-    for level in range(1, 100):
-        task = monster_task(data, level, player.quest_book.monster)
-        lines.append(f"monster: {task.description} {task.duration}")
+        # high level monsters are unreachable in a short run
+        for level in range(1, 100):
+            task = monster_task(data, level, player.quest_book.monster)
+            lines.append(f"monster: {task.description} {task.duration}")
 
     lines.append(f"level: {player.level}")
     lines.append(f"act: {player.quest_book.act}")

tests/test_mechanic.py

@@ -1,4 +1,5 @@
 import datetime
+import pickle
 import re
 
 import pytest
@@ -11,9 +12,12 @@ from pqcli.mechanic import (
     Player,
     Simulation,
     Stats,
+    StatsBuilder,
+    create_player,
     impressive_guy,
     level_up_time,
 )
+from pqcli.random import Alea
 
 
 def test_level_up_time_matches_upstream() -> None:
@@ -24,6 +28,10 @@ def test_level_up_time_matches_upstream() -> None:
     assert level_up_time(100) == 70460007
 
 
+RACE = load_game_data().races[0]
+CLASS = load_game_data().classes[0]
+
+
 def make_simulation() -> Simulation:
     data = load_game_data()
     player = Player(
@@ -32,6 +40,7 @@ def make_simulation() -> Simulation:
         race=data.races[0],
         class_=data.classes[0],
         stats=Stats({stat: 10 for stat in StatType}),
+        rng=Alea("test"),
     )
     return Simulation(player, data)
 
@@ -181,3 +190,53 @@ def test_prologue_fills_plot_bar() -> None:
     ]
     assert positions[5][0] == "Loading Act I"
     assert positions[6][0] == "Heading to the killing fields"
+
+
+def test_player_rng_survives_save_and_load() -> None:
+    simulation = make_simulation()
+    for _ in range(50):
+        simulation.tick(100000.0)
+    restored = pickle.loads(pickle.dumps(simulation.player))
+    assert restored.rng.state() == simulation.player.rng.state()
+
+
+def test_old_save_without_rng_gets_one() -> None:
+    player = make_simulation().player
+    state = player.__dict__.copy()
+    del state["rng"]
+    restored = Player.__new__(Player)
+    restored.__setstate__(state)
+    assert isinstance(restored.rng, Alea)
+
+
+def test_tick_draws_from_player_rng_only() -> None:
+    random.seed("global")
+    expected = Alea("global").uint32() % 1000
+    simulation = make_simulation()
+    before = simulation.player.rng.state()
+    for _ in range(50):
+        simulation.tick(100000.0)
+    assert simulation.player.rng.state() != before
+    assert random.below(1000) == expected
+
+
+def test_new_game_replays_stat_roll_numbers() -> None:
+    # upstream seeds the game with the state from before the stat roll
+    builder = StatsBuilder(Alea("roll"))
+    builder.roll()
+    stats = builder.roll()
+    player = create_player("New", RACE, CLASS, stats, builder.seed)
+    assert player.rng.state() == builder.history[-1].seed
+    with random.using(player.rng):
+        rerolled = StatsBuilder(player.rng).roll()
+    assert dict(rerolled) == dict(stats)
+
+
+def test_unroll_restores_previous_stats_and_generator() -> None:
+    builder = StatsBuilder(Alea("roll"))
+    first = builder.roll()
+    after_first = builder.history[-1].after
+    builder.roll()
+    assert builder.unroll() is first
+    assert builder.seed == builder.history[-1].seed
+    assert builder._rng.state() == after_first

tests/test_random.py

@@ -0,0 +1,88 @@
+import pickle
+
+import pytest
+
+from pqcli import random
+from pqcli.random import Alea
+
+# First outputs and resulting state of upstream's JS Alea(seed).uint32()
+VECTORS = {
+    "alpha": (
+        [3768637044, 756790225, 3147161637, 1726577786, 279486812],
+        (0.732755669625476, 0.4020002172328532, 0.06507309433072805, 368555),
+    ),
+    "": (
+        [715789690, 2091287642, 486307, 3866591158, 760028033],
+        (
+            0.00011322717182338238,
+            0.9002609080635011,
+            0.17695781611837447,
+            1018452,
+        ),
+    ),
+    "1697543210123": (
+        [3110287155, 2843160345, 1794106530, 2361562046, 1804721005],
+        (
+            0.41772297816351056,
+            0.5498440111987293,
+            0.42019435320980847,
+            1384612,
+        ),
+    ),
+    # Mash hashes UTF-16 code units, so the dragon counts as two
+    "Ünïcødé 🐉": (
+        [4162081648, 198215584, 541466577, 6418444, 2254846220],
+        (
+            0.12607001163996756,
+            0.0014944104477763176,
+            0.5249972967430949,
+            96530,
+        ),
+    ),
+}
+
+
+@pytest.mark.parametrize("seed", VECTORS)
+def test_alea_matches_upstream(seed: str) -> None:
+    first, state = VECTORS[seed]
+    rng = Alea(seed)
+    assert [rng.uint32() for _ in first] == first
+    assert rng.state() == state
+
+
+def test_alea_state_round_trip() -> None:
+    rng = Alea("alpha")
+    rng.uint32()
+    copy = Alea.from_state(rng.state())
+    assert [copy.uint32() for _ in range(100)] == [
+        rng.uint32() for _ in range(100)
+    ]
+
+
+def test_alea_pickles_with_its_state() -> None:
+    rng = Alea("alpha")
+    rng.uint32()
+    copy = pickle.loads(pickle.dumps(rng))
+    assert copy.state() == rng.state()
+
+
+def test_unseeded_alea_differs() -> None:
+    assert Alea().state() != Alea("alpha").state()
+
+
+def test_below_is_uint32_modulo() -> None:
+    # Random(n) = seed.uint32() % n
+    random.seed("alpha")
+    assert [random.below(1000) for _ in range(5)] == [
+        n % 1000 for n in VECTORS["alpha"][0]
+    ]
+
+
+def test_using_restores_previous_generator() -> None:
+    random.seed("outer")
+    expected = Alea("outer").uint32() % 1000
+    inner = Alea("inner")
+    with random.using(inner):
+        random.below(10)
+    assert inner.state() != Alea("inner").state()
+    assert random.below(1000) == expected