Implement phase-memory foundation

tests/test_lifecycle.py

@@ -0,0 +1,49 @@
+from datetime import datetime, timezone
+
+from phase_memory.lifecycle import plan_compaction, plan_phase_transition, plan_refresh, plan_retention
+from phase_memory.models import LifecycleActionKind, LifecycleState, MemoryNode, MemoryPhase
+
+
+def test_phase_transition_to_stabilized_requires_review() -> None:
+    node = MemoryNode("event.restart", "episode", "Useful restart trace", phase=MemoryPhase.FLUID)
+
+    action = plan_phase_transition(node, MemoryPhase.STABILIZED)
+
+    assert action.action == LifecycleActionKind.TRANSITION_PHASE
+    assert action.requires_review
+    assert action.to_state == LifecycleState.REVIEW_NEEDED
+    assert action.metadata["to_phase"] == "stabilized"
+
+
+def test_retention_plans_stale_and_delete_requested_without_physical_delete() -> None:
+    now = datetime(2026, 5, 18, tzinfo=timezone.utc)
+    stale = MemoryNode(
+        "stale",
+        "episode",
+        freshness={"updated_at": "2026-05-01T00:00:00+00:00"},
+    )
+    old = MemoryNode(
+        "old",
+        "episode",
+        freshness={"updated_at": "2026-04-01T00:00:00+00:00"},
+    )
+
+    actions = plan_retention([stale, old], stale_after_days=7, delete_after_days=30, now=now)
+
+    by_target = {action.target_id: action for action in actions}
+    assert by_target["stale"].action == LifecycleActionKind.MARK_STALE
+    assert by_target["old"].action == LifecycleActionKind.REQUEST_DELETE
+    assert by_target["old"].metadata["physical_delete"] is False
+
+
+def test_compaction_and_refresh_are_reviewable_plans() -> None:
+    node = MemoryNode("artifact.profile", "artifact", "Profile text", freshness={"source_digest": "old"})
+
+    compact = plan_compaction([node])
+    refresh = plan_refresh([node], source_digest_by_node_id={"artifact.profile": "new"})[0]
+
+    assert compact.action == LifecycleActionKind.COMPACT
+    assert compact.requires_review
+    assert refresh.action == LifecycleActionKind.REFRESH
+    assert refresh.requires_review
+    assert refresh.metadata["proposed_digest"] == "new"