feat(cp8): scenario max_bfs_distance + agent_distance_delta helpers

proteus/grid/scenario.py

@@ -226,6 +226,27 @@ class Scenario(ABC):
         """
         return None
 
+    def max_bfs_distance(self, game: MotiveGridGame) -> int | None:
+        """Free-cell graph diameter (max finite BFS distance), None by default.
+
+        Used to normalise distance metrics (``distance_auc``) and pressure into a
+        unit range. Survival scenarios override it; others inherit ``None`` so the
+        normalisation is simply skipped.
+        """
+        return None
+
+    def agent_distance_delta(
+        self, game, focal_before, predator_before
+    ) -> float | None:
+        """Chase-corrected action quality (None by default).
+
+        ``dist(post_focal, predator_before) - dist(focal_before, predator_before)``
+        — measures whether the participant's own move opened distance from the
+        threat, independent of the predator's chase response (spec §6.2). Non-
+        survival scenarios inherit ``None``.
+        """
+        return None
+
 
 # --------------------------------------------------------------------------- #
 # Scenario registry

proteus/grid/scenarios/predator_evade.py

@@ -505,6 +505,37 @@ class PredatorEvade(Scenario):
             return None
         return self._bfs_distance(game, (focal.x, focal.y), (predator.x, predator.y))
 
+    def max_bfs_distance(self, game: MotiveGridGame) -> int | None:
+        """Free-cell graph diameter: the max finite BFS distance between any two
+        free cells. Used to normalise distance metrics / pressure into [0, 1]."""
+        cells = [
+            (x, y)
+            for x in range(self.grid_size[0])
+            for y in range(self.grid_size[1])
+            if self._is_free(game, (x, y))
+        ]
+        best = 0
+        for i, a in enumerate(cells):
+            for b in cells[i + 1:]:
+                d = self._bfs_distance(game, a, b)
+                if d is not None and d > best:
+                    best = d
+        return best
+
+    def agent_distance_delta(
+        self, game: MotiveGridGame, focal_before, predator_before
+    ) -> float | None:
+        """Chase-corrected action quality (spec §6.2): how much the focal's own
+        move opened distance from the *pre-move* predator cell."""
+        focal = game.focal_sprite
+        if focal is None:
+            return None
+        d_after = self._bfs_distance(game, (focal.x, focal.y), predator_before)
+        d_before = self._bfs_distance(game, focal_before, predator_before)
+        if d_after is None or d_before is None:
+            return None
+        return float(d_after - d_before)
+
     # ------------------------------------------------------------------ #
     # ASCII legend
     # ------------------------------------------------------------------ #

tests/grid/test_distance_helpers.py

@@ -0,0 +1,34 @@
+import random
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import Scenario, get_scenario
+
+
+def _game():
+    s = get_scenario("predator_evade")()
+    g = MotiveGridGame(s, random.Random(42), Difficulty.EASY, max_steps=10)
+    return s, g
+
+
+def test_base_defaults_none():
+    assert Scenario.max_bfs_distance is not None  # method exists
+    # a bare scenario method default returns None (documented contract)
+
+
+def test_max_bfs_distance_positive_on_easy():
+    s, g = _game()
+    d = s.max_bfs_distance(g)
+    assert isinstance(d, int) and d > 0
+
+
+def test_agent_distance_delta_positive_when_moving_away():
+    s, g = _game()
+    focal = g.focal_sprite           # EASY: (5,3)
+    pred = g.predator_sprite         # EASY: (7,3)
+    before_focal = (focal.x, focal.y)
+    before_pred = (pred.x, pred.y)
+    # move focal up to (5,2) -> farther from (7,3)
+    g.apply_motive_action("up")
+    delta = s.agent_distance_delta(g, before_focal, before_pred)
+    assert delta is not None and delta > 0