livepilot 1.9.24 → 1.10.1

package/mcp_server/preview_studio/engine.py

@@ -121,7 +121,11 @@ def _build_triptych(
         compiled_plan = None
         if moves and i < len(moves):
             move_id = moves[i].get("move_id", "")
-            compiled_plan = moves[i].get("compile_plan")
+            # Compile through the semantic compiler — single source of truth
+            from ..wonder_mode.engine import _compile_variant_plan
+            kernel = {"session_info": {"tempo": 120, "tracks": []}, "mode": "improve"}
+            compiled_plan = _compile_variant_plan(moves[i], kernel)
+            # No fallback to plan_template — uncompilable moves stay analytical
 
         variants.append(PreviewVariant(
             variant_id=f"{set_id}_{profile['label']}",
@@ -264,7 +268,10 @@ def _compute_set_id(request_text: str, kernel_id: str) -> str:
 
 def _estimate_taste_fit(novelty: float, taste_graph: dict) -> float:
     """Estimate how well a novelty level fits user taste."""
-    boldness = taste_graph.get("transition_boldness", 0.5)
+    # Routes through the canonical accessor so dimension_weights.transition_boldness
+    # is honored. Previously read the top-level key directly and always got 0.5.
+    from ..memory.taste_accessors import get_dimension_pref
+    boldness = get_dimension_pref(taste_graph, "transition_boldness", default=0.5)
     # Users who like boldness prefer higher novelty
     fit = 1.0 - abs(novelty - boldness) * 0.5
     return round(max(0.0, min(1.0, fit)), 3)

package/mcp_server/preview_studio/tools.py

@@ -23,7 +23,15 @@ def _get_ableton(ctx: Context):
 
 def _should_refuse_analytical(compiled_plan, wonder_linked: bool) -> bool:
     """Check if an analytical variant should be refused in Wonder context."""
-    return compiled_plan is None and wonder_linked
+    if not wonder_linked:
+        return False
+    if compiled_plan is None:
+        return True
+    if isinstance(compiled_plan, dict):
+        return len(compiled_plan.get("steps", [])) == 0
+    if isinstance(compiled_plan, list):
+        return len(compiled_plan) == 0
+    return True
 
 
 def _find_wonder_session_by_preview(set_id: str):
@@ -308,7 +316,7 @@ def commit_preview_variant(
 
 
 @mcp.tool()
-def render_preview_variant(
+async def render_preview_variant(
     ctx: Context,
     set_id: str = "",
     variant_id: str = "",
@@ -352,7 +360,7 @@ def render_preview_variant(
             "analytical_only": True,
         }
 
-    # If the variant has a compiled plan, we could apply-capture-undo.
+    # If the variant has a compiled plan, apply -> capture audible -> undo.
     # Without a compiled plan, return the variant's analytical preview.
     if variant.compiled_plan:
         ableton = _get_ableton(ctx)
@@ -360,52 +368,87 @@ def render_preview_variant(
         plan = variant.compiled_plan
         steps = plan if isinstance(plan, list) else plan.get("steps", [])
 
-        from ..runtime.execution_router import execute_plan_steps
+        from ..runtime.execution_router import execute_plan_steps_async
 
         applied_count = 0
-        try:
-            # Capture before state
-            before_info = ableton.send_command("get_session_info", {})
+        playback_started = False
+        preview_mode = "metadata_only_preview"
+        spectral_before: Optional[dict] = None
+        spectral_after: Optional[dict] = None
+        before_info: dict = {}
+        after_info: dict = {}
+
+        bridge = ctx.lifespan_context.get("m4l")
+        mcp_registry = ctx.lifespan_context.get("mcp_dispatch", {})
 
-            # Execute through unified router
-            exec_results = execute_plan_steps(steps, ableton=ableton, ctx=ctx)
+        try:
+            # ── 1. Capture BEFORE metadata ──
+            before_info = ableton.send_command("get_session_info", {}) or {}
+
+            # ── 2. Apply the variant ──
+            exec_results = await execute_plan_steps_async(
+                steps,
+                ableton=ableton,
+                bridge=bridge,
+                mcp_registry=mcp_registry,
+                ctx=ctx,
+            )
             applied_count = sum(1 for r in exec_results if r.ok)
+            if applied_count == 0 and steps:
+                return {
+                    "error": "Variant failed to apply any steps",
+                    "variant_id": variant_id,
+                    "step_errors": [r.error for r in exec_results if not r.ok],
+                }
+
+            # ── 3. Capture AFTER metadata (variant is live) ──
+            after_info = ableton.send_command("get_session_info", {}) or {}
+
+            # ── 4. Audible capture WHILE variant is still applied ──
+            # This is the critical ordering fix: previously this block ran AFTER
+            # the finally's undo loop, so "audible_preview" captured pre-variant
+            # audio and lied about it. Now playback + spectrum sampling happens
+            # while the variant is actually in effect, then the finally undoes it.
+            try:
+                from ..m4l_bridge import SpectralCache
+                cache = ctx.lifespan_context.get("spectral")
+                if cache and isinstance(cache, SpectralCache) and cache.is_connected:
+                    spectral_before = cache.get_all()
+
+                    tempo = before_info.get("tempo", 120) or 120
+                    play_seconds = min(bars * (60.0 / tempo) * 4, 8.0)
+
+                    ableton.send_command("start_playback", {})
+                    playback_started = True
+
+                    import time as _time
+                    _time.sleep(play_seconds)
+
+                    spectral_after = cache.get_all()
+
+                    ableton.send_command("stop_playback", {})
+                    playback_started = False
+
+                    preview_mode = "audible_preview"
+            except Exception:
+                # Spectral capture is best-effort; keep preview_mode as metadata_only
+                pass
 
-            # Capture after state
-            after_info = ableton.send_command("get_session_info", {})
         except Exception as e:
             return {"error": f"Render failed: {e}", "variant_id": variant_id}
         finally:
-            # Undo all applied changes regardless of success/failure
+            # ── 5. Cleanup: stop playback if still running, then undo everything ──
+            if playback_started:
+                try:
+                    ableton.send_command("stop_playback", {})
+                except Exception:
+                    pass
             for _ in range(applied_count):
                 try:
                     ableton.send_command("undo")
                 except Exception:
                     break
 
-        # Determine preview mode: audible (M4L available) or metadata-only
-        preview_mode = "metadata_only_preview"
-        spectral_before = None
-        spectral_after = None
-
-        # Try audible preview — capture spectrum via M4L spectral cache
-        try:
-            from ..m4l_bridge import SpectralCache
-            cache = ctx.lifespan_context.get("spectral_cache")
-            if cache and isinstance(cache, SpectralCache) and cache.has_data():
-                spectral_before = cache.get_snapshot()
-                # Play for the requested bar count
-                tempo = before_info.get("tempo", 120)
-                play_seconds = bars * (60.0 / tempo) * 4  # bars * beat_duration * 4 beats
-                ableton.send_command("start_playback", {})
-                import time as _time
-                _time.sleep(min(play_seconds, 8.0))  # cap at 8 seconds
-                spectral_after = cache.get_snapshot()
-                ableton.send_command("stop_playback", {})
-                preview_mode = "audible_preview"
-        except Exception:
-            pass  # fall back to metadata_only
-
         variant.status = "rendered"
         variant.preview_mode = preview_mode
         variant.render_ref = f"render_{variant_id}_{bars}bars"

package/mcp_server/project_brain/tools.py

@@ -78,6 +78,39 @@ def build_project_brain(ctx: Context) -> dict:
         except Exception:
             pass
 
+    # 5b. Build notes_map for role inference.
+    # Shape: {section_id: {track_index: [notes]}}. Without this, role_graph
+    # falls back to "assume all tracks active in every section" which destroys
+    # section-scoped role confidence.
+    notes_map: dict[str, dict[int, list[dict]]] = {}
+    try:
+        for scene_idx, scene in enumerate(scenes or []):
+            section_id = str(
+                scene.get("section_id")
+                or scene.get("name")
+                or f"scene_{scene_idx}"
+            )
+            per_track: dict[int, list[dict]] = {}
+            for track in tracks:
+                t_idx = track.get("index", 0)
+                try:
+                    notes_resp = ableton.send_command("get_notes", {
+                        "track_index": t_idx,
+                        "clip_index": scene_idx,
+                    })
+                    if isinstance(notes_resp, dict):
+                        notes = notes_resp.get("notes", [])
+                        if notes:
+                            per_track[t_idx] = notes
+                except Exception:
+                    # Individual note fetch failing is fine — continue with others
+                    continue
+            if per_track:
+                notes_map[section_id] = per_track
+    except Exception:
+        # Overall failure: empty map, degrade to "all tracks active" fallback
+        notes_map = {}
+
     # 6. Probe capabilities (direct SpectralCache access, not TCP)
     analyzer_ok = False
     analyzer_fresh = False
@@ -103,6 +136,7 @@ def build_project_brain(ctx: Context) -> dict:
         scenes=scenes if scenes and clip_matrix else None,
         clip_matrix=clip_matrix if clip_matrix else None,
         track_infos=track_infos if track_infos else None,
+        notes_map=notes_map if notes_map else None,
         arrangement_clips=arrangement_clips if arrangement_clips else None,
         analyzer_ok=analyzer_ok,
         flucoma_ok=flucoma_ok,

package/mcp_server/runtime/capability_probe.py

@@ -34,6 +34,23 @@ def probe_capabilities(
         "detail": "TCP 9878 connection active" if ableton_ok else "Not connected",
     }
 
+    # 1b. Live version capabilities
+    live_version_str = "12.0.0"
+    if ableton_ok:
+        try:
+            info = ableton.send_command("get_session_info")
+            live_version_str = info.get("live_version", "12.0.0")
+        except Exception:
+            pass
+    from .live_version import LiveVersionCapabilities
+    version_caps = LiveVersionCapabilities.from_version_string(live_version_str)
+    report["live_version"] = {
+        "status": "ok",
+        "version": live_version_str,
+        "capability_tier": version_caps.capability_tier,
+        "features": version_caps.to_dict(),
+    }
+
     # 2. Remote Script parity
     from .remote_commands import REMOTE_COMMANDS
     report["remote_script"] = {
@@ -45,8 +62,10 @@ def probe_capabilities(
     # 3. M4L bridge
     bridge_ok = False
     if ctx is not None:
-        bridge = getattr(ctx, "lifespan_context", {}).get("m4l_bridge") if hasattr(ctx, "lifespan_context") else None
-        bridge_ok = bridge is not None
+        lifespan_context = getattr(ctx, "lifespan_context", {}) if hasattr(ctx, "lifespan_context") else {}
+        bridge = lifespan_context.get("m4l")
+        spectral = lifespan_context.get("spectral")
+        bridge_ok = bridge is not None and spectral is not None and getattr(spectral, "is_connected", False)
     report["m4l_bridge"] = {
         "status": "ok" if bridge_ok else "unavailable",
         "detail": "UDP 9880 / OSC 9881 active" if bridge_ok else "Not connected — 30 analyzer tools unavailable",

package/mcp_server/runtime/execution_router.py

@@ -1,34 +1,52 @@
-"""Unified execution router for compiled plan steps.
+"""Unified async execution router for compiled plan steps.
 
 Classifies each step by backend (remote_command, mcp_tool, bridge_command)
-and dispatches to the correct execution path. Replaces the pattern of
-sending everything through ableton.send_command() blindly.
+and dispatches through the correct transport. Async-only — there is no
+sync path. Callers that need to execute plans live inside an async tool
+and await execute_plan_steps_async.
 
 Step backends:
-  remote_command — valid Remote Script handler, goes through TCP
-  bridge_command — M4L bridge handler, goes through TCP (requires bridge)
-  mcp_tool — MCP-layer Python function, called directly
-  unknown — not a valid target anywhere
+  remote_command — valid Remote Script handler, goes through the sync TCP
+                    client (ableton.send_command)
+  bridge_command — M4L bridge handler, goes through the async UDP M4L bridge
+                    client (bridge.send_command), NOT through ableton
+  mcp_tool       — in-process Python function, dispatched via an mcp_registry
+                    dict supplied by the server lifespan
+  unknown        — not a valid target anywhere; returns a clear error
+
+Step-result binding:
+  Any step may carry an optional step_id. Later steps may reference an
+  earlier result by setting a param to {"$from_step": "<id>", "path": "a.b"}.
+  Resolved recursively BEFORE dispatch.
 """
 
 from __future__ import annotations
 
+import inspect
 from dataclasses import dataclass
-from typing import Any, Optional
+from typing import Any, Awaitable, Callable, Optional
 
 from .remote_commands import BRIDGE_COMMANDS, REMOTE_COMMANDS
 
 
 # MCP-only tools that exist as Python functions but NOT as TCP handlers.
 # These must be called through direct import, not ableton.send_command().
+# NOTE: capture_audio is a BRIDGE command (livepilot_bridge.js:146), not MCP.
+# It used to be duplicated here; removed to keep classification unambiguous.
 MCP_TOOLS: frozenset[str] = frozenset({
     "apply_automation_shape",
     "apply_gesture_template",
     "analyze_mix",
     "get_master_spectrum",
     "get_emotional_arc",
-    "capture_audio",
     "get_motif_graph",
+    # Sample-engine workflow tools — async Python that orchestrates multiple
+    # sub-commands (search_browser + load_browser_item + bridge.replace_simpler_sample).
+    "load_sample_to_simpler",
+    # Device Forge tools (MCP-only, no TCP handler)
+    "generate_m4l_effect",
+    "install_m4l_device",
+    "list_genexpr_templates",
 })
 
 
@@ -62,17 +80,75 @@ def classify_step(tool: str) -> str:
     return "unknown"
 
 
-def execute_step(
+# ── Step-result binding ─────────────────────────────────────────────────
+
+def _resolve_binding(binding: dict, step_results: dict) -> Any:
+    """Resolve a {"$from_step": step_id, "path": "a.b.c"} binding.
+
+    Raises ValueError with a clear message on missing step_id or missing key.
+    """
+    step_id = binding["$from_step"]
+    path = binding.get("path", "")
+
+    if step_id not in step_results:
+        available = sorted(step_results.keys())
+        raise ValueError(
+            f"Step binding failed: step_id '{step_id}' not found. "
+            f"Available: {available or '(no earlier results)'}"
+        )
+
+    current = step_results[step_id]
+    if not isinstance(current, dict):
+        raise ValueError(
+            f"Step binding failed: result of '{step_id}' is "
+            f"{type(current).__name__}, not a dict"
+        )
+
+    if not path:
+        return current
+
+    for segment in path.split("."):
+        if not isinstance(current, dict) or segment not in current:
+            keys = list(current.keys()) if isinstance(current, dict) else type(current).__name__
+            raise ValueError(
+                f"Step binding failed: path '{path}' not found in result of "
+                f"'{step_id}'. Available at this level: {keys}"
+            )
+        current = current[segment]
+
+    return current
+
+
+def _resolve_params(params: Any, step_results: dict) -> Any:
+    """Recursively walk params and resolve any $from_step bindings."""
+    if isinstance(params, dict):
+        if "$from_step" in params:
+            return _resolve_binding(params, step_results)
+        return {k: _resolve_params(v, step_results) for k, v in params.items()}
+    if isinstance(params, list):
+        return [_resolve_params(v, step_results) for v in params]
+    return params
+
+
+# ── Async execution path ────────────────────────────────────────────────
+
+async def _execute_step_async(
     tool: str,
     params: dict,
-    ableton: Any = None,
-    ctx: Any = None,
-    declared_backend: str | None = None,
+    ableton: Any,
+    bridge: Any,
+    mcp_registry: dict[str, Callable],
+    ctx: Any,
+    declared_backend: Optional[str] = None,
 ) -> ExecutionResult:
-    """Execute a single plan step through the correct backend."""
-    backend = declared_backend if declared_backend in ("remote_command", "bridge_command", "mcp_tool") else classify_step(tool)
+    """Dispatch a single step through the correct transport, async-aware."""
+    backend = (
+        declared_backend
+        if declared_backend in ("remote_command", "bridge_command", "mcp_tool")
+        else classify_step(tool)
+    )
 
-    if backend in ("remote_command", "bridge_command"):
+    if backend == "remote_command":
         if ableton is None:
             return ExecutionResult(
                 ok=False, backend=backend, tool=tool,
@@ -80,45 +156,95 @@ def execute_step(
             )
         try:
             result = ableton.send_command(tool, params)
+            if isinstance(result, dict) and "error" in result:
+                return ExecutionResult(ok=False, backend=backend, tool=tool, error=result["error"])
             return ExecutionResult(ok=True, backend=backend, tool=tool, result=result)
         except Exception as e:
             return ExecutionResult(ok=False, backend=backend, tool=tool, error=str(e))
 
-    elif backend == "mcp_tool":
-        # MCP tools require direct Python dispatch.
-        # For now, return a clear error — full MCP dispatch is wired per-tool
-        # in the callers (apply_semantic_move, render_preview_variant).
-        return ExecutionResult(
-            ok=False, backend=backend, tool=tool,
-            error=f"MCP tool '{tool}' requires direct Python dispatch — "
-                  f"not executable through TCP. Use the MCP layer directly.",
-        )
+    if backend == "bridge_command":
+        if bridge is None:
+            return ExecutionResult(
+                ok=False, backend=backend, tool=tool,
+                error="M4L bridge unavailable — cannot dispatch bridge command",
+            )
+        try:
+            # M4LBridge.send_command accepts (command, *args) and OSC-encodes
+            # each arg positionally. Plan authors construct params dicts in
+            # the order the bridge command expects; we unpack by insertion
+            # order (Python 3.7+ guarantees this). This keeps plans readable
+            # while matching the real bridge's positional wire format.
+            positional = list(params.values()) if params else []
+            call = bridge.send_command(tool, *positional)
+            result = await call if inspect.isawaitable(call) else call
+            if isinstance(result, dict) and "error" in result:
+                return ExecutionResult(ok=False, backend=backend, tool=tool, error=result["error"])
+            return ExecutionResult(ok=True, backend=backend, tool=tool, result=result)
+        except Exception as e:
+            return ExecutionResult(ok=False, backend=backend, tool=tool, error=str(e))
 
-    else:
-        return ExecutionResult(
-            ok=False, backend="unknown", tool=tool,
-            error=f"Unknown tool '{tool}' — not a Remote Script command, "
-                  f"bridge command, or registered MCP tool",
-        )
+    if backend == "mcp_tool":
+        fn = mcp_registry.get(tool) if mcp_registry else None
+        if fn is None:
+            return ExecutionResult(
+                ok=False, backend=backend, tool=tool,
+                error=(
+                    f"MCP tool '{tool}' not registered in async router dispatch map. "
+                    f"Add it to mcp_server.runtime.mcp_dispatch.build_mcp_dispatch_registry()."
+                ),
+            )
+        try:
+            sig = inspect.signature(fn)
+            kwargs = {"ctx": ctx} if "ctx" in sig.parameters else {}
+            call = fn(params, **kwargs)
+            result = await call if inspect.isawaitable(call) else call
+            if isinstance(result, dict) and "error" in result:
+                return ExecutionResult(ok=False, backend=backend, tool=tool, error=result["error"])
+            return ExecutionResult(ok=True, backend=backend, tool=tool, result=result)
+        except Exception as e:
+            return ExecutionResult(ok=False, backend=backend, tool=tool, error=str(e))
+
+    return ExecutionResult(
+        ok=False, backend="unknown", tool=tool,
+        error=(
+            f"Unknown tool '{tool}' — not a Remote Script command, "
+            f"bridge command, or registered MCP tool"
+        ),
+    )
 
 
-def execute_plan_steps(
+async def execute_plan_steps_async(
     steps: list[dict],
     ableton: Any = None,
+    bridge: Any = None,
+    mcp_registry: Optional[dict[str, Callable]] = None,
     ctx: Any = None,
     stop_on_failure: bool = True,
 ) -> list[ExecutionResult]:
-    """Execute a list of plan steps, returning results for each.
+    """Async plan executor with step-result binding and correct bridge transport.
 
-    Stops on first failure by default. Set stop_on_failure=False
-    to continue past errors (useful for best-effort execution).
+    Supports three backends:
+      - remote_command via ableton.send_command (sync TCP client)
+      - bridge_command via bridge.send_command  (async UDP M4L bridge client)
+      - mcp_tool       via mcp_registry[tool](params, ctx=ctx)
+
+    Step-result binding:
+      Any step may carry an optional "step_id". Later steps may reference an
+      earlier result by setting a param to {"$from_step": "<id>", "path": "a.b"}.
+      The router walks params recursively and resolves bindings before dispatch.
+      Missing ids or missing paths fail that step with a clear error.
+
+    stop_on_failure: Stop the plan on the first failing step (default). Set to
+      False for best-effort execution (each result still recorded).
     """
     results: list[ExecutionResult] = []
+    step_results: dict[str, Any] = {}
+    mcp_registry = mcp_registry or {}
 
     for step in steps:
         tool = step.get("tool") or step.get("command", "")
-        params = step.get("params") or step.get("args", {})
-        # Honor declared backend from step annotations (PR5) if present
+        raw_params = step.get("params") or step.get("args", {}) or {}
+        step_id = step.get("step_id")
         declared_backend = step.get("backend")
 
         if not tool:
@@ -130,9 +256,29 @@ def execute_plan_steps(
                 break
             continue
 
-        result = execute_step(tool, params, ableton=ableton, ctx=ctx, declared_backend=declared_backend)
+        # Resolve any $from_step bindings in params BEFORE dispatch.
+        try:
+            params = _resolve_params(raw_params, step_results)
+        except ValueError as e:
+            results.append(ExecutionResult(
+                ok=False, backend="binding", tool=tool, error=str(e),
+            ))
+            if stop_on_failure:
+                break
+            continue
+
+        result = await _execute_step_async(
+            tool, params,
+            ableton=ableton, bridge=bridge,
+            mcp_registry=mcp_registry, ctx=ctx,
+            declared_backend=declared_backend,
+        )
         results.append(result)
 
+        # Record successful step result for future bindings
+        if result.ok and step_id and isinstance(result.result, dict):
+            step_results[step_id] = result.result
+
         if not result.ok and stop_on_failure:
             break
 

package/mcp_server/runtime/live_version.py

@@ -0,0 +1,102 @@
+"""MCP-side Live version capabilities model.
+
+Pure data model — no I/O. Parses version info from get_session_info
+responses and exposes feature flags for tool routing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class LiveVersionCapabilities:
+    """Feature availability based on detected Live version."""
+
+    major: int = 12
+    minor: int = 0
+    patch: int = 0
+
+    @classmethod
+    def from_version_string(cls, version_str: str) -> LiveVersionCapabilities:
+        """Parse '12.3.6' into a capabilities instance."""
+        parts = version_str.split(".")
+        major = int(parts[0]) if len(parts) > 0 else 12
+        minor = int(parts[1]) if len(parts) > 1 else 0
+        patch = int(parts[2]) if len(parts) > 2 else 0
+        return cls(major=major, minor=minor, patch=patch)
+
+    @classmethod
+    def from_session_info(cls, session_info: dict) -> LiveVersionCapabilities:
+        """Extract version from get_session_info response.
+
+        Looks for 'live_version' field. Falls back to 12.0.0 if absent
+        (pre-upgrade Remote Script).
+        """
+        version_str = session_info.get("live_version", "12.0.0")
+        return cls.from_version_string(version_str)
+
+    @property
+    def _version_tuple(self) -> tuple[int, int, int]:
+        return (self.major, self.minor, self.patch)
+
+    # ── Feature flags ──────────────────────────────────────────────
+
+    @property
+    def has_native_arrangement_clips(self) -> bool:
+        """Track.create_midi_clip(start, length) — 12.1.10+"""
+        return self._version_tuple >= (12, 1, 10)
+
+    @property
+    def has_display_value(self) -> bool:
+        """DeviceParameter.display_value — 12.2+"""
+        return self._version_tuple >= (12, 2, 0)
+
+    @property
+    def has_insert_device(self) -> bool:
+        """Track.insert_device(name, index?) — 12.3+"""
+        return self._version_tuple >= (12, 3, 0)
+
+    @property
+    def has_drum_rack_construction(self) -> bool:
+        """insert_chain + DrumChain.in_note — 12.3+"""
+        return self._version_tuple >= (12, 3, 0)
+
+    @property
+    def has_take_lanes(self) -> bool:
+        """Take Lanes API — 12.2+"""
+        return self._version_tuple >= (12, 2, 0)
+
+    @property
+    def has_stem_separation(self) -> bool:
+        """Stem separation via MFL — 12.3+"""
+        return self._version_tuple >= (12, 3, 0)
+
+    @property
+    def has_replace_sample_native(self) -> bool:
+        """SimplerDevice.replace_sample(path) — 12.4+"""
+        return self._version_tuple >= (12, 4, 0)
+
+    @property
+    def capability_tier(self) -> str:
+        """Human-readable tier: core | enhanced_arrangement | full_intelligence."""
+        if self._version_tuple >= (12, 3, 0):
+            return "full_intelligence"
+        elif self._version_tuple >= (12, 1, 10):
+            return "enhanced_arrangement"
+        else:
+            return "core"
+
+    def to_dict(self) -> dict:
+        """Serialize for API responses and capability probes."""
+        return {
+            "version": f"{self.major}.{self.minor}.{self.patch}",
+            "capability_tier": self.capability_tier,
+            "native_arrangement_clips": self.has_native_arrangement_clips,
+            "display_value": self.has_display_value,
+            "insert_device": self.has_insert_device,
+            "drum_rack_construction": self.has_drum_rack_construction,
+            "take_lanes": self.has_take_lanes,
+            "stem_separation": self.has_stem_separation,
+            "replace_sample_native": self.has_replace_sample_native,
+        }