feat(player): discrete Right variant + Left level + Calibration (slice design §2)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/test_player_alteration.py

@@ -2,11 +2,14 @@ import pytest
 
 from hef.selection import Coordinate
 from player.alteration import (
+    DEFAULT_CALIBRATION,
     AnalyticalOverlay,
+    Calibration,
     ColorGrade,
     RenderPlan,
     Restyle,
     plan_alteration,
+    render_plan_to_dict,
 )
 
 
@@ -17,30 +20,32 @@ def _coord(left=0, right=0, dark=0, light=0):
 def test_all_zero_knobs_is_the_unaltered_base():
     plan = plan_alteration(_coord())
     assert plan.is_identity
+    assert plan.overlay.level == 0
     assert plan.overlay.intensity == 0.0
-    assert plan.restyle.blend == 0.0
+    assert plan.restyle.variant == 0
     assert plan.grade.tone == 0.0
     assert plan.grade.is_identity
 
 
 def test_left_drives_the_analytical_overlay_only():
     plan = plan_alteration(_coord(left=4))
+    assert plan.overlay.level == 4
     assert plan.overlay.intensity == 1.0
-    assert plan.restyle.blend == 0.0  # Left does not touch the substrate
+    assert plan.restyle.variant == 0  # Left does not touch the substrate
     assert plan.grade.tone == 0.0
 
 
-def test_right_drives_the_restyle_substrate_only():
+def test_right_selects_a_discrete_restyle_variant_only():
     plan = plan_alteration(_coord(right=2))
-    assert plan.restyle.blend == 0.5
-    assert plan.overlay.intensity == 0.0  # Right does not add overlay
+    assert plan.restyle.variant == 2
+    assert plan.overlay.level == 0  # Right does not add overlay
 
 
 def test_left_and_right_stack_not_cancel():
     # design §4.2: whole-brain corner = dreamlike substrate WITH labels on top
     plan = plan_alteration(_coord(left=4, right=4))
-    assert plan.overlay.intensity == 1.0
-    assert plan.restyle.blend == 1.0
+    assert plan.overlay.level == 4
+    assert plan.restyle.variant == 4
 
 
 def test_light_pole_grades_warm_positive_tone():
@@ -50,8 +55,7 @@ def test_light_pole_grades_warm_positive_tone():
 
 
 def test_dark_pole_grades_cool_negative_tone():
-    plan = plan_alteration(_coord(dark=4))
-    assert plan.grade.tone == -1.0
+    assert plan_alteration(_coord(dark=4)).grade.tone == -1.0
 
 
 def test_equal_dark_and_light_is_identity_grade():
@@ -66,14 +70,48 @@ def test_dark_minus_light_sets_intermediate_tone():
 
 
 def test_whole_brain_dark_corner_stacks_grade_substrate_and_overlay():
-    # design §4.2 "Dark + analytical": cold measurement over a melancholy scene
     plan = plan_alteration(_coord(left=4, right=2, dark=4, light=0))
-    assert plan.overlay.intensity == 1.0
-    assert plan.restyle.blend == 0.5
+    assert plan.overlay.level == 4
+    assert plan.restyle.variant == 2
     assert plan.grade.tone == -1.0
     assert not plan.is_identity
 
 
+def test_default_calibration_is_behavior_preserving():
+    # DEFAULT_CALIBRATION must reproduce the original three helpers exactly.
+    for left in range(5):
+        assert plan_alteration(_coord(left=left)).overlay.intensity == pytest.approx(left / 4)
+    for right in range(5):
+        assert plan_alteration(_coord(right=right)).restyle.variant == right
+    for dark in range(5):
+        for light in range(5):
+            expected = (light - dark) / 4
+            assert plan_alteration(_coord(dark=dark, light=light)).grade.tone == pytest.approx(expected)
+
+
+def test_custom_calibration_scales_mood_and_overlay():
+    cal = Calibration(mood_gain=0.5, overlay_gain=0.5, right_variant_map=(0, 0, 1, 1, 2))
+    assert plan_alteration(_coord(light=4), cal).grade.tone == pytest.approx(0.5)
+    assert plan_alteration(_coord(left=4), cal).overlay.intensity == pytest.approx(0.5)
+    assert plan_alteration(_coord(right=3), cal).restyle.variant == 1
+
+
+def test_calibration_gain_is_clamped_to_unit_range():
+    cal = Calibration(mood_gain=10.0, overlay_gain=10.0)
+    assert plan_alteration(_coord(light=4), cal).grade.tone == 1.0  # clamped, not 10
+    assert plan_alteration(_coord(left=4), cal).overlay.intensity == 1.0
+
+
+def test_render_plan_to_dict_round_trips_the_numbers():
+    d = render_plan_to_dict(plan_alteration(_coord(left=4, right=2, dark=4, light=0)))
+    assert d == {
+        "grade": {"tone": -1.0},
+        "overlay": {"level": 4, "intensity": 1.0},
+        "restyle": {"variant": 2},
+        "is_identity": False,
+    }
+
+
 def test_render_plan_is_frozen():
     plan = plan_alteration(_coord())
     with pytest.raises(Exception):