feat(cp6): per-difficulty hand-authored predator_evade layouts (EASY unchanged)

proteus/grid/scenarios/predator_evade.py

@@ -59,6 +59,7 @@ from __future__ import annotations
 
 import random
 from collections import deque
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from proteus.arc_grid import BlockingMode, Level, Sprite
@@ -91,6 +92,57 @@ _WALL_CELLS: tuple[tuple[int, int], ...] = (
     (2, 5),
 )
 
+# --------------------------------------------------------------------------- #
+# Per-difficulty hand-authored layouts.
+# --------------------------------------------------------------------------- #
+
+@dataclass(frozen=True)
+class _Layout:
+    """A hand-authored deterministic layout for one difficulty band."""
+
+    grid_size: tuple[int, int]
+    focal_start: tuple[int, int]
+    predator_start: tuple[int, int]
+    wall_cells: tuple[tuple[int, int], ...]
+
+
+# Candidate hand-authored layouts. Tuned under the golden invariant test
+# (Task 3): the pre-roll direction ("left") must dead-end into a wall at the
+# handover while a perpendicular move increases BFS distance, so
+# optimal_action != habit_action. Adjust coordinates if Task 3 fails.
+_LAYOUTS: dict[Difficulty, _Layout] = {
+    Difficulty.EASY: _Layout(
+        grid_size=(8, 8),
+        focal_start=(5, 3),
+        predator_start=(7, 3),
+        wall_cells=((2, 2), (2, 3), (2, 4), (2, 5)),
+    ),
+    Difficulty.MEDIUM: _Layout(
+        grid_size=(10, 10),
+        focal_start=(6, 4),
+        predator_start=(8, 4),
+        wall_cells=tuple((3, y) for y in range(2, 8)),
+    ),
+    Difficulty.HARD: _Layout(
+        grid_size=(12, 12),
+        focal_start=(7, 5),
+        predator_start=(9, 5),
+        wall_cells=(
+            tuple((3, y) for y in range(3, 9))
+            + tuple((x, 8) for x in range(4, 7))
+        ),
+    ),
+    Difficulty.EXPERT: _Layout(
+        grid_size=(12, 12),
+        focal_start=(7, 5),
+        predator_start=(9, 4),
+        wall_cells=(
+            tuple((3, y) for y in range(2, 10))
+            + ((4, 3), (5, 3))
+        ),
+    ),
+}
+
 # Action string -> (dx, dy).  Mirror of game._DIRECTION_DELTAS; duplicated here
 # so the scenario's answer-key reasoning is self-contained and does not import
 # private game internals.
@@ -132,9 +184,12 @@ class PredatorEvade(Scenario):
     """
 
     task_name: str = "predator_evade"
+    # Default hint only; build_level() overwrites this per instance with the
+    # difficulty-specific size. Read scenario.grid_size only AFTER build_level
+    # has been called (the game sizes its camera from it right after building).
     grid_size: tuple[int, int] = _GRID_SIZE
     rules_text: str = (
-        "You control the focal agent 'A' on an 8x8 grid. A predator 'B' hunts "
+        "You control the focal agent 'A' on a grid. A predator 'B' hunts "
         "you, moving one cell along the shortest path toward you every turn. "
         "Walls '#' block movement; '.' is open ground. You are eliminated if "
         "the predator reaches your cell. Survive as long as you can. "
@@ -159,45 +214,38 @@ class PredatorEvade(Scenario):
     # World construction
     # ------------------------------------------------------------------ #
     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.
+        """Build the hand-authored level for *difficulty* (deterministic).
 
         Args:
-            rng: Seeded RNG owned by the game/module (unused at EASY).
-            difficulty: The session difficulty band (a ``Difficulty``).
+            rng: Seeded RNG (reserved for tie-breaks; layouts are fixed).
+            difficulty: The session difficulty band.
 
         Returns:
-            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).
+            A :class:`~proteus.arc_grid.Level` with focal, predator, and walls.
         """
-        del rng  # deterministic layout; rng reserved for tie-breaks
-        del difficulty  # per-difficulty dispatch added in Task 2
-
-        self._wall_cells = frozenset(_WALL_CELLS)
+        del rng  # deterministic hand-authored layouts
+        layout = _LAYOUTS.get(difficulty, _LAYOUTS[Difficulty.EASY])
+        self._wall_cells = frozenset(layout.wall_cells)
+        # Instance attribute shadows the class default so the camera and
+        # within_bounds both see THIS band's size (they read scenario.grid_size).
+        self.grid_size = layout.grid_size
 
         focal = Sprite(
             pixels=[[FOCAL_IDX]],
             name="focal",
-            x=_FOCAL_START[0],
-            y=_FOCAL_START[1],
+            x=layout.focal_start[0],
+            y=layout.focal_start[1],
             blocking=BlockingMode.PIXEL_PERFECT,
         )
         predator = Sprite(
             pixels=[[PREDATOR_IDX]],
             name="predator",
-            x=_PREDATOR_START[0],
-            y=_PREDATOR_START[1],
+            x=layout.predator_start[0],
+            y=layout.predator_start[1],
             blocking=BlockingMode.PIXEL_PERFECT,
         )
         sprites: list[Sprite] = [focal, predator]
-        for (wx, wy) in _WALL_CELLS:
+        for (wx, wy) in layout.wall_cells:
             sprites.append(
                 Sprite(
                     pixels=[[WALL_IDX]],

tests/grid/test_difficulty_layouts.py

@@ -1,6 +1,9 @@
 import random
 
+import numpy as np
+
 from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
 from proteus.grid.scenario import Scenario, get_scenario
 
 
@@ -24,3 +27,38 @@ def test_record_focal_move_default_is_noop_on_base():
     s = _scenario()
     s.record_focal_move("up")
     assert s.habit_action(None) == "up"
+
+
+_BANDS = [Difficulty.EASY, Difficulty.MEDIUM, Difficulty.HARD, Difficulty.EXPERT]
+
+
+def _game(difficulty, seed=42):
+    s = _scenario()
+    return MotiveGridGame(s, random.Random(seed), difficulty, max_steps=20), s
+
+
+def test_easy_layout_unchanged():
+    # EASY remains the 8x8 single-wall world: focal (5,3), predator (7,3).
+    game, _ = _game(Difficulty.EASY)
+    assert game.current_grid().shape == (8, 8)
+    assert (game.focal_sprite.x, game.focal_sprite.y) == (5, 3)
+    assert (game.predator_sprite.x, game.predator_sprite.y) == (7, 3)
+
+
+def test_bands_have_distinct_grid_sizes_or_starts():
+    seen = set()
+    for d in _BANDS:
+        game, _ = _game(d)
+        h, w = game.current_grid().shape
+        fx, fy = game.focal_sprite.x, game.focal_sprite.y
+        px, py = game.predator_sprite.x, game.predator_sprite.y
+        seen.add((h, w, fx, fy, px, py))
+    # All four bands must be pairwise distinct: each band's (size, focal, predator) tuple unique.
+    assert len(seen) == 4
+
+
+def test_each_band_is_deterministic():
+    for d in _BANDS:
+        g1, _ = _game(d, seed=7)
+        g2, _ = _game(d, seed=7)
+        assert np.array_equal(g1.current_grid(), g2.current_grid())