livepilot 1.27.2 → 1.27.3

package/mcp_server/mix_engine/critics.py

@@ -2,11 +2,36 @@
 
 Six critics: balance, masking, dynamics, stereo, depth, translation.
 All pure computation, zero I/O.
+
+Confidence values
+------------------
+Every issue's ``confidence`` is a BASE value (the original hand-tuned
+literal, preserved as the per-issue-type prior) MODULATED by a data-quality
+signal actually present in the state being examined — never a decorative
+flat constant. Three modulation shapes are used, each documented at its
+helper:
+
+  - ``_sample_size_confidence`` — more contributing tracks behind an
+    aggregate (e.g. the average volume `anchor_too_weak` compares against)
+    means the aggregate is more trustworthy.
+  - ``_measurement_confidence`` — real per-track spectral overlap
+    (``severity_basis == "spectral_overlap"``) earns a premium over a
+    role-pair heuristic prior (no per-track spectrum available).
+  - ``_margin_confidence`` / ``_band_interior_confidence`` — how far a
+    measurement sits from the classification boundary. Values right at an
+    edge are one measurement-noise-width from flipping to the neighboring
+    bucket, so they're discounted; values solidly inside the flagged
+    region earn the full base confidence.
+
+All modulated values are bounded to [0.3, 0.95] — even a single strong
+signal shouldn't claim near-certainty, and even a borderline call keeps a
+floor of honesty (it's still a real detection, just a weak one).
 """
 
 from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
+from typing import Optional
 
 from .models import (
     BalanceState,
@@ -18,6 +43,65 @@ from .models import (
 )
 
 
+_CONF_FLOOR = 0.3
+_CONF_CEIL = 0.95
+
+
+def _sample_size_confidence(n: int, base: float, full_n: int) -> float:
+    """Scale `base` by how many tracks contributed to the aggregate it rests on.
+
+    n=1 -> 70% of base (a lone track's "average" isn't a meaningful
+    baseline to compare against). n>=full_n -> 100% of base (a well-
+    supported average). Linear ramp in between.
+    """
+    frac = min(1.0, max(0, n - 1) / max(1, full_n - 1))
+    scaled = base * (0.7 + 0.3 * frac)
+    return round(max(_CONF_FLOOR, min(_CONF_CEIL, scaled)), 3)
+
+
+def _measurement_confidence(measured: bool, base: float) -> float:
+    """Scale `base` by whether the severity came from a real measurement.
+
+    measured=True  -> per-track spectral overlap was available (this
+                       session's actual tracks were compared) -> premium.
+    measured=False -> role-pair heuristic prior only (no per-track
+                       spectrum) -> discounted, it's a population prior,
+                       not a measurement of THIS mix.
+    """
+    modifier = 1.2 if measured else 0.8
+    return round(max(_CONF_FLOOR, min(_CONF_CEIL, base * modifier)), 3)
+
+
+def _margin_confidence(margin: float, full_margin: float, base: float) -> float:
+    """Scale `base` by how far past a decision boundary a measurement sits.
+
+    margin<=0 (right at the boundary) -> 70% of base — the critic could
+    flip on measurement noise alone, so confidence is discounted.
+    margin>=full_margin -> 100% of base — solidly inside the flagged
+    region.
+    """
+    frac = min(1.0, max(0.0, margin) / full_margin) if full_margin > 0 else 1.0
+    scaled = base * (0.7 + 0.3 * frac)
+    return round(max(_CONF_FLOOR, min(_CONF_CEIL, scaled)), 3)
+
+
+def _band_interior_confidence(value: float, low: float, high: float, base: float) -> float:
+    """Scale `base` by how centrally `value` sits within a two-sided band.
+
+    Values near either edge of [low, high] are one measurement-noise-width
+    from being classified into the neighboring bucket, so they're
+    discounted; values near the band's center get the full base value.
+    """
+    half_width = (high - low) / 2.0
+    if half_width <= 0:
+        return round(max(_CONF_FLOOR, min(_CONF_CEIL, base)), 3)
+    center = (high + low) / 2.0
+    distance_from_center = abs(value - center)
+    frac = 1.0 - min(1.0, distance_from_center / half_width)
+    scaled = base * (0.7 + 0.3 * frac)
+    return round(max(_CONF_FLOOR, min(_CONF_CEIL, scaled)), 3)
+
+
 # ── MixIssue ───────────────────────────────────────────────────────
 
 
@@ -51,6 +135,14 @@ def run_balance_critic(balance: BalanceState) -> list[MixIssue]:
     # Compute average volume of active tracks
     avg_vol = sum(t.volume for t in active) / len(active)
 
+    # Confidence scales with how many tracks fed the average being compared
+    # against — an average of 2 tracks is a much weaker baseline than an
+    # average of 8. full_n=6 is where the average is considered well-
+    # supported; below that it's discounted toward 70% of the base value.
+    n_active = len(active)
+    anchor_confidence = _sample_size_confidence(n_active, base=0.7, full_n=6)
+    support_confidence = _sample_size_confidence(n_active, base=0.6, full_n=6)
+
     # Check if anchor tracks are too quiet
     for t in active:
         if t.track_index in balance.anchor_tracks:
@@ -59,7 +151,7 @@ def run_balance_critic(balance: BalanceState) -> list[MixIssue]:
                     issue_type="anchor_too_weak",
                     critic="balance",
                     severity=min(1.0, (avg_vol - t.volume) / max(avg_vol, 0.01)),
-                    confidence=0.7,
+                    confidence=anchor_confidence,
                     affected_tracks=[t.track_index],
                     evidence=(
                         f"Anchor track '{t.name}' (role={t.role}) at volume "
@@ -76,7 +168,7 @@ def run_balance_critic(balance: BalanceState) -> list[MixIssue]:
                     issue_type="support_too_loud",
                     critic="balance",
                     severity=min(1.0, (t.volume - avg_vol) / max(avg_vol, 0.01)),
-                    confidence=0.6,
+                    confidence=support_confidence,
                     affected_tracks=[t.track_index],
                     evidence=(
                         f"Support track '{t.name}' (role={t.role}) at volume "
@@ -101,7 +193,7 @@ def run_masking_critic(masking: MaskingMap) -> list[MixIssue]:
                 issue_type="frequency_collision",
                 critic="masking",
                 severity=entry.severity,
-                confidence=0.6,
+                confidence=_measurement_confidence(entry.measured, base=0.6),
                 affected_tracks=[entry.track_a, entry.track_b],
                 evidence=(
                     f"Tracks {entry.track_a} and {entry.track_b} collide "
@@ -116,30 +208,64 @@ def run_masking_critic(masking: MaskingMap) -> list[MixIssue]:
 # ── Dynamics Critic ─────────────────────────────────────────────────
 
 
-def run_dynamics_critic(dynamics: DynamicsState) -> list[MixIssue]:
-    """Detect dynamics problems: over-compression, flat dynamics, low headroom."""
+def run_dynamics_critic(
+    dynamics: DynamicsState,
+    context: Optional[dict] = None,
+) -> list[MixIssue]:
+    """Detect dynamics problems: over-compression, flat dynamics, low headroom.
+
+    context: optional hint about the session's intended dynamics target.
+        {"target_style": "loud_master"} tells the critic this mix is
+        deliberately targeting a loud, heavily-limited master — a
+        legitimate style choice (not a defect) — so the `over_compressed`
+        check is suppressed rather than false-positiving on intentional
+        design. Omitting `context` (the default) preserves the original
+        behavior byte-for-byte EXCEPT the evidence string, which now
+        states the "assumes a dynamic mix target" assumption explicitly
+        so a reader doesn't over-trust the flag for a style that
+        intentionally lives in the 3-6dB crest band.
+    """
+    context = context or {}
+    target_style = context.get("target_style", "dynamic")
     issues: list[MixIssue] = []
 
     if dynamics.over_compressed:
-        issues.append(MixIssue(
-            issue_type="over_compressed",
-            critic="dynamics",
-            severity=min(1.0, max(0.0, (6.0 - dynamics.crest_factor_db) / 6.0)),
-            confidence=0.7,
-            affected_tracks=[],
-            evidence=(
-                f"Crest factor {dynamics.crest_factor_db:.1f} dB — "
-                f"dynamics are flat, likely over-compressed"
-            ),
-            recommended_moves=["bus_compression", "transient_shaping"],
-        ))
+        if target_style == "loud_master":
+            # Deliberately loud-master styles target exactly this crest
+            # band — that's the intended sound, not flat/over-compressed.
+            pass
+        else:
+            issues.append(MixIssue(
+                issue_type="over_compressed",
+                critic="dynamics",
+                severity=min(1.0, max(0.0, (6.0 - dynamics.crest_factor_db) / 6.0)),
+                # Confidence is highest at the center of the 3-6dB band and
+                # discounted near either edge, where a small measurement
+                # wobble could reclassify the mix as healthy or flat instead.
+                confidence=_band_interior_confidence(
+                    dynamics.crest_factor_db, 3.0, 6.0, base=0.7
+                ),
+                affected_tracks=[],
+                evidence=(
+                    f"Crest factor {dynamics.crest_factor_db:.1f} dB — dynamics "
+                    f"read as flat/over-compressed. Assumes a dynamic mix target; "
+                    f"loud-master styles may intentionally sit at 3-6dB crest — "
+                    f"pass context={{'target_style': 'loud_master'}} if that's the intent."
+                ),
+                recommended_moves=["bus_compression", "transient_shaping"],
+            ))
 
     elif dynamics.crest_factor_db < 3.0 and dynamics.crest_factor_db > 0:
         issues.append(MixIssue(
             issue_type="flat_dynamics",
             critic="dynamics",
             severity=0.8,
-            confidence=0.8,
+            # Confidence scales with how far below the 3.0dB threshold the
+            # crest factor sits — deep in flat territory (near 0dB) is a
+            # much more confident call than crest sitting just under 3.0.
+            confidence=_margin_confidence(
+                3.0 - dynamics.crest_factor_db, full_margin=3.0, base=0.8
+            ),
             affected_tracks=[],
             evidence=(
                 f"Crest factor {dynamics.crest_factor_db:.1f} dB — "
@@ -153,7 +279,12 @@ def run_dynamics_critic(dynamics: DynamicsState) -> list[MixIssue]:
             issue_type="low_headroom",
             critic="dynamics",
             severity=min(1.0, (1.0 - dynamics.headroom)),
-            confidence=0.9,
+            # Confidence scales with how far below the 1.0dB threshold
+            # headroom sits — near-zero headroom is an unambiguous clip
+            # risk, while headroom just under 1.0dB is a borderline call.
+            confidence=_margin_confidence(
+                1.0 - dynamics.headroom, full_margin=1.0, base=0.9
+            ),
             affected_tracks=[],
             evidence=f"Only {dynamics.headroom:.1f} dB headroom — clipping risk",
             recommended_moves=["gain_staging"],
@@ -170,11 +301,16 @@ def run_stereo_critic(stereo: StereoState) -> list[MixIssue]:
     issues: list[MixIssue] = []
 
     if stereo.mono_risk:
+        # mono_risk requires center_strength > 0.85 AND side_activity < 0.05;
+        # confidence scales with how far past BOTH thresholds the mix sits —
+        # a mix that's barely over 0.85/barely under 0.05 is a much weaker
+        # "essentially mono" call than one deep in that territory.
+        margin = (stereo.center_strength - 0.85) + (0.05 - stereo.side_activity)
         issues.append(MixIssue(
             issue_type="center_collapse",
             critic="stereo",
             severity=0.6,
-            confidence=0.7,
+            confidence=_margin_confidence(margin, full_margin=0.2, base=0.7),
             affected_tracks=[],
             evidence=(
                 f"Center strength {stereo.center_strength:.2f}, "
@@ -189,7 +325,9 @@ def run_stereo_critic(stereo: StereoState) -> list[MixIssue]:
             issue_type="overwide",
             critic="stereo",
             severity=min(1.0, stereo.side_activity - 0.5),
-            confidence=0.5,
+            confidence=_margin_confidence(
+                stereo.side_activity - 0.7, full_margin=0.3, base=0.5
+            ),
             affected_tracks=[],
             evidence=(
                 f"Side activity {stereo.side_activity:.2f} — "
@@ -213,7 +351,9 @@ def run_depth_critic(depth: DepthState) -> list[MixIssue]:
             issue_type="no_depth_separation",
             critic="depth",
             severity=0.5,
-            confidence=0.5,
+            confidence=_margin_confidence(
+                0.05 - depth.depth_separation, full_margin=0.05, base=0.5
+            ),
             affected_tracks=[],
             evidence=(
                 f"Depth separation {depth.depth_separation:.3f} — "
@@ -227,7 +367,9 @@ def run_depth_critic(depth: DepthState) -> list[MixIssue]:
             issue_type="excessive_wash",
             critic="depth",
             severity=min(1.0, depth.wet_dry_ratio),
-            confidence=0.6,
+            confidence=_margin_confidence(
+                depth.wet_dry_ratio - 0.6, full_margin=0.4, base=0.6
+            ),
             affected_tracks=[],
             evidence=(
                 f"Wet/dry ratio {depth.wet_dry_ratio:.2f} — "
@@ -249,13 +391,17 @@ def run_translation_critic(
     """Detect translation risks: mono weakness, harshness risk."""
     issues: list[MixIssue] = []
 
-    # Mono weakness: wide mix with weak center
+    # Mono weakness: wide mix with weak center. Confidence scales with how
+    # far past BOTH thresholds (side_activity > 0.5, center_strength < 0.3)
+    # the mix sits — deep in that territory is a much stronger call than
+    # barely past either edge.
     if stereo.side_activity > 0.5 and stereo.center_strength < 0.3:
+        margin = (stereo.side_activity - 0.5) + (0.3 - stereo.center_strength)
         issues.append(MixIssue(
             issue_type="mono_weakness",
             critic="translation",
             severity=0.7,
-            confidence=0.6,
+            confidence=_margin_confidence(margin, full_margin=0.4, base=0.6),
             affected_tracks=[],
             evidence=(
                 f"Side activity {stereo.side_activity:.2f} with center "
@@ -265,13 +411,16 @@ def run_translation_critic(
             recommended_moves=["width_adjustment", "gain_staging"],
         ))
 
-    # Harshness risk: over-compressed + low headroom
+    # Harshness risk: over-compressed + low headroom. Confidence scales with
+    # how far below the 3.0dB headroom threshold the mix sits.
     if dynamics.over_compressed and dynamics.headroom is not None and dynamics.headroom < 3.0:
         issues.append(MixIssue(
             issue_type="harshness_risk",
             critic="translation",
             severity=0.6,
-            confidence=0.5,
+            confidence=_margin_confidence(
+                3.0 - dynamics.headroom, full_margin=3.0, base=0.5
+            ),
             affected_tracks=[],
             evidence=(
                 f"Over-compressed (crest {dynamics.crest_factor_db:.1f} dB) "
@@ -287,12 +436,20 @@ def run_translation_critic(
 # ── Run all critics ─────────────────────────────────────────────────
 
 
-def run_all_mix_critics(mix_state: MixState) -> list[MixIssue]:
-    """Run all six critics and aggregate issues."""
+def run_all_mix_critics(
+    mix_state: MixState,
+    dynamics_context: Optional[dict] = None,
+) -> list[MixIssue]:
+    """Run all six critics and aggregate issues.
+
+    dynamics_context: optional hint forwarded to run_dynamics_critic (see
+        its docstring) — e.g. {"target_style": "loud_master"}. Omitting it
+        (the default) preserves existing behavior for every current caller.
+    """
     issues: list[MixIssue] = []
     issues.extend(run_balance_critic(mix_state.balance))
     issues.extend(run_masking_critic(mix_state.masking))
-    issues.extend(run_dynamics_critic(mix_state.dynamics))
+    issues.extend(run_dynamics_critic(mix_state.dynamics, dynamics_context))
     issues.extend(run_stereo_critic(mix_state.stereo))
     issues.extend(run_depth_critic(mix_state.depth))
     issues.extend(run_translation_critic(mix_state.dynamics, mix_state.stereo))

package/mcp_server/mix_engine/models.py

@@ -59,12 +59,32 @@ class BalanceState:
 
 @dataclass
 class MaskingEntry:
-    """A single frequency masking collision between two tracks."""
+    """A single frequency masking collision between two tracks.
+
+    Fields
+    ------
+    track_a, track_b : int
+        Track indices of the colliding pair.
+    overlap_band : str
+        Frequency band where the collision is strongest (e.g. "sub", "low").
+    severity : float
+        0–1 collision severity.  When ``measured`` is True this reflects
+        actual per-track band energy overlap; when False it is a role-pair
+        heuristic constant from the collision-rule table.
+    measured : bool
+        True  → severity was scaled by real per-track spectral data.
+        False → severity is a role-prior heuristic (no per-track spectrum).
+    severity_basis : str
+        Human-readable label for the severity origin.
+        Either "spectral_overlap" (measured) or "role_heuristic" (heuristic).
+    """
 
     track_a: int = 0
     track_b: int = 0
     overlap_band: str = ""
     severity: float = 0.0
+    measured: bool = False
+    severity_basis: str = "role_heuristic"
 
     def to_dict(self) -> dict:
         return asdict(self)

package/mcp_server/mix_engine/state_builder.py

@@ -155,18 +155,73 @@ def build_balance_state(
 # ── Masking ─────────────────────────────────────────────────────────
 
 
+def _extract_per_track_bands(spectrum: dict) -> dict[int, dict[str, float]]:
+    """Extract per-track band-energy dicts from a spectrum payload.
+
+    Supports two shapes:
+    - Per-track:  {"tracks": {"0": {"sub": 0.8, "low": 0.6, ...}, ...}}
+    - Master-only: {"bands": {...}} — no per-track data, returns empty dict.
+
+    Returns {track_index: {band_lower: energy_float, ...}}.
+    Band keys are lowercased so callers can use the collision-rule vocabulary
+    ("sub", "low", "low_mid", "mid", "high_mid", "presence", "high") directly.
+    """
+    raw_tracks = spectrum.get("tracks")
+    if not raw_tracks or not isinstance(raw_tracks, dict):
+        return {}
+    result: dict[int, dict[str, float]] = {}
+    for key, bands in raw_tracks.items():
+        try:
+            idx = int(key)
+        except (ValueError, TypeError):
+            continue
+        if isinstance(bands, dict):
+            result[idx] = {k.lower(): float(v) for k, v in bands.items()}
+    return result
+
+
+def _overlap_score(bands_a: dict[str, float], bands_b: dict[str, float], band: str) -> float:
+    """Compute normalised spectral overlap for a single band.
+
+    Uses the geometric mean of the two tracks' energy in that band so that
+    the score is high only when BOTH tracks are active there.  Returns a
+    value in [0, 1] (or 0.0 when the band is absent from either track).
+    """
+    ea = bands_a.get(band, 0.0)
+    eb = bands_b.get(band, 0.0)
+    return math.sqrt(max(ea, 0.0) * max(eb, 0.0))
+
+
 def build_masking_map(
     spectrum: Optional[dict],
     track_roles: Optional[dict[int, str]] = None,
 ) -> MaskingMap:
     """Build MaskingMap from spectrum data.
 
-    Uses per-track spectrum bands if available, otherwise returns empty.
-    Spectrum shape: {"tracks": {track_idx_str: {band: value, ...}, ...}}
-    or flat {"bands": {band: value}} for master-only.
-
-    For Phase 1 we detect masking heuristically from role collisions
-    in known problem bands (kick/bass in sub/low, bass/chords in low_mid).
+    Spectrum shapes accepted
+    ------------------------
+    Per-track (preferred):
+        {"tracks": {"0": {"sub": 0.8, "low": 0.6, ...}, "1": {...}, ...}}
+    Master-only (fallback):
+        {"bands": {"sub": 0.9, ...}}
+
+    Severity calculation (hybrid)
+    -----------------------------
+    When per-track band energy IS available for both members of a colliding
+    pair, ``severity`` is scaled by the geometric-mean overlap in the
+    colliding band:
+
+        severity = base_severity * overlap_score(band_a, band_b, band)
+
+    This means two tracks that are perfectly EQ-separated in that band
+    (one of them has ~0 energy there) produce a near-zero severity, while
+    tracks that are both loud in the same band produce a severity close to
+    the role-prior constant.
+
+    When per-track data is absent (master-bus spectrum only), the original
+    role-prior constant is kept unchanged.  Each entry is labelled with
+    ``measured=True/False`` and ``severity_basis`` so downstream consumers
+    can distinguish real measurements from heuristics.
     """
     entries: list[MaskingEntry] = []
     track_roles = track_roles or {}
@@ -174,12 +229,18 @@ def build_masking_map(
     if not spectrum or not track_roles:
         return MaskingMap(entries=[], worst_pair=None)
 
+    # Extract per-track bands if available (empty dict = master-bus only)
+    per_track_bands = _extract_per_track_bands(spectrum)
+
     # Build role->indices mapping
     role_to_indices: dict[str, list[int]] = {}
     for idx, role in track_roles.items():
         role_to_indices.setdefault(_masking_role(role), []).append(idx)
 
-    # Known problematic role pairs and their collision bands
+    # Known problematic role pairs and their collision bands.
+    # Each tuple: (role_a, role_b, band, base_severity)
+    # base_severity is the heuristic prior; it may be scaled by spectral
+    # overlap when per-track data is present.
     collision_rules: list[tuple[str, str, str, float]] = [
         ("kick", "bass", "sub", 0.7),
         ("kick", "bass", "low", 0.6),
@@ -197,11 +258,29 @@ def build_masking_map(
         for ia in indices_a:
             for ib in indices_b:
                 if ia != ib:
+                    bands_a = per_track_bands.get(ia)
+                    bands_b = per_track_bands.get(ib)
+
+                    if bands_a is not None and bands_b is not None:
+                        # Scale the role-prior by actual spectral overlap.
+                        overlap = _overlap_score(bands_a, bands_b, band)
+                        severity = base_severity * overlap
+                        measured = True
+                        severity_basis = "spectral_overlap"
+                    else:
+                        # No per-track data — keep the role-prior constant and
+                        # label it so callers know it is not a measurement.
+                        severity = base_severity
+                        measured = False
+                        severity_basis = "role_heuristic"
+
                     entries.append(MaskingEntry(
                         track_a=ia,
                         track_b=ib,
                         overlap_band=band,
-                        severity=base_severity,
+                        severity=severity,
+                        measured=measured,
+                        severity_basis=severity_basis,
                     ))
 
     worst = None

package/mcp_server/mix_engine/tools.py

@@ -84,11 +84,17 @@ def _fetch_mix_data(ctx: Context) -> dict:
 
 
 @mcp.tool()
-def analyze_mix(ctx: Context) -> dict:
+def analyze_mix(ctx: Context, target_style: str = "dynamic") -> dict:
     """Build full mix state and run all critics.
 
     Returns the complete mix analysis including all sub-states
     (balance, masking, dynamics, stereo, depth) and all detected issues.
+
+    target_style: intended dynamics target for the dynamics critic.
+        "dynamic" (default) — standard mix expectations.
+        "loud_master" — deliberately loud, heavily-limited master: the
+        over_compressed check is suppressed (3-6dB crest is the intended
+        sound there, not a defect).
     """
     data = _fetch_mix_data(ctx)
     mix_state = build_mix_state(
@@ -97,7 +103,9 @@ def analyze_mix(ctx: Context) -> dict:
         spectrum=data["spectrum"],
         rms_data=data["rms_data"],
     )
-    issues = run_all_mix_critics(mix_state)
+    issues = run_all_mix_critics(
+        mix_state, dynamics_context={"target_style": target_style}
+    )
     moves = plan_mix_moves(issues, mix_state)
     sonic_snapshot = normalize_sonic_snapshot(data["spectrum"], source="mix_engine")
     sonic_character = extract_character_profile(sonic_snapshot or {})
@@ -113,10 +121,12 @@ def analyze_mix(ctx: Context) -> dict:
 
 
 @mcp.tool()
-def get_mix_issues(ctx: Context) -> dict:
+def get_mix_issues(ctx: Context, target_style: str = "dynamic") -> dict:
     """Run all mix critics and return detected issues only.
 
     Lighter than analyze_mix — skips move planning.
+
+    target_style: "dynamic" (default) or "loud_master" — see analyze_mix.
     """
     data = _fetch_mix_data(ctx)
     mix_state = build_mix_state(
@@ -125,7 +135,9 @@ def get_mix_issues(ctx: Context) -> dict:
         spectrum=data["spectrum"],
         rms_data=data["rms_data"],
     )
-    issues = run_all_mix_critics(mix_state)
+    issues = run_all_mix_critics(
+        mix_state, dynamics_context={"target_style": target_style}
+    )
     sonic_snapshot = normalize_sonic_snapshot(data["spectrum"], source="mix_engine")
 
     return {

package/mcp_server/performance_engine/tools.py

@@ -40,6 +40,39 @@ _POSITIONAL_FALLBACK_ROLES = {
     "default": "verse",
 }
 
+# _composition_engine's SectionType vocabulary is RICHER than the performance
+# VALID_ROLES set (it adds loop / pre_chorus / bridge / unknown / transition_fx).
+# Feeding one of those straight into SceneRole(role=...) trips its __post_init__
+# guard and raises ValueError, which crashes get_performance_state /
+# get_performance_safe_moves / plan_scene_handoff the moment ANY scene resolves
+# to an out-of-vocabulary type (e.g. a scene named "Drums"/"My Idea" → unknown).
+# Map every composition type into the performance vocabulary by musical role.
+_SECTION_TYPE_TO_PERF_ROLE = {
+    "intro": "intro",
+    "verse": "verse",
+    "chorus": "chorus",
+    "build": "build",
+    "drop": "drop",
+    "breakdown": "breakdown",
+    "outro": "outro",
+    "transition": "transition",
+    "transition_fx": "transition",
+    "pre_chorus": "build",     # a pre-chorus builds toward the chorus
+    "bridge": "breakdown",     # a bridge is a contrasting, lower-energy section
+    "loop": "verse",           # a bare loop / idea reads as a steady verse
+    "unknown": "verse",        # neutral default
+}
+
+
+def _to_performance_role(value: str) -> str:
+    """Coerce any composition SectionType value into the performance vocabulary.
+
+    Falls back to 'verse' for any value not in the map so a future SectionType
+    can never crash the performance tools.
+    """
+    role = _SECTION_TYPE_TO_PERF_ROLE.get(value)
+    return role if role is not None else "verse"
+
 
 def _positional_fallback_role(index: int, scene_count: int) -> str:
     """Map a scene index to a role when no composition data is available.
@@ -148,21 +181,36 @@ def _fetch_scene_data(ctx: Context) -> tuple[list[SceneRole], int]:
         name = scene_data.get("name", f"Scene {i}")
         ce_sec = ce_by_scene_idx.get(i)
         if ce_sec is not None:
-            # SectionType is an enum; .value gives the string vocabulary
+            # SectionType is an enum; .value gives the string vocabulary, which
+            # we then coerce into the (narrower) performance VALID_ROLES set.
             stype = ce_sec.section_type
-            role = stype.value if hasattr(stype, "value") else str(stype)
+            raw = stype.value if hasattr(stype, "value") else str(stype)
+            role = _to_performance_role(raw)
             energy = float(ce_sec.energy)
         else:
             # Unnamed scene or build failed — positional fallback
             role = _positional_fallback_role(i, scene_count)
             energy = _positional_fallback_energy(role)
 
-        scene_roles.append(SceneRole(
-            scene_index=i,
-            name=name,
-            energy_level=energy,
-            role=role,
-        ))
+        # Clamp energy and defensively construct: SceneRole.__post_init__ raises
+        # on an out-of-range energy or an unmapped role, and a single raise here
+        # would take down the whole tool. A bad value degrades to a safe scene.
+        energy = max(0.0, min(1.0, energy))
+        try:
+            scene_roles.append(SceneRole(
+                scene_index=i,
+                name=name,
+                energy_level=energy,
+                role=role,
+            ))
+        except ValueError as exc:
+            logger.debug("_fetch_scene_data SceneRole(%r) invalid: %s", role, exc)
+            scene_roles.append(SceneRole(
+                scene_index=i,
+                name=name,
+                energy_level=energy,
+                role="verse",
+            ))
 
     # Determine current scene — default to 0 since session_info
     # doesn't expose a selected_scene field

package/mcp_server/persistence/base_store.py

@@ -70,6 +70,17 @@ class PersistentJsonStore:
         try:
             return json.loads(self._path.read_text(encoding="utf-8"))
         except (json.JSONDecodeError, OSError):
+            # Mirror the read() corruption-recovery path: preserve the
+            # corrupt file as <name>.corrupt so it can be inspected/recovered
+            # rather than being silently overwritten by the next _write_unlocked
+            # call (which update() always performs after _read_unlocked).
+            # Best-effort — a backup failure must not prevent the store from
+            # recovering with defaults.
+            corrupt = self._path.with_suffix(self._path.suffix + ".corrupt")
+            try:
+                self._path.rename(corrupt)
+            except OSError:
+                pass
             return {}
 
     def _write_unlocked(self, data: dict) -> None: