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

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

player/alteration.py

@@ -1,22 +1,18 @@
 """The alteration engine: a knob vector -> a layered RenderPlan (design §4, §5).
 
-Replaces the 2026-06-04 nearest-match *selection* with a *transformation* of a
-neutral base clip. Given the four experience knobs, it produces three layers
-that compose per §4.2:
+Reconciled slice (2026-06-07): the Right axis is a DISCRETE selection of a
+pre-baked, flow-stabilized restyle variant (not a continuous blend), the Left
+axis carries its knob LEVEL so a runtime annotation track can pick which labels
+show, and a frozen `Calibration` parameterizes the knob->strength curves so they
+can be tuned by eye in the simulator and baked into DEFAULT_CALIBRATION.
 
-  - Substrate transforms (alter pixels, blend with each other):
-      * Restyle  -- the Right axis: a pre-baked generative v2v dreamlike restyle.
-      * ColorGrade -- the mood axis (Dark/Light): a deterministic color grade.
-  - Overlay (composited on top of the substrate):
-      * AnalyticalOverlay -- the Left axis: HUD/labels/measurement.
-
-Left and Right are NOT opposites; they live on different layers and stack
-(§4.2). Dark and Light are the two poles of one mood grade whose center is the
-identity (§5).
-
-Calibration note: the knob->strength curves below are the single source of
-truth for how a 0..4 position maps to a transform strength. See the session
-0006 transcript Deferred decisions for the §3-vs-§4.2/§5 reconciliation.
+Layers compose per §4.2:
+  - Substrate: ColorGrade (Dark/Light mood, center = identity §5) + a pre-baked
+    Right restyle variant.
+  - Overlay: AnalyticalOverlay (Left), composited on top at runtime.
+Left and Right stack (different layers); Dark/Light are the two poles of one
+mood grade. See docs/superpowers/specs/2026-06-07-reconciled-simulator-
+alteration-slice-design.md.
 """
 
 from __future__ import annotations
@@ -28,6 +24,27 @@ from hef.selection import Coordinate
 KNOB_MAX = 4  # knob full-scale (0..4)
 
 
+def _clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """Tunable knob->strength curves (settled by eye in the sim, then baked).
+
+    - mood_gain: scales the signed Dark/Light tone (result clamped to [-1, 1]).
+    - overlay_gain: scales the Left overlay intensity (clamped to [0, 1]).
+    - right_variant_map: knob value (0..4) -> pre-baked Right variant index.
+    """
+
+    mood_gain: float = 1.0
+    overlay_gain: float = 1.0
+    right_variant_map: tuple = (0, 1, 2, 3, 4)
+
+
+DEFAULT_CALIBRATION = Calibration()
+
+
 @dataclass(frozen=True)
 class ColorGrade:
     """Mood-axis grade (§5). `tone` is signed: >0 warm yellow->white (light),
@@ -42,18 +59,20 @@ class ColorGrade:
 
 @dataclass(frozen=True)
 class AnalyticalOverlay:
-    """Left axis (§4.1): analytical HUD/annotation/labels, composited on top.
-    `intensity` 0..1 (0 = no overlay)."""
+    """Left axis (§4.1): analytical HUD/annotation, composited on top at runtime.
+    `level` is the Left knob (0..4); a runtime annotation track uses it to pick
+    which labels appear. `intensity` 0..1 is the overlay opacity/strength."""
 
+    level: int
     intensity: float
 
 
 @dataclass(frozen=True)
 class Restyle:
-    """Right axis (§4.1): pre-baked generative v2v dreamlike substrate.
-    `blend` 0..1 (0 = raw substrate, no restyle)."""
+    """Right axis (§4.1): selects a pre-baked, flow-stabilized restyle variant.
+    `variant` is a discrete index (0 = raw base, no restyle)."""
 
-    blend: float
+    variant: int
 
 
 @dataclass(frozen=True)
@@ -69,30 +88,42 @@ class RenderPlan:
         """True when the plan leaves the neutral base un-altered."""
         return (
             self.grade.is_identity
-            and self.overlay.intensity == 0.0
-            and self.restyle.blend == 0.0
+            and self.overlay.level == 0
+            and self.restyle.variant == 0
         )
 
 
-def _overlay_intensity(left: int) -> float:
-    """Left knob -> analytical-overlay intensity (0..1)."""
-    return left / KNOB_MAX
+def _overlay_intensity(left: int, cal: Calibration) -> float:
+    return _clamp(cal.overlay_gain * left / KNOB_MAX, 0.0, 1.0)
 
 
-def _restyle_blend(right: int) -> float:
-    """Right knob -> v2v restyle blend (0..1)."""
-    return right / KNOB_MAX
+def _right_variant(right: int, cal: Calibration) -> int:
+    return cal.right_variant_map[right]
 
 
-def _mood_tone(dark: int, light: int) -> float:
-    """(dark, light) -> signed mood grade in [-1, 1]; equal -> 0 identity (§5)."""
-    return (light - dark) / KNOB_MAX
+def _mood_tone(dark: int, light: int, cal: Calibration) -> float:
+    return _clamp(cal.mood_gain * (light - dark) / KNOB_MAX, -1.0, 1.0)
 
 
-def plan_alteration(coord: Coordinate) -> RenderPlan:
+def plan_alteration(
+    coord: Coordinate, calibration: Calibration = DEFAULT_CALIBRATION
+) -> RenderPlan:
     """Map a knob vector to its layered RenderPlan (design §4)."""
     return RenderPlan(
-        grade=ColorGrade(tone=_mood_tone(coord.dark, coord.light)),
-        overlay=AnalyticalOverlay(intensity=_overlay_intensity(coord.left)),
-        restyle=Restyle(blend=_restyle_blend(coord.right)),
+        grade=ColorGrade(tone=_mood_tone(coord.dark, coord.light, calibration)),
+        overlay=AnalyticalOverlay(
+            level=coord.left,
+            intensity=_overlay_intensity(coord.left, calibration),
+        ),
+        restyle=Restyle(variant=_right_variant(coord.right, calibration)),
     )
+
+
+def render_plan_to_dict(plan: RenderPlan) -> dict:
+    """JSON-serializable form for the simulator API."""
+    return {
+        "grade": {"tone": plan.grade.tone},
+        "overlay": {"level": plan.overlay.level, "intensity": plan.overlay.intensity},
+        "restyle": {"variant": plan.restyle.variant},
+        "is_identity": plan.is_identity,
+    }