feat(cp7): MemoryTurn/MemoryCheckpoint models (JSON round-trip)

proteus/runtime/memory.py

@@ -0,0 +1,58 @@
+"""Memory checkpoint models + persistence for the CP7 memory pre-roll.
+
+A MemoryCheckpoint is one full-information self-play episode the playing model
+ran *before* the scored game. It is persisted as a single-file JSON checkpoint
+per (model, timestamp) and shown at the handover as the model's prior
+experience. Like ``trace.py`` this module is a serialization boundary: it
+imports only pydantic + stdlib and NO other runtime module.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class MemoryTurn(BaseModel):
+    """One self-play turn of the memory episode.
+
+    Attributes:
+        turn_idx: 1-based index within the memory episode.
+        frame_ascii: The pre-move grid the model saw this memory turn.
+        action: The action the model committed.
+        reasoning: The model's reasoning excerpt (may be truncated).
+        focal_pos: Focal ``(x, y)`` BEFORE the move (JSON array on disk).
+        predator_pos: Predator ``(x, y)`` BEFORE the move.
+    """
+
+    turn_idx: int
+    frame_ascii: str
+    action: str
+    reasoning: str = ""
+    focal_pos: tuple[int, int]
+    predator_pos: tuple[int, int]
+
+
+class MemoryCheckpoint(BaseModel):
+    """A persisted full-info self-play episode used as handover memory.
+
+    Attributes:
+        model: Provider model identifier that produced the episode.
+        scenario: Registered scenario name.
+        motive_category: Category label (default ``"survival"``).
+        difficulty: Difficulty band string.
+        seed: Seed of the memory world (same as the scored game).
+        created_at: ISO-ish stamp from an injectable clock (filesystem-safe).
+        memory_turns: The episode's per-turn records, in play order.
+        outcome: ``"survived"`` or ``"eliminated"``.
+        transparent_prompt: The full-info brief used to drive the episode.
+    """
+
+    model: str
+    scenario: str
+    motive_category: str = "survival"
+    difficulty: str
+    seed: int | None = None
+    created_at: str
+    memory_turns: list[MemoryTurn] = Field(default_factory=list)
+    outcome: str
+    transparent_prompt: str

tests/runtime/test_memory.py

@@ -0,0 +1,39 @@
+from proteus.runtime.memory import MemoryCheckpoint, MemoryTurn
+
+
+def _checkpoint() -> MemoryCheckpoint:
+    return MemoryCheckpoint(
+        model="demo",
+        scenario="predator_evade",
+        difficulty="easy",
+        seed=42,
+        created_at="2026-06-02T10-40-56Z",
+        memory_turns=[
+            MemoryTurn(
+                turn_idx=1, frame_ascii="FRAME-A", action="up",
+                reasoning="r1", focal_pos=(5, 3), predator_pos=(7, 3),
+            ),
+        ],
+        outcome="survived",
+        transparent_prompt="brief",
+    )
+
+
+def test_checkpoint_round_trips_through_json():
+    ck = _checkpoint()
+    restored = MemoryCheckpoint.model_validate_json(ck.model_dump_json())
+    assert restored.model == "demo"
+    assert restored.memory_turns[0].action == "up"
+    assert restored.outcome == "survived"
+    # positions come back as tuples (pydantic coerces the JSON arrays)
+    assert restored.memory_turns[0].focal_pos == (5, 3)
+
+
+def test_checkpoint_defaults():
+    ck = MemoryCheckpoint(
+        model="m", scenario="s", difficulty="easy", seed=None,
+        created_at="t", memory_turns=[], outcome="survived",
+        transparent_prompt="b",
+    )
+    assert ck.motive_category == "survival"
+    assert ck.memory_turns == []