feat(cp6): Scenario.build_level takes difficulty + record_focal_move/safety_distance defaults

proteus/grid/game.py

@@ -100,7 +100,7 @@ class MotiveGridGame(ARCBaseGame):
             difficulty: Session difficulty (passed through to the scenario).
             max_steps: Survival budget; surviving this many played turns wins.
         """
-        level = scenario.build_level(rng)
+        level = scenario.build_level(rng, difficulty)
         width, height = scenario.grid_size
         camera = Camera(width=width, height=height)
 

proteus/grid/scenario.py

@@ -39,6 +39,7 @@ if TYPE_CHECKING:
     # is injected into MotiveGridGame, and the game reads it back here only
     # for annotations.
     from .game import MotiveGridGame
+    from .difficulty import Difficulty
 
 
 class Scenario(ABC):
@@ -63,19 +64,18 @@ class Scenario(ABC):
     rules_text: str
 
     @abstractmethod
-    def build_level(self, rng: random.Random) -> Level:
-        """Build the arc_grid level: walls plus initial sprite positions.
+    def build_level(self, rng: random.Random, difficulty: Difficulty) -> Level:
+        """Build the arc_grid level for *difficulty*: walls + initial sprites.
 
-        All randomness (wall placement, initial positions) must flow from
-        *rng* so that a given ``(scenario, seed)`` is fully deterministic.
+        All randomness must flow from *rng* so that a given
+        ``(scenario, seed, difficulty)`` is fully deterministic.
 
         Args:
             rng: Seeded RNG owned by the game/module.
+            difficulty: The session difficulty band (a ``Difficulty``).
 
         Returns:
-            A freshly built :class:`~proteus.arc_grid.Level` containing the
-            focal sprite (``name="focal"``), the predator sprite
-            (``name="predator"``), and any walls / NPCs.
+            A freshly built :class:`~proteus.arc_grid.Level`.
         """
         raise NotImplementedError
 
@@ -175,6 +175,23 @@ class Scenario(ABC):
         """
         raise NotImplementedError
 
+    def record_focal_move(self, action: str) -> None:
+        """Record the focal's last committed move (no-op by default).
+
+        Scenarios whose ``habit_action`` tracks the live trajectory override
+        this; others (and future scenarios) inherit a safe no-op so callers
+        like ``SessionRunner`` and ``viz.reconstruct`` never hit AttributeError.
+        """
+
+    def safety_distance(self, game: MotiveGridGame) -> int | None:
+        """Return the focal's 'safety' distance for this motive (None by default).
+
+        Survival-style scenarios return the BFS distance from the focal to the
+        threat (larger = safer). Non-survival scenarios leave it ``None`` so the
+        trajectory final-distance metric is simply skipped for them.
+        """
+        return None
+
 
 # --------------------------------------------------------------------------- #
 # Scenario registry

proteus/grid/scenarios/predator_evade.py

@@ -158,23 +158,27 @@ class PredatorEvade(Scenario):
     # ------------------------------------------------------------------ #
     # World construction
     # ------------------------------------------------------------------ #
-    def build_level(self, rng: random.Random) -> Level:
-        """Build the EASY level: focal mid-west, predator east, dead-end wall.
+    def build_level(self, rng: random.Random, difficulty: Difficulty) -> Level:
+        """Build the level for *difficulty*: focal, predator, walls.
 
         The layout is deterministic (fixed coordinates), so *rng* is accepted
         for interface conformance and forward compatibility (harder difficulties
         may randomise wall placement) but is not consumed here.  ``_wall_cells``
         is refreshed so the BFS helpers stay in sync with the built level.
+        Per-difficulty dispatch is added in Task 2; currently all difficulties
+        produce the EASY layout unchanged.
 
         Args:
             rng: Seeded RNG owned by the game/module (unused at EASY).
+            difficulty: The session difficulty band (a ``Difficulty``).
 
         Returns:
-            A :class:`~squid_game.arc_grid.Level` with the focal
+            A :class:`~proteus.arc_grid.Level` with the focal
             (``name="focal"``), predator (``name="predator"``), and the wall
             sprites (tagged ``sys_static`` so the engine merges them).
         """
-        del rng  # deterministic EASY layout; reserved for harder difficulties
+        del rng  # deterministic layout; rng reserved for tie-breaks
+        del difficulty  # per-difficulty dispatch added in Task 2
 
         self._wall_cells = frozenset(_WALL_CELLS)
 

tests/grid/test_difficulty_layouts.py

@@ -0,0 +1,26 @@
+import random
+
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.scenario import Scenario, get_scenario
+
+
+def _scenario():
+    return get_scenario("predator_evade")()
+
+
+def test_build_level_accepts_difficulty():
+    s = _scenario()
+    level = s.build_level(random.Random(42), Difficulty.EASY)
+    names = {sp.name for sp in level.get_sprites()}
+    assert "focal" in names and "predator" in names
+
+
+def test_record_focal_move_default_is_noop_on_base():
+    # hasattr proves the no-op default is now inherited from the Scenario ABC
+    # (so non-tracking scenarios never AttributeError). PredatorEvade overrides
+    # it to track the live trajectory, which habit_action reads back.
+    assert hasattr(Scenario, "record_focal_move")
+    # PredatorEvade still tracks it (used by habit_action).
+    s = _scenario()
+    s.record_focal_move("up")
+    assert s.habit_action(None) == "up"