feat(cp1): port predator_evade + wire scenario registry

proteus/grid/__init__.py

@@ -1 +1,10 @@
-"""proteus.grid — the motive_grid scenario family (ported)."""
+"""proteus.grid — the motive_grid scenario family (ported).
+
+Importing this package imports :mod:`proteus.grid.scenarios`, whose
+``@register_scenario`` decorators populate the scenario registry so
+``get_scenario("predator_evade")`` resolves.
+"""
+
+from proteus.grid import scenarios  # noqa: F401  — side-effect: populate registry
+
+__all__ = ["scenarios"]

proteus/grid/scenarios/__init__.py

@@ -0,0 +1,9 @@
+"""Scenario implementations for the motive_grid family.
+
+Importing this package fires each scenario's ``@register_scenario`` decorator,
+populating the registry in :mod:`proteus.grid.scenario`.
+"""
+
+from proteus.grid.scenarios import predator_evade  # noqa: F401  — side-effect: register
+
+__all__ = ["predator_evade"]

proteus/grid/scenarios/predator_evade.py

@@ -0,0 +1,463 @@
+"""predator_evade — the bear-chase evasion scenario for motive_grid.
+
+A predator pursues the focal agent across an 8x8 grid by taking one
+shortest-path (BFS) step toward it every turn, so its motion reads as a clear
+*chase* intent rather than noise (the ToM signal the benchmark probes).  The
+world is laced with a short internal wall that forms a **dead-end to the west**,
+exactly where the focal agent has been walking.  At the Cut handover the only
+survival-correct move is to *detour* away from the wall while the fixed habit
+("keep walking west") runs the agent straight into the dead-end with the
+predator closing from behind.  That divergence — ``optimal_action`` (escape) vs
+``habit_action`` (keep west) — is the diagnostic the benchmark measures.
+
+Coordinate convention (shared with ``game.py``): ``y`` grows DOWNWARD.  Actions
+are the strings ``"up"`` ``(0,-1)``, ``"down"`` ``(0,1)``, ``"left"`` ``(-1,0)``,
+``"right"`` ``(1,0)``, ``"stay"`` ``(0,0)``.
+
+Deterministic EASY layout (seed-independent; placement is fixed, not random,
+so ``rng`` is threaded only for forward-compatible tie-breaks)::
+
+    col:  0 1 2 3 4 5 6 7      x ->
+    row 0 . . . . . . . .
+    row 1 . . . . . . . .
+    row 2 . . # . . . . .      '#' = wall  (PIXEL_PERFECT)
+    row 3 . . # A . S B .      'A' = focal start (5,3) ... walks west
+    row 4 . . # . . . . .      'B' = predator start (7,3)
+    row 5 . . # . . . . .      'S' = focal Cut-handover cell (3,3)
+    row 6 . . . . . . . .
+    row 7 . . . . . . . .
+
+Cut pre-roll (``cut_length`` EASY = 2, ``cut_focal_policy`` = "left"):
+
+    start    focal (5,3)  predator (7,3)
+    step 1   focal (4,3)  predator (6,3)
+    step 2   focal (3,3)  predator (5,3)      <- HANDOVER / diagnostic state
+
+At the handover the wall column ``x=2`` (rows 2..5) sits directly west of the
+focal at ``(3,3)``:
+
+    * ``habit_action``  = "left"  -> blocked by the wall (dead-end), no progress,
+      BFS distance to predator stays 2.
+    * ``optimal_action`` = "up"   -> steps to ``(3,2)``, the legal move that
+      MAXIMIZES BFS distance from the predator (distance 3).  ("up" and "down"
+      tie at distance 3; the fixed action order breaks the tie in favour of
+      "up".)
+
+Hence ``optimal_action != habit_action`` at the Cut — the property the whole
+discrimination metric depends on.
+
+Palette indices (consistent with :meth:`PredatorEvade.legend` and the pixels
+handed to each sprite in :meth:`PredatorEvade.build_level`):
+
+    * ``5`` -> ``'.'``  background (the arc_grid camera default)
+    * ``1`` -> ``'A'``  focal agent
+    * ``2`` -> ``'B'``  predator
+    * ``3`` -> ``'#'``  wall
+"""
+
+from __future__ import annotations
+
+import random
+from collections import deque
+from typing import TYPE_CHECKING
+
+from proteus.arc_grid import BlockingMode, Level, Sprite
+from proteus.grid.difficulty import Difficulty
+
+from ..scenario import Scenario, register_scenario
+
+if TYPE_CHECKING:
+    from ..game import MotiveGridGame
+
+# --------------------------------------------------------------------------- #
+# Palette indices (must match build_level pixels and legend()).
+# --------------------------------------------------------------------------- #
+BACKGROUND_IDX = 5  # arc_grid Camera default background
+FOCAL_IDX = 1
+PREDATOR_IDX = 2
+WALL_IDX = 3
+
+# --------------------------------------------------------------------------- #
+# EASY deterministic layout.
+# --------------------------------------------------------------------------- #
+_GRID_SIZE: tuple[int, int] = (8, 8)
+_FOCAL_START: tuple[int, int] = (5, 3)
+_PREDATOR_START: tuple[int, int] = (7, 3)
+# Vertical wall column forming the dead-end west of the focal's path.
+_WALL_CELLS: tuple[tuple[int, int], ...] = (
+    (2, 2),
+    (2, 3),
+    (2, 4),
+    (2, 5),
+)
+
+# 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.
+_DELTAS: dict[str, tuple[int, int]] = {
+    "up": (0, -1),
+    "down": (0, 1),
+    "left": (-1, 0),
+    "right": (1, 0),
+    "stay": (0, 0),
+}
+
+# Fixed deterministic tie-break order for both the predator's chase step and the
+# focal's optimal-action search.  Movement directions first (so a move that
+# strictly improves the objective is always preferred over "stay"), in the
+# canonical up/down/left/right order.
+_TIE_BREAK_ORDER: tuple[str, ...] = ("up", "down", "left", "right", "stay")
+
+# Cut pre-roll length per difficulty.  EASY = 2 (per spec §5).
+_CUT_LENGTH: dict[Difficulty, int] = {
+    Difficulty.EASY: 2,
+    Difficulty.MEDIUM: 2,
+    Difficulty.HARD: 3,
+    Difficulty.EXPERT: 3,
+}
+_DEFAULT_CUT_LENGTH = 2
+
+
+@register_scenario("predator_evade")
+class PredatorEvade(Scenario):
+    """Bear-chase evasion scenario (see module docstring for the geometry).
+
+    The scenario owns one piece of mutable bookkeeping that does not belong on
+    the world: ``_wall_cells`` (the set of wall coordinates, cached in
+    :meth:`build_level` so the BFS helpers can treat walls as blocked without
+    re-deriving them from the merged ``sys_static`` sprite) and
+    ``_last_focal_move`` (the focal's last committed move direction, used by
+    :meth:`habit_action`).  Per-game *world* state (sprite positions, step
+    count) lives on the injected :class:`~..game.MotiveGridGame`.
+    """
+
+    task_name: str = "predator_evade"
+    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, 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. "
+        "Actions: up, down, left, right, stay (up decreases the row, down "
+        "increases it; left/right move along the column). Read the predator's "
+        "approach and move to stay away from it — do not walk into walls or "
+        "dead-ends."
+    )
+
+    def __init__(self) -> None:
+        """Initialize per-game scenario bookkeeping.
+
+        ``_last_focal_move`` defaults to ``"left"`` because the focal agent
+        walks west throughout the Cut pre-roll (:meth:`cut_focal_policy`); at the
+        handover the model's "habit" is therefore to keep going west, which the
+        dead-end geometry turns into the wrong move.
+        """
+        self._wall_cells: frozenset[tuple[int, int]] = frozenset(_WALL_CELLS)
+        self._last_focal_move: str = "left"
+
+    # ------------------------------------------------------------------ #
+    # World construction
+    # ------------------------------------------------------------------ #
+    def build_level(self, rng: random.Random) -> Level:
+        """Build the EASY level: focal mid-west, predator east, dead-end wall.
+
+        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.
+
+        Args:
+            rng: Seeded RNG owned by the game/module (unused at EASY).
+
+        Returns:
+            A :class:`~squid_game.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
+
+        self._wall_cells = frozenset(_WALL_CELLS)
+
+        focal = Sprite(
+            pixels=[[FOCAL_IDX]],
+            name="focal",
+            x=_FOCAL_START[0],
+            y=_FOCAL_START[1],
+            blocking=BlockingMode.PIXEL_PERFECT,
+        )
+        predator = Sprite(
+            pixels=[[PREDATOR_IDX]],
+            name="predator",
+            x=_PREDATOR_START[0],
+            y=_PREDATOR_START[1],
+            blocking=BlockingMode.PIXEL_PERFECT,
+        )
+        sprites: list[Sprite] = [focal, predator]
+        for (wx, wy) in _WALL_CELLS:
+            sprites.append(
+                Sprite(
+                    pixels=[[WALL_IDX]],
+                    name="wall",
+                    x=wx,
+                    y=wy,
+                    blocking=BlockingMode.PIXEL_PERFECT,
+                    tags=["sys_static"],
+                )
+            )
+        return Level(sprites=sprites)
+
+    # ------------------------------------------------------------------ #
+    # Cut pre-roll
+    # ------------------------------------------------------------------ #
+    def cut_focal_policy(self, game: MotiveGridGame) -> str:
+        """Drive the focal agent west during the Cut pre-roll.
+
+        The scripted westward walk sets up the dead-end tension: by the handover
+        the focal sits just east of the wall with the predator closing behind.
+
+        Args:
+            game: The live game (unused; the policy is unconditional).
+
+        Returns:
+            ``"left"``.
+        """
+        del game
+        return "left"
+
+    def cut_length(self, difficulty) -> int:
+        """Return the Cut pre-roll step count ``K`` for *difficulty*.
+
+        Args:
+            difficulty: The session difficulty (a :class:`Difficulty`, or any
+                value; unknown values fall back to the EASY length).
+
+        Returns:
+            ``2`` for EASY (placing the focal at ``(3,3)`` against the wall).
+        """
+        return _CUT_LENGTH.get(difficulty, _DEFAULT_CUT_LENGTH)
+
+    # ------------------------------------------------------------------ #
+    # Threat motion (motive = chase)
+    # ------------------------------------------------------------------ #
+    def advance_threat(self, game: MotiveGridGame) -> None:
+        """Move the predator one BFS step along a shortest path to the focal.
+
+        The predator pursues over *free* cells only (grid minus walls), so its
+        motion is purely a function of the focal position — a reactive chase,
+        never random.  The framework only guards the focal agent's bounds, so
+        this method excludes off-grid and wall cells itself.  If no path to the
+        focal exists, the predator stays put.
+
+        Tie-break: among the neighbours that lie on a shortest path, the first
+        in :data:`_TIE_BREAK_ORDER` (up, down, left, right) wins, which is fully
+        deterministic.
+
+        Args:
+            game: The live game whose predator sprite is moved in place.
+        """
+        predator = game.predator_sprite
+        focal = game.focal_sprite
+        if predator is None or focal is None:
+            return
+
+        src = (predator.x, predator.y)
+        dst = (focal.x, focal.y)
+        if src == dst:
+            return
+
+        next_cell = self._chase_step(game, src, dst)
+        if next_cell is None:
+            return
+        predator.move(next_cell[0] - predator.x, next_cell[1] - predator.y)
+
+    def _chase_step(
+        self,
+        game: MotiveGridGame,
+        src: tuple[int, int],
+        dst: tuple[int, int],
+    ) -> tuple[int, int] | None:
+        """Return the predator's next cell on a shortest path ``src`` -> ``dst``.
+
+        Picks the free neighbour of *src* (in :data:`_TIE_BREAK_ORDER`) whose BFS
+        distance to *dst* is minimal.  Returns ``None`` if *dst* is unreachable.
+
+        Args:
+            game: The live game (for bounds checks).
+            src: The predator's current ``(x, y)``.
+            dst: The focal's ``(x, y)``.
+        """
+        best_cell: tuple[int, int] | None = None
+        best_dist: int | None = None
+        for action in _TIE_BREAK_ORDER:
+            dx, dy = _DELTAS[action]
+            if dx == 0 and dy == 0:
+                continue
+            cand = (src[0] + dx, src[1] + dy)
+            if not self._is_free(game, cand):
+                continue
+            dist = self._bfs_distance(game, cand, dst)
+            if dist is None:
+                continue
+            if best_dist is None or dist < best_dist:
+                best_dist = dist
+                best_cell = cand
+        return best_cell
+
+    # ------------------------------------------------------------------ #
+    # Outcome
+    # ------------------------------------------------------------------ #
+    def check_elimination(self, game: MotiveGridGame) -> bool:
+        """Return whether the predator has captured the focal agent.
+
+        Args:
+            game: The live game to inspect.
+
+        Returns:
+            ``True`` iff the focal and predator occupy the same cell.
+        """
+        focal = game.focal_sprite
+        predator = game.predator_sprite
+        if focal is None or predator is None:
+            return False
+        return focal.x == predator.x and focal.y == predator.y
+
+    # ------------------------------------------------------------------ #
+    # Answer keys
+    # ------------------------------------------------------------------ #
+    def optimal_action(self, game: MotiveGridGame) -> str:
+        """Return the legal move that maximizes BFS distance from the predator.
+
+        Considers every action in :data:`_TIE_BREAK_ORDER`; an action is *legal*
+        only if its resulting cell is on-grid and not a wall (moves into a wall
+        or off-grid are discarded, never silently treated as "stay").  Among the
+        legal actions the one whose resulting cell has the greatest BFS distance
+        to the predator wins; ties break by the fixed action order.  This is the
+        motive-congruent escape — the prediction answer key.
+
+        Args:
+            game: The live game to inspect.
+
+        Returns:
+            One of ``"up"``, ``"down"``, ``"left"``, ``"right"``, ``"stay"``.
+            ``"stay"`` is returned only if no other action is legal (boxed in).
+        """
+        focal = game.focal_sprite
+        predator = game.predator_sprite
+        if focal is None or predator is None:
+            return "stay"
+
+        src = (focal.x, focal.y)
+        pred_cell = (predator.x, predator.y)
+
+        best_action = "stay"
+        best_dist: int | None = None
+        for action in _TIE_BREAK_ORDER:
+            dx, dy = _DELTAS[action]
+            cand = (src[0] + dx, src[1] + dy)
+            if not self._is_free(game, cand):
+                # Off-grid or into a wall: illegal, skip (covers blocked "left").
+                continue
+            dist = self._bfs_distance(game, cand, pred_cell)
+            if dist is None:
+                continue
+            if best_dist is None or dist > best_dist:
+                best_dist = dist
+                best_action = action
+        return best_action
+
+    def habit_action(self, game: MotiveGridGame) -> str:
+        """Return the fixed-habit action: repeat the last committed move.
+
+        The focal walks west all through the Cut pre-roll, so at the handover the
+        habit is ``"left"`` (which the dead-end geometry makes the wrong move).
+        ``MotiveGridModule`` (CP5) is expected to call :meth:`record_focal_move`
+        after each committed action so the habit tracks the live trajectory; the
+        default reflects the pre-roll direction.
+
+        Args:
+            game: The live game (unused; the habit is carried as scenario state).
+
+        Returns:
+            The last committed move direction (``"left"`` at the Cut).
+        """
+        del game
+        return self._last_focal_move
+
+    def record_focal_move(self, action: str) -> None:
+        """Record the focal's last committed move so :meth:`habit_action` tracks it.
+
+        A non-moving ``"stay"`` does not change the established habit direction
+        (the habit is "the direction I keep heading"), so it is ignored.
+
+        Args:
+            action: The action just committed by the focal agent.
+        """
+        if action in _DELTAS and action != "stay":
+            self._last_focal_move = action
+
+    # ------------------------------------------------------------------ #
+    # ASCII legend
+    # ------------------------------------------------------------------ #
+    def legend(self) -> dict[int, str]:
+        """Return the palette-index -> single-character symbol map.
+
+        Returns:
+            ``{5: '.', 1: 'A', 2: 'B', 3: '#'}`` — background, focal, predator,
+            wall (consistent with the pixels assigned in :meth:`build_level`).
+        """
+        return {
+            BACKGROUND_IDX: ".",
+            FOCAL_IDX: "A",
+            PREDATOR_IDX: "B",
+            WALL_IDX: "#",
+        }
+
+    # ------------------------------------------------------------------ #
+    # BFS / free-cell helpers
+    # ------------------------------------------------------------------ #
+    def _is_free(self, game: MotiveGridGame, cell: tuple[int, int]) -> bool:
+        """Return whether *cell* is on-grid and not a wall.
+
+        Args:
+            game: The live game (for the bounds check).
+            cell: The ``(x, y)`` cell to test.
+        """
+        return game.within_bounds(cell[0], cell[1]) and cell not in self._wall_cells
+
+    def _bfs_distance(
+        self,
+        game: MotiveGridGame,
+        src: tuple[int, int],
+        dst: tuple[int, int],
+    ) -> int | None:
+        """Return the shortest 4-neighbour path length over free cells.
+
+        Args:
+            game: The live game (for bounds checks).
+            src: Start cell ``(x, y)`` (assumed free).
+            dst: Goal cell ``(x, y)``.
+
+        Returns:
+            The number of steps from *src* to *dst* over free cells, or ``None``
+            if *dst* is unreachable (or either endpoint is a wall).
+        """
+        if not self._is_free(game, src) or not self._is_free(game, dst):
+            return None
+        if src == dst:
+            return 0
+        seen = {src}
+        queue: deque[tuple[tuple[int, int], int]] = deque([(src, 0)])
+        while queue:
+            cell, dist = queue.popleft()
+            for action in _TIE_BREAK_ORDER:
+                dx, dy = _DELTAS[action]
+                if dx == 0 and dy == 0:
+                    continue
+                nxt = (cell[0] + dx, cell[1] + dy)
+                if nxt in seen or not self._is_free(game, nxt):
+                    continue
+                if nxt == dst:
+                    return dist + 1
+                seen.add(nxt)
+                queue.append((nxt, dist + 1))
+        return None

tests/grid/test_predator_evade_registered.py

@@ -0,0 +1,8 @@
+def test_importing_proteus_grid_registers_predator_evade():
+    import proteus.grid  # noqa: F401  (side-effect: registers scenarios)
+    from proteus.grid.scenario import get_scenario, list_scenarios
+    assert "predator_evade" in list_scenarios()
+    cls = get_scenario("predator_evade")
+    inst = cls()
+    assert inst.task_name == "predator_evade"
+    assert inst.grid_size == (8, 8)