feat(cp6): runtime.rollout — deterministic optimal-trajectory simulator

proteus/runtime/rollout.py

@@ -0,0 +1,73 @@
+"""Deterministic optimal-trajectory rollout for the trajectory metric.
+
+Mirrors viz.reconstruct's engine-replay pattern: rebuild the game from
+(scenario, seed, difficulty), replay the scripted Cut pre-roll, then play
+OPTIMALLY (scenario.optimal_action each turn) for up to n_turns, capturing the
+pre-move focal position per turn and the final safety distance. This is the
+"ideal motive-reader" reference path the realized trajectory is scored against.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+
+
+@dataclass(frozen=True)
+class RolloutResult:
+    """The optimal player's trajectory for one session."""
+
+    focal_positions: list[tuple[int, int]]  # pre-move focal cell per optimal turn
+    final_safety_distance: int | None       # BFS focal->predator at rollout end
+
+
+def optimal_rollout(
+    scenario_name: str,
+    seed: int | None,
+    difficulty: Difficulty,
+    n_turns: int,
+) -> RolloutResult:
+    """Simulate the optimal trajectory and return its positions + final safety.
+
+    Args:
+        scenario_name: Registered scenario key.
+        seed: Session seed (same world as the real run).
+        difficulty: Session difficulty band.
+        n_turns: Cap on optimal play turns (use the realized play length so the
+            two trajectories align index-for-index).
+
+    Returns:
+        A :class:`RolloutResult` with the per-turn pre-move focal positions of
+        the optimal player and the final BFS safety distance at rollout end.
+    """
+    scenario = get_scenario(scenario_name)()
+    rng = random.Random(seed)
+    cut_length = scenario.cut_length(difficulty)
+    game = MotiveGridGame(scenario, rng, difficulty, max_steps=cut_length + n_turns)
+
+    # Cut pre-roll (scripted policy), identical to SessionRunner.
+    for _ in range(cut_length):
+        action = scenario.cut_focal_policy(game)
+        game.apply_motive_action(action)
+        scenario.record_focal_move(action)
+
+    focal_positions: list[tuple[int, int]] = []
+    for _ in range(n_turns):
+        focal = game.focal_sprite
+        if focal is None:
+            break
+        focal_positions.append((focal.x, focal.y))  # pre-move
+        action = scenario.optimal_action(game)
+        game.apply_motive_action(action)
+        scenario.record_focal_move(action)
+        if game.eliminated or game.survived:
+            break
+
+    return RolloutResult(
+        focal_positions=focal_positions,
+        final_safety_distance=scenario.safety_distance(game),
+    )

tests/runtime/test_rollout.py

@@ -0,0 +1,23 @@
+from proteus.grid.difficulty import Difficulty
+from proteus.runtime.rollout import RolloutResult, optimal_rollout
+
+
+def test_optimal_rollout_is_deterministic():
+    a = optimal_rollout("predator_evade", seed=42, difficulty=Difficulty.EASY, n_turns=5)
+    b = optimal_rollout("predator_evade", seed=42, difficulty=Difficulty.EASY, n_turns=5)
+    assert isinstance(a, RolloutResult)
+    assert a.focal_positions == b.focal_positions
+    assert a.final_safety_distance == b.final_safety_distance
+
+
+def test_optimal_rollout_length_capped_by_n_turns():
+    r = optimal_rollout("predator_evade", seed=42, difficulty=Difficulty.EASY, n_turns=3)
+    assert len(r.focal_positions) <= 3
+    # Each recorded position is the PRE-move focal cell for that optimal turn.
+    assert all(isinstance(p, tuple) and len(p) == 2 for p in r.focal_positions)
+
+
+def test_optimal_rollout_first_position_is_handover():
+    # The first optimal pre-move position equals the focal's handover cell.
+    r = optimal_rollout("predator_evade", seed=42, difficulty=Difficulty.EASY, n_turns=5)
+    assert r.focal_positions[0] == (3, 3)  # EASY handover