livepilot 1.23.6 → 1.24.0

package/mcp_server/composer/layer_planner.py

@@ -1,467 +1,21 @@
-"""Layer planner — convert CompositionIntent into LayerSpec list.
+"""Backward-compat shim — layer_planner has moved to full/layer_planner.py.
 
-Pure computation. Determines which layers to create, what to search for,
-which techniques to use, and how to arrange sections. No I/O.
+Existing code that imports from ``mcp_server.composer.layer_planner`` continues
+to work unchanged. New code should import from
+``mcp_server.composer.full.layer_planner`` directly.
 """
-
-from __future__ import annotations
-
-import math
-from dataclasses import dataclass, field
-from typing import Optional
-
-from .prompt_parser import CompositionIntent
-
-
-# ── Data Model ─────────────────────────────────────────────────────
-
-@dataclass
-class LayerSpec:
-    """Specification for a single layer in a composition."""
-
-    role: str                        # "drums", "bass", "lead", "pad", "texture", "vocal", "percussion", "fx"
-    search_query: str                # Splice search query
-    splice_filters: dict = field(default_factory=dict)  # key, bpm_range, genre, tags, sample_type
-    technique_id: str = ""           # from the 29-technique library
-    processing: list[dict] = field(default_factory=list)  # devices to add + param targets
-    volume_db: float = 0.0           # mix level
-    pan: float = 0.0                 # -1.0 to 1.0
-    sections: list[str] = field(default_factory=list)  # which arrangement sections
-    priority: int = 5                # download order (1=first, 10=last)
-
-    def to_dict(self) -> dict:
-        return {
-            "role": self.role,
-            "search_query": self.search_query,
-            "splice_filters": self.splice_filters,
-            "technique_id": self.technique_id,
-            "processing": self.processing,
-            "volume_db": self.volume_db,
-            "pan": self.pan,
-            "sections": self.sections,
-            "priority": self.priority,
-        }
-
-
-# ── Role Templates ─────────────────────────────────────────────────
-# role → default config used to build LayerSpec
-
-_ROLE_TEMPLATES: dict[str, dict] = {
-    "drums": {
-        "query_template": "{genre} drums {tempo}bpm",
-        "sample_type": "loop",
-        "technique_id": "slice_and_sequence",
-        "processing": [
-            {"name": "EQ Eight", "params": {"1 Filter Type A": "highpass", "1 Frequency A": 30.0}},
-            {"name": "Compressor", "params": {"Threshold": -12.0, "Ratio": 4.0}},
-        ],
-        "volume_db": -3.0,
-        "pan": 0.0,
-        "priority": 1,
-    },
-    "bass": {
-        "query_template": "{genre} bass {key} oneshot",
-        "sample_type": "oneshot",
-        "technique_id": "key_matched_layer",
-        "processing": [
-            {"name": "Saturator", "params": {"Drive": 6.0}},
-            {"name": "EQ Eight", "params": {"1 Filter Type A": "highpass", "1 Frequency A": 30.0}},
-        ],
-        "volume_db": -5.0,
-        "pan": 0.0,
-        "priority": 2,
-    },
-    "lead": {
-        "query_template": "{genre} {mood} melody {key}",
-        "sample_type": "loop",
-        "technique_id": "counterpoint_from_chops",
-        "processing": [
-            {"name": "Auto Filter", "params": {"Frequency": 2000.0, "Resonance": 0.3}},
-            {"name": "Delay", "params": {"Feedback": 0.35}},
-        ],
-        "volume_db": -6.0,
-        "pan": 0.0,
-        "priority": 4,
-    },
-    "pad": {
-        "query_template": "{mood} pad {key}",
-        "sample_type": "loop",
-        "technique_id": "extreme_stretch",
-        "processing": [
-            {"name": "Reverb", "params": {"Decay Time": 4.0, "Dry/Wet": 0.6}},
-            {"name": "Chorus-Ensemble", "params": {"Rate 1": 0.5}},
-        ],
-        "volume_db": -10.0,
-        "pan": 0.0,
-        "priority": 5,
-    },
-    "texture": {
-        "query_template": "{mood} texture ambient",
-        "sample_type": "loop",
-        "technique_id": "granular_scatter",
-        "processing": [
-            {"name": "Grain Delay", "params": {"Frequency": 1000.0, "Dry/Wet": 0.5}},
-            {"name": "Reverb", "params": {"Decay Time": 6.0, "Dry/Wet": 0.7}},
-        ],
-        "volume_db": -15.0,
-        "pan": 0.0,
-        "priority": 6,
-    },
-    "vocal": {
-        "query_template": "vocal {mood} {key}",
-        "sample_type": "loop",
-        "technique_id": "vocal_chop_rhythm",
-        "processing": [
-            {"name": "Auto Filter", "params": {"Frequency": 3000.0}},
-            {"name": "Reverb", "params": {"Decay Time": 2.5, "Dry/Wet": 0.4}},
-        ],
-        "volume_db": -8.0,
-        "pan": 0.0,
-        "priority": 7,
-    },
-    "percussion": {
-        "query_template": "{genre} percussion loop",
-        "sample_type": "loop",
-        "technique_id": "ghost_note_texture",
-        "processing": [
-            {"name": "EQ Eight", "params": {"1 Filter Type A": "highpass", "1 Frequency A": 200.0}},
-            {"name": "Compressor", "params": {"Threshold": -15.0, "Ratio": 3.0}},
-        ],
-        "volume_db": -12.0,
-        "pan": 0.0,
-        "priority": 3,
-    },
-    "fx": {
-        "query_template": "{genre} riser fx",
-        "sample_type": "oneshot",
-        "technique_id": "one_sample_challenge",
-        "processing": [],
-        "volume_db": -6.0,
-        "pan": 0.0,
-        "priority": 8,
-    },
-}
-
-
-# ── Role Selection per Genre + Energy ──────────────────────────────
-# Define which roles appear at different energy levels per genre.
-
-_GENRE_ROLE_PRIORITY: dict[str, list[str]] = {
-    # Roles listed in order of priority (first added, last dropped)
-    "techno": ["drums", "bass", "percussion", "lead", "texture", "vocal", "fx"],
-    "house": ["drums", "bass", "lead", "pad", "vocal", "texture"],
-    "hip hop": ["drums", "bass", "lead", "vocal", "texture", "fx"],
-    "ambient": ["pad", "texture", "vocal", "lead", "percussion"],
-    "drum and bass": ["drums", "bass", "lead", "percussion", "texture", "vocal", "fx"],
-    "trap": ["drums", "bass", "lead", "vocal", "fx", "texture"],
-    "lo-fi": ["drums", "bass", "pad", "texture", "vocal"],
-}
-
-_DEFAULT_ROLE_PRIORITY = ["drums", "bass", "lead", "pad", "texture", "vocal", "percussion", "fx"]
-
-
-# ── Section Templates ──────────────────────────────────────────────
-# Each section: name, bar count, which roles play (with optional volume offset)
-
-SECTION_TEMPLATES: dict[str, list[dict]] = {
-    "techno": [
-        {"name": "Intro",     "bars": 8,  "layers": ["drums:-6dB", "texture"]},
-        {"name": "Build",     "bars": 8,  "layers": ["drums", "bass", "percussion"]},
-        {"name": "Drop",      "bars": 16, "layers": ["drums", "bass", "lead", "percussion", "texture"]},
-        {"name": "Breakdown", "bars": 8,  "layers": ["texture", "vocal", "pad"]},
-        {"name": "Drop 2",   "bars": 16, "layers": ["drums", "bass", "lead", "percussion", "vocal", "texture"]},
-        {"name": "Outro",     "bars": 8,  "layers": ["drums:-6dB", "texture", "pad"]},
-    ],
-    # Dub techno — continuous-evolution aesthetic. No Drop structure, no
-    # Build/Break cycle. Section names reflect dub-techno arrangement idioms:
-    # slow reveal, subtraction before addition, return deeper not louder.
-    # Source: concepts/artists/basic-channel.yaml arrangement_idioms +
-    # live-verification finding from v1.18.0 CHANGELOG #2. v1.18.1 #2 fix.
-    "dub techno": [
-        {"name": "Dawn",      "bars": 16, "layers": ["texture:-12dB"]},
-        {"name": "Pulse",     "bars": 16, "layers": ["drums:-6dB", "texture"]},
-        {"name": "Chord",     "bars": 32, "layers": ["drums", "bass", "pad:-6dB", "texture"]},
-        {"name": "Depth",     "bars": 32, "layers": ["drums", "bass", "pad", "texture"]},
-        {"name": "Withdraw",  "bars": 16, "layers": ["pad:-6dB", "texture:-6dB"]},
-        {"name": "Return",    "bars": 16, "layers": ["texture:-12dB"]},
-    ],
-    "house": [
-        {"name": "Intro",     "bars": 8,  "layers": ["drums:-6dB", "pad"]},
-        {"name": "Verse",     "bars": 16, "layers": ["drums", "bass", "pad"]},
-        {"name": "Drop",      "bars": 16, "layers": ["drums", "bass", "lead", "vocal"]},
-        {"name": "Breakdown", "bars": 8,  "layers": ["pad", "texture", "vocal"]},
-        {"name": "Drop 2",   "bars": 16, "layers": ["drums", "bass", "lead", "vocal", "texture"]},
-        {"name": "Outro",     "bars": 8,  "layers": ["drums:-6dB", "pad"]},
-    ],
-    "hip hop": [
-        {"name": "Intro",  "bars": 4,  "layers": ["texture"]},
-        {"name": "Verse",  "bars": 16, "layers": ["drums", "bass", "texture"]},
-        {"name": "Hook",   "bars": 8,  "layers": ["drums", "bass", "lead", "vocal"]},
-        {"name": "Verse 2", "bars": 16, "layers": ["drums", "bass", "percussion", "texture"]},
-        {"name": "Hook 2", "bars": 8,  "layers": ["drums", "bass", "lead", "vocal", "fx"]},
-        {"name": "Outro",  "bars": 4,  "layers": ["texture", "vocal:-10dB"]},
-    ],
-    "ambient": [
-        {"name": "Opening",   "bars": 16, "layers": ["pad", "texture"]},
-        {"name": "Evolve",    "bars": 16, "layers": ["pad", "texture", "vocal"]},
-        {"name": "Peak",      "bars": 16, "layers": ["pad", "texture", "vocal", "lead"]},
-        {"name": "Dissolve",  "bars": 16, "layers": ["pad", "texture"]},
-    ],
-    "drum and bass": [
-        {"name": "Intro",     "bars": 8,  "layers": ["texture", "percussion:-6dB"]},
-        {"name": "Build",     "bars": 8,  "layers": ["drums:-6dB", "bass", "percussion"]},
-        {"name": "Drop",      "bars": 16, "layers": ["drums", "bass", "lead", "percussion", "texture"]},
-        {"name": "Breakdown", "bars": 8,  "layers": ["texture", "vocal", "pad"]},
-        {"name": "Drop 2",   "bars": 16, "layers": ["drums", "bass", "lead", "percussion", "vocal", "fx"]},
-        {"name": "Outro",     "bars": 8,  "layers": ["drums:-6dB", "texture"]},
-    ],
-    "trap": [
-        {"name": "Intro",   "bars": 4,  "layers": ["texture"]},
-        {"name": "Verse",   "bars": 16, "layers": ["drums", "bass", "texture"]},
-        {"name": "Drop",    "bars": 8,  "layers": ["drums", "bass", "lead", "vocal", "fx"]},
-        {"name": "Verse 2", "bars": 16, "layers": ["drums", "bass", "texture", "vocal"]},
-        {"name": "Drop 2",  "bars": 8,  "layers": ["drums", "bass", "lead", "vocal", "fx"]},
-        {"name": "Outro",   "bars": 4,  "layers": ["texture:-6dB"]},
-    ],
-    "lo-fi": [
-        {"name": "Intro",   "bars": 4,  "layers": ["texture", "pad"]},
-        {"name": "A",       "bars": 16, "layers": ["drums", "bass", "pad", "texture"]},
-        {"name": "B",       "bars": 16, "layers": ["drums", "bass", "pad", "vocal"]},
-        {"name": "A2",      "bars": 16, "layers": ["drums", "bass", "pad", "texture"]},
-        {"name": "Outro",   "bars": 8,  "layers": ["pad", "texture"]},
-    ],
-}
-
-# Fallback template for unknown genres
-_DEFAULT_SECTION_TEMPLATE: list[dict] = [
-    {"name": "Intro",     "bars": 8,  "layers": ["texture"]},
-    {"name": "Build",     "bars": 8,  "layers": ["drums", "bass"]},
-    {"name": "Main",      "bars": 16, "layers": ["drums", "bass", "lead", "texture"]},
-    {"name": "Breakdown", "bars": 8,  "layers": ["pad", "texture"]},
-    {"name": "Main 2",   "bars": 16, "layers": ["drums", "bass", "lead", "vocal", "texture"]},
-    {"name": "Outro",     "bars": 8,  "layers": ["drums:-6dB", "texture"]},
-]
-
-
-# ── Planner Functions ──────────────────────────────────────────────
-
-def _build_search_query(template: str, intent: CompositionIntent) -> str:
-    """Fill a query template with intent fields."""
-    return template.format(
-        genre=intent.genre or "electronic",
-        mood=intent.mood or "",
-        key=intent.key or "",
-        tempo=intent.tempo or 120,
-    ).strip()
-
-
-def _build_splice_filters(
-    intent: CompositionIntent,
-    sample_type: str,
-) -> dict:
-    """Build Splice filter dict from intent."""
-    filters: dict = {}
-
-    # Key → Splice format (lowercase root, separate chord_type)
-    if intent.key:
-        key = intent.key
-        if key.endswith("m") and len(key) >= 2:
-            root = key[:-1].lower()
-            filters["chord_type"] = "minor"
-        else:
-            root = key.lower()
-            filters["chord_type"] = "major"
-        filters["key"] = root
-
-    # BPM range (+-5)
-    if intent.tempo:
-        filters["bpm_min"] = max(1, intent.tempo - 5)
-        filters["bpm_max"] = intent.tempo + 5
-
-    if intent.genre:
-        filters["genre"] = intent.genre
-
-    if sample_type:
-        filters["sample_type"] = sample_type
-
-    return filters
-
-
-def _select_roles(intent: CompositionIntent) -> list[str]:
-    """Select which roles to include based on genre, energy, and explicit elements."""
-    role_priority = _GENRE_ROLE_PRIORITY.get(intent.genre, _DEFAULT_ROLE_PRIORITY)
-
-    # How many layers to pick
-    count = intent.layer_count or 5
-
-    # Start with the top N roles by priority
-    roles = list(role_priority[:count])
-
-    # Add any explicitly requested elements as roles
-    element_to_role = {
-        "vocal": "vocal",
-        "808": "bass",
-        "bass": "bass",
-        "drums": "drums",
-        "percussion": "percussion",
-        "pad": "pad",
-        "texture": "texture",
-        "fx": "fx",
-        "strings": "pad",     # strings map to pad role
-        "piano": "lead",      # piano maps to lead role
-        "guitar": "lead",
-        "brass": "lead",
-        "synth": "lead",
-    }
-
-    for element in intent.explicit_elements:
-        role = element_to_role.get(element)
-        if role and role not in roles:
-            roles.append(role)
-
-    return roles
-
-
-def plan_layers(intent: CompositionIntent) -> list[LayerSpec]:
-    """Convert a CompositionIntent into a list of LayerSpec.
-
-    Each LayerSpec describes one track to create: what to search for,
-    which technique to use, processing chain, and mix settings.
-    """
-    roles = _select_roles(intent)
-    sections = plan_sections(intent)
-    section_names = [s["name"] for s in sections]
-
-    layers: list[LayerSpec] = []
-
-    for role in roles:
-        template = _ROLE_TEMPLATES.get(role)
-        if not template:
-            continue
-
-        # Build search query
-        query = _build_search_query(template["query_template"], intent)
-
-        # Add descriptors to query for richer searches
-        if intent.descriptors:
-            query += " " + " ".join(intent.descriptors[:2])
-
-        # Build Splice filters
-        splice_filters = _build_splice_filters(intent, template["sample_type"])
-
-        # Determine which sections this role appears in
-        role_sections: list[str] = []
-        for section in sections:
-            section_layers = section.get("layers", [])
-            for layer_ref in section_layers:
-                # Parse "drums:-6dB" → "drums"
-                layer_role = layer_ref.split(":")[0]
-                if layer_role == role:
-                    role_sections.append(section["name"])
-                    break
-        # If no section template match, include in all sections
-        if not role_sections:
-            role_sections = section_names
-
-        # Pan spread for stereo width
-        pan = _compute_pan(role, intent.energy)
-
-        layer = LayerSpec(
-            role=role,
-            search_query=query,
-            splice_filters=splice_filters,
-            technique_id=template["technique_id"],
-            processing=list(template["processing"]),  # copy
-            volume_db=template["volume_db"],
-            pan=pan,
-            sections=role_sections,
-            priority=template["priority"],
-        )
-
-        layers.append(layer)
-
-    # Sort by priority (drums first, fx last)
-    layers.sort(key=lambda l: l.priority)
-
-    return layers
-
-
-def plan_sections(intent: CompositionIntent) -> list[dict]:
-    """Plan arrangement sections based on genre and duration.
-
-    Returns a list of dicts: {name, bars, layers, start_bar}.
-    """
-    template = SECTION_TEMPLATES.get(intent.genre, _DEFAULT_SECTION_TEMPLATE)
-
-    # Scale sections to fit duration_bars
-    total_template_bars = sum(s["bars"] for s in template)
-    if total_template_bars == 0:
-        total_template_bars = 64
-
-    scale = intent.duration_bars / total_template_bars
-
-    sections: list[dict] = []
-    current_bar = 0
-
-    for section in template:
-        scaled_bars = max(4, round(section["bars"] * scale))
-        # Round to nearest 4 bars
-        scaled_bars = max(4, (scaled_bars // 4) * 4)
-
-        sections.append({
-            "name": section["name"],
-            "bars": scaled_bars,
-            "layers": list(section["layers"]),
-            "start_bar": current_bar,
-        })
-        current_bar += scaled_bars
-
-    # Clamp overshoot. Rounding each section up to the nearest 4 bars plus
-    # the min-of-4-bars floor means a short duration_bars (e.g. 16) against
-    # a 6-section template could produce 24+ bars of sections — a 50%
-    # overshoot that pushed arrangement clips into unexpected territory.
-    # Trim from the longest non-intro section until we fit.
-    total_placed = sum(s["bars"] for s in sections)
-    overshoot = total_placed - intent.duration_bars
-    if overshoot > 0 and sections:
-        # Sort indices by section length desc, skipping the first section
-        # (usually intro) which we'd rather preserve at its snapped length.
-        trimmable = sorted(
-            range(1, len(sections)),
-            key=lambda i: -sections[i]["bars"],
-        ) or [0]
-        i = 0
-        while overshoot > 0 and i < len(trimmable) * 4:
-            idx = trimmable[i % len(trimmable)]
-            if sections[idx]["bars"] > 4:
-                sections[idx]["bars"] -= 4
-                overshoot -= 4
-            i += 1
-        # Recompute start_bar values after any trim
-        running = 0
-        for s in sections:
-            s["start_bar"] = running
-            running += s["bars"]
-
-    return sections
-
-
-def _compute_pan(role: str, energy: float) -> float:
-    """Compute pan position for a role.
-
-    Core elements (drums, bass) stay centered.
-    Support elements get wider spread at higher energy.
-    """
-    _PAN_MAP = {
-        "drums": 0.0,
-        "bass": 0.0,
-        "lead": 0.0,
-        "pad": 0.0,
-        "vocal": 0.0,
-        "percussion": 0.3,
-        "texture": -0.3,
-        "fx": 0.4,
-    }
-    base_pan = _PAN_MAP.get(role, 0.0)
-    # Widen slightly with energy
-    return base_pan * (0.5 + 0.5 * energy)
+from .full.layer_planner import (  # noqa: F401
+    LayerSpec,
+    plan_layers,
+    plan_sections,
+    _ROLE_TEMPLATES,
+    _GENRE_ROLE_PRIORITY,
+    _DEFAULT_ROLE_PRIORITY,
+    # v1.24: _DEFAULT_SECTION_TEMPLATE removed per vocabulary-not-form principle (Task 12).
+    _build_search_query,
+    _ROLE_INSTRUMENT,
+    _NON_TONAL_ROLES,
+    _build_splice_filters,
+    _select_roles,
+    _compute_pan,
+)

package/mcp_server/composer/sample_resolver.py

@@ -44,7 +44,7 @@ import re
 from pathlib import Path
 from typing import Optional, Tuple
 
-from .layer_planner import LayerSpec
+from .full.layer_planner import LayerSpec
 import logging
 
 logger = logging.getLogger(__name__)
@@ -142,7 +142,12 @@ def _score_candidate(path: Path, layer: LayerSpec, query_tempos: set[str]) -> fl
         if _role_matches(primary, role):
             score += 1.5  # bonus: filename is "about" this layer's role
         else:
-            score -= 5.0  # heavy penalty: filename is about a different role
+            # v1.24 BUG-FULL-MODE-16 fix: when role word is literally in the
+            # filename, the role-word presence is authoritative — soften the
+            # primary-mismatch penalty so synth_bass_* is not hard-rejected.
+            role_in_name = role and role in name
+            mismatch_penalty = 2.0 if role_in_name else 5.0
+            score -= mismatch_penalty  # penalty: filename is about a different role
 
     # 3. Role-adjacent hint words in filename
     hints = _ROLE_HINTS.get(role, frozenset())
@@ -210,15 +215,41 @@ async def _splice_resolve(
     """Query Splice for the layer. Returns (path, source) or (None, 'unresolved').
 
     Tries local hits first (free), then remote downloads (1 credit each,
-    respecting the hard floor). Stops on first success.
+    respecting the hard floor).
+
+    BUG-FULL-MODE-9 (2026-05-01): forwards `layer.splice_filters` to the
+    server-side search (key, chord_type, BPM range, genre, sample_type,
+    instrument). Pre-fix this passed only `query` + `per_page`, which made
+    Splice degrade to text-matching on the search-query string — leading
+    to e.g. `Piano_OneShot_PianoPhrase_Am.wav` winning the bass slot
+    because the filename contains "OneShot" + "Am".
+
+    BUG-FULL-MODE-10 (2026-05-01): scores Splice candidates by role-fit
+    using the same `_score_candidate` heuristic applied to filesystem
+    results. Required because Splice's server-side scoring still doesn't
+    know which result is best for THIS role — a "synth" instrument filter
+    on the lead slot can return both vocals and pad samples; the
+    role-fit score sorts them. Candidates with score ≤ 0 are skipped.
     """
     if splice_client is None or not getattr(splice_client, "connected", False):
         return None, "unresolved"
 
+    # BUG-FULL-MODE-9: forward the per-layer filter dict that the planner
+    # already built (key, chord_type, bpm_min/max, genre, sample_type,
+    # instrument). Pre-fix this was silently dropped — Splice never
+    # received any filtering criteria beyond the free-text query.
+    f = layer.splice_filters or {}
     try:
         result = await splice_client.search_samples(
             query=layer.search_query,
-            per_page=5,
+            key=f.get("key", ""),
+            chord_type=f.get("chord_type", ""),
+            bpm_min=int(f.get("bpm_min", 0)),
+            bpm_max=int(f.get("bpm_max", 0)),
+            genre=f.get("genre", ""),
+            sample_type=f.get("sample_type", ""),
+            instrument=f.get("instrument", ""),
+            per_page=10,  # bumped from 5 to give scorer more options
         )
     except Exception as exc:
         logger.debug("_splice_resolve failed: %s", exc)
@@ -227,14 +258,52 @@ async def _splice_resolve(
     if not samples:
         return None, "unresolved"
 
-    # 1. Prefer already-local Splice hits (zero credit spend)
+    # BUG-FULL-MODE-10: score every candidate by role-fit using filename
+    # heuristics. Score against Splice's `filename` field (authoritative
+    # metadata — usually the original asset name with role hints baked in
+    # like "Piano_OneShot_PianoPhrase_Am.wav"), NOT against `local_path`
+    # which is the cached file location and can be an arbitrary hash or
+    # bootstrap name like "splice_local.wav". When filename is empty,
+    # fall back to local_path so we don't drop legitimately-cached hits.
+    query_tempos = _extract_query_tempos(layer.search_query)
+
+    def _scoring_path(sample) -> Optional[Path]:
+        fn = getattr(sample, "filename", "") or getattr(sample, "name", "") or ""
+        if fn:
+            return Path(fn)
+        lp = getattr(sample, "local_path", "") or ""
+        if lp:
+            return Path(lp)
+        return None
+
+    scored: list[tuple[float, object]] = []
     for sample in samples:
+        path = _scoring_path(sample)
+        if path is None:
+            continue
+        score = _score_candidate(path, layer, query_tempos)
+        scored.append((score, sample))
+
+    # Sort high-to-low; samples with score ≤ 0 are ambiguous (no role
+    # signal) — keep them as fallback but prefer scoring positives first.
+    scored.sort(key=lambda t: t[0], reverse=True)
+
+    # 1. Prefer already-local Splice hits (zero credit spend), in score order.
+    for score, sample in scored:
+        if score <= 0:
+            continue  # fail-fast on negative-scored (wrong-role) matches
         lp = getattr(sample, "local_path", "") or ""
         if lp and Path(lp).exists():
+            logger.debug(
+                "_splice_resolve: local hit '%s' for role=%s score=%.1f",
+                lp, layer.role, score,
+            )
             return lp, "splice_local"
 
-    # 2. Remote download — respect the credit hard floor
-    for sample in samples:
+    # 2. Remote download — respect the credit hard floor, score order.
+    for score, sample in scored:
+        if score <= 0:
+            continue  # don't download wrong-role candidates
         if getattr(sample, "local_path", ""):
             continue  # already handled above
         file_hash = getattr(sample, "file_hash", "")
@@ -246,6 +315,10 @@ async def _splice_resolve(
                 break  # credit floor hit — stop trying, don't try next sample
             downloaded = await splice_client.download_sample(file_hash)
             if downloaded and Path(downloaded).exists():
+                logger.debug(
+                    "_splice_resolve: downloaded '%s' for role=%s score=%.1f",
+                    downloaded, layer.role, score,
+                )
                 return downloaded, "splice_remote"
         except Exception as exc:
             logger.debug("_splice_resolve failed: %s", exc)