livepilot 1.27.1 → 1.27.3

package/mcp_server/memory/tools.py

@@ -6,6 +6,8 @@
 
 from __future__ import annotations
 
+import logging
+
 from fastmcp import Context
 
 from ..server import mcp
@@ -14,12 +16,29 @@ from .promotion import batch_evaluate_promotions
 from .session_memory import SessionMemoryStore
 from .taste_memory import TasteMemoryStore
 
+logger = logging.getLogger(__name__)
+
 
 def _get_anti_memory(ctx: Context) -> AntiMemoryStore:
     """Get or create the session-scoped AntiMemoryStore."""
     return ctx.lifespan_context.setdefault("anti_memory", AntiMemoryStore())
 
 
+def _get_persistent_taste_store(ctx: Context):
+    """Return the persistent taste store from the live server context, or None.
+
+    Only the live server lifespan injects "persistent_taste" (the same key the
+    wonder/runtime/preview_studio tools use, so all share ONE instance); tests
+    build their own context without it, so taste tools stay session-only
+    (hermetic) there. When present, taste write-backs and reads persist across
+    restarts (P2-29).
+    """
+    try:
+        return ctx.lifespan_context.get("persistent_taste")
+    except AttributeError:
+        return None
+
+
 def _get_session_memory(ctx: Context) -> SessionMemoryStore:
     """Get or create the session-scoped SessionMemoryStore."""
     return ctx.lifespan_context.setdefault("session_memory", SessionMemoryStore())
@@ -43,12 +62,25 @@ def record_anti_preference(
 ) -> dict:
     """Record a user dislike for a dimension+direction. direction must be 'increase' or 'decrease'."""
     if direction not in ("increase", "decrease"):
-        return {"error": "direction must be 'increase' or 'decrease'"}
+        return {"error": "direction must be 'increase' or 'decrease'",
+                "code": "INVALID_PARAM"}
     store = _get_anti_memory(ctx)
     pref = store.record_dislike(dimension, direction)
+    # P2-29: persist to the taste store so the anti-preference survives a
+    # server restart (best-effort — the session store above is authoritative
+    # for the in-session response).
+    persistent = _get_persistent_taste_store(ctx)
+    persisted = False
+    if persistent is not None:
+        try:
+            persistent.record_anti_preference(dimension, direction)
+            persisted = True
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("persist anti_preference failed: %s", exc)
     return {
         "recorded": pref.to_dict(),
         "should_caution": store.should_caution(dimension, direction),
+        "persisted": persisted,
     }
 
 
@@ -143,7 +175,10 @@ def get_taste_graph(ctx: Context) -> dict:
 
     taste_store = _get_taste_memory(ctx)
     anti_store = _get_anti_memory(ctx)
-    graph = build_taste_graph(taste_store=taste_store, anti_store=anti_store)
+    graph = build_taste_graph(
+        taste_store=taste_store, anti_store=anti_store,
+        persistent_store=_get_persistent_taste_store(ctx),
+    )
     return graph.to_dict()
 
 
@@ -158,7 +193,10 @@ def explain_taste_inference(ctx: Context) -> dict:
 
     taste_store = _get_taste_memory(ctx)
     anti_store = _get_anti_memory(ctx)
-    graph = build_taste_graph(taste_store=taste_store, anti_store=anti_store)
+    graph = build_taste_graph(
+        taste_store=taste_store, anti_store=anti_store,
+        persistent_store=_get_persistent_taste_store(ctx),
+    )
     return graph.explain()
 
 
@@ -178,7 +216,10 @@ def rank_moves_by_taste(
 
     taste_store = _get_taste_memory(ctx)
     anti_store = _get_anti_memory(ctx)
-    graph = build_taste_graph(taste_store=taste_store, anti_store=anti_store)
+    graph = build_taste_graph(
+        taste_store=taste_store, anti_store=anti_store,
+        persistent_store=_get_persistent_taste_store(ctx),
+    )
 
     if isinstance(move_specs, str):
         import json
@@ -218,10 +259,27 @@ def record_positive_preference(
             matching_signals.append(sig_name)
     if matching_signals:
         taste_store.update_from_outcome({"signals": matching_signals})
+    # P2-29 (dimension-weight half): persist the updated dimension weight so it
+    # survives a server restart — symmetric with record_anti_preference. Without
+    # this the persisted dimension_weights hydration branch in build_taste_graph
+    # stayed dead (no production writer). Best-effort; session store is
+    # authoritative for the in-session response.
+    persisted = False
+    persistent = _get_persistent_taste_store(ctx)
+    if persistent is not None and matching_signals:
+        try:
+            for dim in taste_store.get_taste_dimensions():
+                if dim.name == dimension and dim.evidence_count > 0:
+                    persistent.record_dimension_weight(dimension, dim.value)
+                    persisted = True
+                    break
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("persist dimension_weight failed: %s", exc)
     return {
         "recorded": bool(matching_signals),
         "dimension": dimension,
         "direction": direction,
         "signals_matched": matching_signals,
         "evidence": evidence,
+        "persisted": persisted,
     }

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