davinci-resolve-mcp 2.88.0 → 2.89.0

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.89.0
+
+The build gates this server already enforced are now gates an agent can ask
+about, and the capability probe those gates run on no longer lies. Issue #132,
+reported by @magwa101.
+
+### Added
+
+- **`get_version` reports what the connected build is missing.** A new `build`
+  block carries `unavailable_on_this_build` — every recorded API surface this
+  build does not have — plus `known_gates` and the caveat that an absence from
+  that list is not a promise a method exists. #132 happened in a session that
+  opened with `get_version` and was told a number and nothing the number ruled
+  out. `get_resolve_version_fields` gains the same list on the granular server.
+- **The version-gate registry went from 7 recorded surfaces to 41.**
+  `_requires_method(obj, "GetLayoutPresetList", "21.0.4")` appears 44 times
+  across the two servers and gates 31 distinct symbols, but
+  `check_version_support` — the call `resolve-session` step 2 tells an agent to
+  make — answered from a ledger that knew seven of them. So the one question an
+  agent is instructed to ask returned `unknown` for surfaces this server was
+  already routing on. On Studio 19.1.3.7 the session preflight named 7 missing
+  surfaces; it now names 40. The new floors are labelled `documented` rather
+  than `measured`: they come from Blackmagic's release documentation, not a live
+  bisect here, and an agent relaying one should be able to say which.
+- **`tests/test_version_gate_drift.py`** fails when a call site and the ledger
+  disagree, and when a bare method name is gated at two different builds on two
+  different classes (which would make a bare-name lookup a coin flip). A table
+  copied by hand is exactly what drifts back apart.
+- **`src/utils/resolve_probe.py`** — `has_method` and `api_constant`, with the
+  measurement behind them. A companion guard fails the suite on a bare `hasattr`
+  with a Resolve-shaped attribute name.
+
+### Fixed
+
+- **29 capability probes across `src/` used `hasattr` on Resolve API objects,
+  where it is a constant `True`** (measured on Studio 19.1.3.7 across 42 checks,
+  recorded in `api_truth`; re-confirmed live for this release —
+  `hasattr(project, 'GenerateSpeech')` returns `True` on a build that has no
+  such method). It failed in two shapes that look nothing alike:
+  - `if not hasattr(clip, "RemoveMotionBlur")` is a dead branch, so the
+    "requires Resolve 21+" refusal never fired and the call below it raised
+    `AttributeError` on an older build. Eleven of these were the granular
+    server's Resolve 21 AI guards.
+  - `getattr(r, n) if hasattr(r, n) else n` never reaches its `else`, so a build
+    without the constant got `None` where the author wrote a string fallback —
+    no exception, no refusal, just a `None` travelling on into `Export()`. This
+    reached granular timeline export and `ExportLUT`, and three constant
+    lookups on the compound server. Confirmed live: a name Resolve does not
+    define returned `None` under the old form and now falls back correctly.
+    The fallback keys on `is None`, not truthiness, because `EXPORT_AAF` is
+    genuinely `0.0`.
+- **The granular AI tools reported a missing Extras pack as success.** Resolve's
+  AI methods return the reason as a *string* when the pack is absent, and
+  `bool("Required package ... is not installed.")` is `True`. The compound
+  server has normalized that since the 21.0.2.4 measurement; the granular one
+  had not, so folder and clip audio classification returned `{"success": true}`
+  for a call that did not run, and `RemoveMotionBlur` / `GenerateSpeech` walked
+  a string into `.GetName()`. All now route through `_ai_result`, which reports
+  the failure and carries Resolve's own reason.
+- **`Project.ApplyFairlightPresetToCurrentTimeline` was recorded on `Timeline`.**
+  The shipped README lists it under Project and the server calls it there; the
+  method's name is what made the wrong attribution look right.
+
+### Validation
+
+Suite 2560 → 2580. Live-checked against the running Studio 19.1.3.7 for the
+probe semantics, the refusal path, the constant fallback, and the `get_version`
+preflight (40 of 41 gates unavailable, as expected on that build). The Resolve 21
+and 21.0.4 surfaces themselves remain untested here — this machine cannot run
+them — and the Extras-pack failure paths are pinned by a stub that reproduces
+the measured attribute-fabrication behaviour rather than by a live 21 build.
+
 ## What's New in v2.88.0
 
 The twelve Resolve 21.0.4 surfaces that only existed on the compound server now

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.88.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.89.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.88.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.89.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.88.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.89.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -489,7 +489,16 @@ you are on the correct page first.
 Key actions:
 - `launch` — connect to or start Resolve; call this first if any tool returns a
   "Not connected" error
-- `get_version` — returns `{product, version, version_string}`
+- `get_version` — returns `{product, version, version_string, build, mcp}`.
+  `build.unavailable_on_this_build` lists every recorded API surface this build
+  does **not** have; read it before offering anything version-gated. An absence
+  from that list is not a promise a method exists — most of the API has never
+  been version-bisected, so `check_version_support` answers `unknown` for it,
+  and `unknown` means probe with `name in dir(obj)`, never bare `hasattr`
+  (constant `True` on Resolve objects)
+- `check_version_support(symbol?, resolve_version?)` — is one named symbol on
+  this build? Without `symbol`, the same missing-surface list `get_version`
+  carries. No connection needed when `resolve_version` is passed
 - `api_truth(query?)` — look up behaviorally-verified facts about quirky/unreliable
   Resolve API behavior (no connection needed); filter by substring
 - `verification_stats` — readback-verification tally (verified/contradicted/

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.88.0"
+VERSION = "2.89.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.88.0",
+  "version": "2.89.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -45,6 +45,7 @@ from src.utils.media_analysis_jobs import (
 )
 from src.utils.platform import setup_environment
 from src.utils.resolve_connection import connect_resolve
+from src.utils.resolve_probe import has_method
 from src.utils.analysis_memory import read_panel_state, write_panel_state
 from src.utils import brain_edits as _brain_edits
 from src.utils import timeline_versioning as _timeline_versioning
@@ -11917,7 +11918,7 @@ HTML = HTML.replace("/* CONTROL_PANEL_I18N */", localization_script())
 
 
 def _safe_call(obj: Any, method_name: str, *args: Any) -> Tuple[Any, Optional[str]]:
-    if obj is None or not hasattr(obj, method_name):
+    if not has_method(obj, method_name):
         return None, f"{method_name} unavailable"
     try:
         return getattr(obj, method_name)(*args), None

package/src/granular/common.py

@@ -49,6 +49,8 @@ from src.utils.render_ids import (
     render_format_id_from_formats,
 )
 from src.utils.resolve_connection import connect_resolve
+from src.utils.resolve_probe import api_constant as _api_constant, has_method
+from src.utils.resolve_versions import availability, gates_unavailable_on
 from src.utils.project_properties import (
     get_all_project_properties,
     get_color_settings,
@@ -85,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.88.0"
+VERSION = "2.89.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -741,11 +743,43 @@ def _get_timeline_item(track_type="video", track_index=1, item_index=0):
     return items[item_index], None
 
 def _has_method(obj, method_name):
-    return callable(getattr(obj, method_name, None))
+    # `hasattr` is a constant True on Resolve objects — see src/utils/resolve_probe.
+    return has_method(obj, method_name)
 
 def _requires_method(obj, method_name, min_version):
     if _has_method(obj, method_name):
         return None
     return {"error": f"{method_name} requires DaVinci Resolve {min_version}+"}
 
+def _ai_result(returned):
+    """Normalize a Resolve 21 AI-method return into (ok, message).
+
+    The AI methods do not agree on how they report a missing Extras pack, and
+    one of the two shapes is a trap. Verified live on Studio 21.0.2.4 with only
+    AI Motion Deblur installed:
+
+      - `AnalyzeForSlate`  -> False
+      - `AnalyzeForIntellisearch` -> "Required package 'AI Intellisearch -
+        Faster' is not installed."
+      - `GenerateSpeech`   -> "Required Package, 'AI Speech Generator' is not
+        Installed."
+
+    A non-empty string is truthy, so `bool(returned)` reports success for a call
+    that definitively did not run, and treating the return as a MediaPoolItem
+    raises AttributeError. This is the compound server's `_ai_result`, kept
+    identical on purpose: the granular tools called the same AI methods with a
+    bare `bool()` and inherited the whole trap.
+    """
+    if isinstance(returned, str):
+        return False, returned.strip() or None
+    return bool(returned), None
+
+def _ai_result_payload(returned):
+    """`{"success": ...}` plus the Resolve-supplied reason when there is one."""
+    ok, message = _ai_result(returned)
+    payload = {"success": ok}
+    if message:
+        payload["error"] = message
+    return payload
+
 __all__ = [name for name in globals() if not name.startswith("__")]

package/src/granular/folder.py

@@ -325,9 +325,10 @@ def folder_perform_audio_classification(folder_path: str = "") -> Dict[str, Any]
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "PerformAudioClassification"):
-        return {"error": "PerformAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.PerformAudioClassification())}
+    missing = _requires_method(folder, "PerformAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.PerformAudioClassification())
 
 
 @mcp.tool()
@@ -343,9 +344,10 @@ def folder_clear_audio_classification(folder_path: str = "") -> Dict[str, Any]:
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "ClearAudioClassification"):
-        return {"error": "ClearAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.ClearAudioClassification())}
+    missing = _requires_method(folder, "ClearAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.ClearAudioClassification())
 
 
 @mcp.tool()
@@ -363,9 +365,10 @@ def folder_analyze_for_intellisearch(folder_path: str = "", identify_faces: bool
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "AnalyzeForIntellisearch"):
-        return {"error": "AnalyzeForIntellisearch requires DaVinci Resolve 21+"}
-    return {"success": bool(folder.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))}
+    missing = _requires_method(folder, "AnalyzeForIntellisearch", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(folder.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))
 
 
 @mcp.tool()
@@ -383,11 +386,12 @@ def folder_analyze_for_slate(folder_path: str = "", marker_color: str = "Blue")
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "AnalyzeForSlate"):
-        return {"error": "AnalyzeForSlate requires DaVinci Resolve 21+"}
+    missing = _requires_method(folder, "AnalyzeForSlate", "21.0")
+    if missing:
+        return missing
     if marker_color not in _MARKER_COLORS:
         return {"error": f"Invalid marker_color '{marker_color}'. Valid: {', '.join(_MARKER_COLORS)}"}
-    return {"success": bool(folder.AnalyzeForSlate(marker_color))}
+    return _ai_result_payload(folder.AnalyzeForSlate(marker_color))
 
 
 @mcp.tool()
@@ -407,9 +411,16 @@ def folder_remove_motion_blur(folder_path: str = "", deblur_option: Optional[Dic
     folder, err = _resolve_folder(mp, folder_path)
     if err:
         return err
-    if not hasattr(folder, "RemoveMotionBlur"):
-        return {"error": "RemoveMotionBlur requires DaVinci Resolve 21+"}
+    missing = _requires_method(folder, "RemoveMotionBlur", "21.0")
+    if missing:
+        return missing
     result = folder.RemoveMotionBlur(deblur_option or {})
+    # A missing Extras pack comes back as an error STRING, which is truthy and
+    # also iterable — the loop below would walk it character by character and
+    # report success. Normalize before either.
+    ok, message = _ai_result(result)
+    if not ok:
+        return {"success": False, "error": message} if message else {"success": False}
     created = []
     for pair in (result or []):
         try:
@@ -417,4 +428,4 @@ def folder_remove_motion_blur(folder_path: str = "", deblur_option: Optional[Dic
             created.append({"original": orig.GetName(), "new": new.GetName(), "new_id": new.GetUniqueId()})
         except Exception:
             continue
-    return {"success": bool(result), "created": created}
+    return {"success": True, "created": created}

package/src/granular/media_pool_item.py

@@ -17,13 +17,13 @@ def _invalidate_analysis_registry_for_clip(project, clip, *, reason: str) -> Opt
     if project is None or clip is None:
         return None
     try:
-        project_name = project.GetName() if hasattr(project, "GetName") else None
-        project_id = project.GetUniqueId() if hasattr(project, "GetUniqueId") else None
-        clip_id = clip.GetUniqueId() if hasattr(clip, "GetUniqueId") else None
-        media_id = clip.GetMediaId() if hasattr(clip, "GetMediaId") else None
+        project_name = project.GetName() if _has_method(project, "GetName") else None
+        project_id = project.GetUniqueId() if _has_method(project, "GetUniqueId") else None
+        clip_id = clip.GetUniqueId() if _has_method(clip, "GetUniqueId") else None
+        media_id = clip.GetMediaId() if _has_method(clip, "GetMediaId") else None
         source_file = None
         try:
-            source_file = clip.GetClipProperty("File Path") if hasattr(clip, "GetClipProperty") else None
+            source_file = clip.GetClipProperty("File Path") if _has_method(clip, "GetClipProperty") else None
         except Exception:
             source_file = None
         return _mark_analysis_registry_stale(
@@ -930,9 +930,10 @@ def perform_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "PerformAudioClassification"):
-        return {"error": "PerformAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.PerformAudioClassification())}
+    missing = _requires_method(clip, "PerformAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.PerformAudioClassification())
 
 
 @mcp.tool()
@@ -948,9 +949,10 @@ def clear_clip_audio_classification(clip_id: str) -> Dict[str, Any]:
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "ClearAudioClassification"):
-        return {"error": "ClearAudioClassification requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.ClearAudioClassification())}
+    missing = _requires_method(clip, "ClearAudioClassification", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.ClearAudioClassification())
 
 
 @mcp.tool()
@@ -968,9 +970,10 @@ def analyze_clip_for_intellisearch(clip_id: str, identify_faces: bool = False, i
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "AnalyzeForIntellisearch"):
-        return {"error": "AnalyzeForIntellisearch requires DaVinci Resolve 21+"}
-    return {"success": bool(clip.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))}
+    missing = _requires_method(clip, "AnalyzeForIntellisearch", "21.0")
+    if missing:
+        return missing
+    return _ai_result_payload(clip.AnalyzeForIntellisearch(bool(identify_faces), bool(is_better_mode)))
 
 
 @mcp.tool()
@@ -988,11 +991,12 @@ def analyze_clip_for_slate(clip_id: str, marker_color: str = "Blue") -> Dict[str
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "AnalyzeForSlate"):
-        return {"error": "AnalyzeForSlate requires DaVinci Resolve 21+"}
+    missing = _requires_method(clip, "AnalyzeForSlate", "21.0")
+    if missing:
+        return missing
     if marker_color not in _MARKER_COLORS:
         return {"error": f"Invalid marker_color '{marker_color}'. Valid: {', '.join(_MARKER_COLORS)}"}
-    return {"success": bool(clip.AnalyzeForSlate(marker_color))}
+    return _ai_result_payload(clip.AnalyzeForSlate(marker_color))
 
 
 @mcp.tool()
@@ -1012,11 +1016,15 @@ def remove_clip_motion_blur(clip_id: str, deblur_option: Optional[Dict[str, Any]
     clip = _find_clip_by_id(mp.GetRootFolder(), clip_id)
     if not clip:
         return {"error": f"Clip {clip_id} not found"}
-    if not hasattr(clip, "RemoveMotionBlur"):
-        return {"error": "RemoveMotionBlur requires DaVinci Resolve 21+"}
+    missing = _requires_method(clip, "RemoveMotionBlur", "21.0")
+    if missing:
+        return missing
     new_clip = clip.RemoveMotionBlur(deblur_option or {})
-    if not new_clip:
-        return {"success": False}
+    # An error string is truthy, so a bare `if not new_clip` let a missing
+    # Extras pack through to .GetName() and raised AttributeError.
+    ok, message = _ai_result(new_clip)
+    if not ok:
+        return {"success": False, "error": message} if message else {"success": False}
     return {"success": True, "new": new_clip.GetName(), "new_id": new_clip.GetUniqueId()}
 
 

package/src/granular/project.py

@@ -192,7 +192,7 @@ def save_project() -> str:
     try:
         # Method 1: Try direct save method if available
         try:
-            if hasattr(current_project, "SaveProject"):
+            if _has_method(current_project, "SaveProject"):
                 result = current_project.SaveProject()
                 if result:
                     logger.info(f"Project '{project_name}' saved using SaveProject method")
@@ -204,7 +204,7 @@ def save_project() -> str:
         # Method 2: Try project manager save method
         if not success:
             try:
-                if hasattr(project_manager, "SaveProject"):
+                if _has_method(project_manager, "SaveProject"):
                     result = project_manager.SaveProject()
                     if result:
                         logger.info(f"Project '{project_name}' saved using ProjectManager.SaveProject method")
@@ -1640,8 +1640,9 @@ def generate_speech(text_input: str, voice_model: str = "", timecode: str = "",
     pm, current_project = get_current_project()
     if not current_project:
         return {"error": "No project currently open"}
-    if not hasattr(current_project, "GenerateSpeech"):
-        return {"error": "GenerateSpeech requires DaVinci Resolve 21+ and the AI Speech Generator Extra"}
+    missing = _requires_method(current_project, "GenerateSpeech", "21.0")
+    if missing:
+        return missing
     if not text_input:
         return {"error": "text_input is required"}
     settings: Dict[str, Any] = {"TextInput": text_input}
@@ -1664,8 +1665,12 @@ def generate_speech(text_input: str, voice_model: str = "", timecode: str = "",
         if audio_track is not None:
             settings["AudioTrack"] = audio_track
     new_item = current_project.GenerateSpeech(settings, timecode or "")
-    if not new_item:
-        return {"success": False, "error": "GenerateSpeech returned no media item"}
+    # Without the AI Speech Generator Extra this returns the reason as a STRING,
+    # which is truthy — the old check passed it through to .GetName().
+    ok, message = _ai_result(new_item)
+    if not ok:
+        return {"success": False,
+                "error": message or "GenerateSpeech returned no media item"}
     return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId()}
 
 

package/src/granular/resolve_control.py

@@ -186,10 +186,12 @@ def inspect_custom_object(object_path: str) -> Dict[str, Any]:
                     return {"error": f"Method '{method_name}' not found or not callable"}
             else:
                 # It's an attribute access
-                if hasattr(obj, part):
-                    obj = getattr(obj, part)
-                else:
+                # getattr, not hasattr: on a Resolve object hasattr is a
+                # constant True, so the not-found branch could never run.
+                value = getattr(obj, part, None)
+                if value is None:
                     return {"error": f"Attribute '{part}' not found"}
+                obj = value
         
         # Inspect the object we've retrieved
         return inspect_object(obj)
@@ -399,7 +401,19 @@ def get_resolve_version_fields() -> Dict[str, Any]:
         return {"error": "Not connected to DaVinci Resolve"}
     version = resolve.GetVersion()
     if version:
-        return {"major": version[0], "minor": version[1], "patch": version[2], "build": version[3], "suffix": version[4] if len(version) > 4 else ""}
+        # Carry what this build is MISSING, not just what it is. An agent that
+        # only learns the number still has to know which surfaces that number
+        # rules out, and guessing that is issue #132.
+        missing = gates_unavailable_on(resolve.GetVersionString())
+        return {"major": version[0], "minor": version[1], "patch": version[2], "build": version[3],
+                "suffix": version[4] if len(version) > 4 else "",
+                "unavailable_on_this_build": missing,
+                "note": ("Recorded surfaces absent here — do not offer them. An absence "
+                         "from this list is not a promise a method exists; most of the "
+                         "API has never been version-bisected."
+                         if missing else
+                         "Clears every recorded version gate. Surfaces nobody has "
+                         "bisected are still unknown — probe before offering them.")}
     return {"error": "Failed to get version"}
 
 

package/src/granular/timeline.py

@@ -655,8 +655,8 @@ def timeline_create_compound_clip(
         return {"success": False, "error": "Failed to create compound clip"}
     return {
         "success": True,
-        "name": result.GetName() if hasattr(result, "GetName") else None,
-        "unique_id": result.GetUniqueId() if hasattr(result, "GetUniqueId") else None,
+        "name": result.GetName() if _has_method(result, "GetName") else None,
+        "unique_id": result.GetUniqueId() if _has_method(result, "GetUniqueId") else None,
     }
 
 
@@ -714,8 +714,11 @@ def timeline_export(file_path: str, export_type: str, export_subtype: str = "EXP
         return err
     # Map string constants to resolve constants
     try:
-        etype = getattr(resolve, export_type) if hasattr(resolve, export_type) else export_type
-        esub = getattr(resolve, export_subtype) if hasattr(resolve, export_subtype) else export_subtype
+        # Fall back on the VALUE, not on hasattr: hasattr is a constant True
+        # here, so a build without the constant used to hand Export a None
+        # instead of the string name the fallback was written to pass through.
+        etype = _api_constant(resolve, export_type, export_type)
+        esub = _api_constant(resolve, export_subtype, export_subtype)
     except Exception:
         logger.debug("Could not resolve timeline export constants", exc_info=True)
         etype = export_type

package/src/granular/timeline_item.py

@@ -2118,7 +2118,7 @@ def ti_export_lut(export_type: str, path: str, item_index: int = 0, track_type:
     if err:
         return err
     try:
-        etype = getattr(resolve, export_type) if hasattr(resolve, export_type) else export_type
+        etype = _api_constant(resolve, export_type, export_type)
     except Exception:
         etype = export_type
     return {"success": bool(item.ExportLUT(etype, path))}

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.88.0"
+VERSION = "2.89.0"
 
 import base64
 import os
@@ -48,6 +48,7 @@ from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
 from src.utils import clip_colors as _clip_colors
 from src.utils import resolve_versions as _resolve_versions
+from src.utils.resolve_probe import api_constant as _api_constant, has_method as _probe_has_method
 from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
@@ -1032,7 +1033,7 @@ def _destructive_versioning_provider() -> Optional[Tuple[Any, Any, str, Optional
         except Exception:
             project_name = None
         try:
-            project_id = proj.GetUniqueId() if hasattr(proj, "GetUniqueId") else None
+            project_id = proj.GetUniqueId() if _has_method(proj, "GetUniqueId") else None
         except Exception:
             project_id = None
         root = resolve_media_analysis_output_root(
@@ -1785,7 +1786,8 @@ def _send_resolve_keystroke_go_to_mark_in() -> Dict[str, Any]:
         return {"sent": False, "error": f"{type(exc).__name__}: {exc}"}
 
 def _has_method(obj, method_name):
-    return callable(getattr(obj, method_name, None))
+    # `hasattr` is a constant True on Resolve objects — see src/utils/resolve_probe.
+    return _probe_has_method(obj, method_name)
 
 def _requires_method(obj, method_name, min_version):
     if _has_method(obj, method_name):
@@ -5901,10 +5903,11 @@ def _timeline_export_value(value, resolve_obj=None):
     if not raw:
         return "", None
     const_name = raw if raw.startswith("EXPORT_") else None
-    if const_name and resolve_obj is not None and hasattr(resolve_obj, const_name):
-        return getattr(resolve_obj, const_name), const_name
     if const_name:
-        return const_name, const_name
+        # hasattr is a constant True on a Resolve object, so the old presence
+        # test always won and handed Export a None from getattr on a build
+        # without the constant. Fall back on the value instead.
+        return _api_constant(resolve_obj, const_name, const_name), const_name
     return raw, None
 
 
@@ -7383,9 +7386,7 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
 
 
 def _resolve_audio_constant(resolve_obj, name: str, fallback):
-    if resolve_obj is not None and hasattr(resolve_obj, name):
-        return getattr(resolve_obj, name)
-    return fallback
+    return _api_constant(resolve_obj, name, fallback)
 
 
 def _normalize_auto_sync_settings(settings: Dict[str, Any], resolve_obj=None):
@@ -13787,10 +13788,33 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "get_version":
         update_env = _setup_update_env()
         mcp_update = get_cached_update_status(project_dir, VERSION, env=update_env)
+        version_string = r.GetVersionString()
+        # The first call of nearly every session. Issue #132 is the report of an
+        # agent describing a surface that was not on the user's build, and the
+        # reason it could happen is that nothing in the session ever said which
+        # build that was in terms of what is missing from it. So the answer to
+        # "what am I connected to" now carries what this build does not have,
+        # rather than waiting to be asked.
+        missing = _resolve_versions.gates_unavailable_on(version_string)
         return {
             "product": r.GetProductName(),
             "version": r.GetVersion(),
-            "version_string": r.GetVersionString(),
+            "version_string": version_string,
+            "build": {
+                "unavailable_on_this_build": missing,
+                "known_gates": len(_resolve_versions.VERSION_GATES),
+                "note": (
+                    f"{len(missing)} recorded surface(s) are absent on this build. "
+                    "Do not offer them. An absence from this list is NOT a promise "
+                    "the method exists — most of the scripting API has never been "
+                    "version-bisected, so ask check_version_support for a specific "
+                    "symbol and probe when it answers `unknown`."
+                    if missing else
+                    "This build clears every recorded version gate. That is not a "
+                    "promise about surfaces nobody has bisected — ask "
+                    "check_version_support for a specific symbol before offering it."
+                ),
+            },
             "mcp": {
                 "version": VERSION,
                 "update": mcp_update,
@@ -22792,9 +22816,7 @@ def _resolve_lut_export_type(export_type, resolve_obj=None):
         const_name = raw
     if not const_name:
         return None, _err(f"Unknown LUT export type: {raw}")
-    if resolve_obj and hasattr(resolve_obj, const_name):
-        return getattr(resolve_obj, const_name), None
-    return const_name, None
+    return _api_constant(resolve_obj, const_name, const_name), None
 
 
 def _validate_cdl_payload(cdl):
@@ -27636,7 +27658,7 @@ def _resource_current_project() -> Dict[str, Any]:
     return {
         "open": True,
         "name": proj.GetName(),
-        "id": proj.GetUniqueId() if hasattr(proj, "GetUniqueId") else None,
+        "id": proj.GetUniqueId() if _has_method(proj, "GetUniqueId") else None,
     }
 
 
@@ -27659,7 +27681,7 @@ def _resource_current_timeline() -> Dict[str, Any]:
     return {
         "open": True,
         "name": tl.GetName(),
-        "id": tl.GetUniqueId() if hasattr(tl, "GetUniqueId") else None,
+        "id": tl.GetUniqueId() if _has_method(tl, "GetUniqueId") else None,
         "start_frame": tl.GetStartFrame(),
         "end_frame": tl.GetEndFrame(),
         "start_timecode": tl.GetStartTimecode(),

package/src/utils/cloud_operations.py

@@ -9,6 +9,8 @@ the Resolve scripting API.
 import logging
 from typing import Any, Dict, Optional
 
+from src.utils.resolve_probe import has_method
+
 logger = logging.getLogger("davinci-resolve-mcp.cloud_operations")
 
 
@@ -63,7 +65,7 @@ def _project_manager(resolve_obj, method_name: str):
     pm = resolve_obj.GetProjectManager()
     if not pm:
         return None, {"success": False, "error": "Failed to get Project Manager"}
-    if not hasattr(pm, method_name):
+    if not has_method(pm, method_name):
         return None, {
             "success": False,
             "error": f"{method_name} not available in this version of DaVinci Resolve",
@@ -98,7 +100,7 @@ def create_cloud_project(
     return {
         "success": True,
         "project_name": project.GetName(),
-        "project_id": project.GetUniqueId() if hasattr(project, "GetUniqueId") else None,
+        "project_id": project.GetUniqueId() if has_method(project, "GetUniqueId") else None,
     }
 
 
@@ -132,7 +134,7 @@ def load_cloud_project(
     return {
         "success": True,
         "project_name": project.GetName(),
-        "project_id": project.GetUniqueId() if hasattr(project, "GetUniqueId") else None,
+        "project_id": project.GetUniqueId() if has_method(project, "GetUniqueId") else None,
     }
 
 

package/src/utils/object_inspection.py

@@ -14,6 +14,8 @@ import inspect
 import logging
 from typing import Any, Dict, List, Optional, Union, Callable
 
+from src.utils.resolve_probe import has_method
+
 logger = logging.getLogger(__name__)
 
 
@@ -170,7 +172,7 @@ def get_lua_table_keys(lua_table: Any) -> List[str]:
     keys = []
     
     # Check for DaVinci-specific Lua table iteration methods
-    if hasattr(lua_table, 'GetKeyList'):
+    if has_method(lua_table, 'GetKeyList'):
         try:
             # Some DaVinci Resolve objects have a GetKeyList() method
             return lua_table.GetKeyList()
@@ -210,7 +212,7 @@ def convert_lua_to_python(lua_obj: Any) -> Any:
         return lua_obj
         
     # Try to convert Lua tables to Python dicts or lists
-    if hasattr(lua_obj, 'GetKeyList') or hasattr(lua_obj, '__iter__'):
+    if has_method(lua_obj, 'GetKeyList') or hasattr(lua_obj, '__iter__'):
         keys = get_lua_table_keys(lua_obj)
         
         # If we found keys, convert to dict

package/src/utils/project_properties.py

@@ -13,6 +13,8 @@ import logging
 import json
 from typing import Dict, List, Any, Optional, Union
 
+from src.utils.resolve_probe import has_method
+
 # Configure logging
 logger = logging.getLogger("davinci-resolve-mcp.project_properties")
 
@@ -521,7 +523,7 @@ def get_project_metadata(project_obj) -> Dict[str, Any]:
         metadata["name"] = project_obj.GetName()
         
         # Add project path if available
-        if hasattr(project_obj, "GetPath"):
+        if has_method(project_obj, "GetPath"):
             metadata["path"] = project_obj.GetPath()
         
         # Get current timeline

package/src/utils/resolve_probe.py

@@ -0,0 +1,68 @@
+"""Capability probes for DaVinci Resolve API objects, because `hasattr` lies.
+
+Measured on Studio 19.1.3.7, direct connection, 42 checks across Resolve,
+ProjectManager, Project, MediaPool, Timeline, Folder and TimelineItem: bare
+`hasattr(obj, name)` returns **True for every name** — real, borrowed from
+another object type, or entirely invented — while `getattr(obj, name)` returns
+`None` for the ones that do not exist. The full record is in `api_truth` under
+"hasattr() / getattr() on Resolve API objects (attribute fabrication)".
+
+So `hasattr` on a Resolve object is a constant `True`. It carries no
+information, and it fails in two directions that look nothing alike:
+
+    if not hasattr(clip, "RemoveMotionBlur"):        # never taken
+        return {"error": "requires Resolve 21+"}     # dead branch
+    clip.RemoveMotionBlur(...)                       # AttributeError on 19.x
+
+    etype = getattr(r, name) if hasattr(r, name) else name   # else never taken
+    # -> etype is None on a build without that constant, not the string
+    #    fallback the author wrote, and None flows on into the export call.
+
+The second shape is the dangerous one: no exception, no refusal, just a `None`
+travelling further from the mistake with every line.
+
+Use `has_method` where the intent is "can I call this", and `api_constant`
+where the intent is "does this build define this constant, else use my
+fallback". Both take the form that agreed with `dir()` in all 42 checks.
+
+One caveat worth keeping: those 42 checks were on the DIRECT connection. The
+21.0.0 record of the in-app bridge fabricating callables for any name was never
+re-run, so on a bridge build `callable(getattr(...))` may still over-report.
+`dir()` membership is the form unaffected either way — but it is not free on
+every object, and switching to it wholesale would change behaviour on a path we
+have not measured. That trade is recorded here rather than made silently.
+"""
+
+from typing import Any, Optional
+
+__all__ = ["has_method", "api_constant", "MISSING"]
+
+#: Sentinel for "no attribute", distinct from a legitimately-None attribute.
+MISSING = object()
+
+
+def has_method(obj: Any, name: str) -> bool:
+    """True when `name` is a callable on `obj`. The replacement for `hasattr`.
+
+    Returns False for a missing object rather than raising, because every
+    caller here is asking "is this reachable" and a None handle is one of the
+    ways it is not.
+    """
+    if obj is None or not name:
+        return False
+    return callable(getattr(obj, name, None))
+
+
+def api_constant(obj: Any, name: str, default: Optional[Any] = None) -> Any:
+    """The Resolve constant `name`, or `default` when this build lacks it.
+
+    Resolve exposes export/audio type constants as plain attributes
+    (`resolve.EXPORT_AAF`), and callers pass the string name through unchanged
+    when the constant is absent. `getattr` returning None is exactly the signal
+    `hasattr` destroys, so the fallback is driven off the value, not off a
+    presence test.
+    """
+    if obj is None or not name:
+        return default
+    value = getattr(obj, name, None)
+    return default if value is None else value

package/src/utils/resolve_versions.py

@@ -102,11 +102,13 @@ def at_least(live: Any, required: Any) -> Optional[bool]:
 # measured from what a reporter measured, because the two carry different
 # weight and an agent relaying the fact should be able to say which it is.
 #
-#   measured  — probed live by this project
-#   reported  — a user's live probe, credited, not independently reproduced
-#   vendor    — stated by Blackmagic's shipped Developer/Scripting/README.txt
+#   measured   — probed live by this project
+#   reported   — a user's live probe, credited, not independently reproduced
+#   vendor     — stated by Blackmagic's shipped Developer/Scripting/README.txt
+#   documented — a floor this server already enforces at the call site, taken
+#                from Blackmagic's release documentation. See CODE_FLOORS.
 
-VERSION_GATES: List[Dict[str, Any]] = [
+_EVIDENCE_GATES: List[Dict[str, Any]] = [
     {
         "symbol": "Resolve.GetFairlightPresets",
         "introduced_in": "20.2.2",
@@ -117,7 +119,11 @@ VERSION_GATES: List[Dict[str, Any]] = [
         "issue": 128,
     },
     {
-        "symbol": "Timeline.ApplyFairlightPresetToCurrentTimeline",
+        # Named on Project, not Timeline: the shipped README lists it in the
+        # Project section and src/server.py calls it on the project handle. The
+        # method's name says "CurrentTimeline", which is what made the earlier
+        # Timeline attribution here look right.
+        "symbol": "Project.ApplyFairlightPresetToCurrentTimeline",
         "introduced_in": "20.2.2",
         "source": "measured",
         "note": "Same gate as GetFairlightPresets; the two are only useful together.",
@@ -166,6 +172,90 @@ VERSION_GATES: List[Dict[str, Any]] = [
     },
 ]
 
+
+# ── Floors this server already enforces ─────────────────────────────────────
+# `_requires_method(obj, "Method", "X.Y")` in src/server.py and src/granular/
+# refuses a call when the method is absent and names a floor. Those floors were
+# real routing knowledge that `check_version_support` could not see: the ledger
+# above knew seven symbols while the two servers gated thirty-one, so the one
+# call an agent is told to make answered `unknown` for surfaces this repo was
+# already routing on. That is the shape of issue #132 — guidance that does not
+# vary with the build it is connected to — showing up inside our own tooling.
+#
+# The `documented` label is deliberately weaker than `measured`. These floors
+# come from Blackmagic's release documentation (the build whose shipped
+# Developer/Scripting README first carried the method), not from a live bisect
+# by this project, so an agent relaying one should say "documented as requiring
+# 21.0.4+", never "measured absent on your build". A floor being wrong in the
+# vendor's direction is survivable — the call-site guard still probes the live
+# object before refusing, so the floor only ever supplies the *explanation*.
+#
+# tests/test_version_gate_drift.py fails when a call site and this table
+# disagree, which is what keeps the two from drifting apart again.
+
+CODE_FLOORS: Dict[str, str] = {
+    "MediaPoolItem.LinkProxyMedia": "17.0",
+    "MediaPoolItem.LinkFullResolutionMedia": "20.0",
+    "MediaPoolItem.MonitorGrowingFile": "20.0",
+    "MediaPoolItem.ReplaceClipPreserveSubClip": "20.0",
+    "Timeline.GetVoiceIsolationState": "20.1",
+    "Timeline.SetVoiceIsolationState": "20.1",
+    "TimelineItem.GetVoiceIsolationState": "20.1",
+    "TimelineItem.SetVoiceIsolationState": "20.1",
+    "MediaPoolItem.SetName": "20.2",
+    "TimelineItem.SetName": "20.2",
+    "TimelineItem.ResetAllNodeColors": "20.2",
+    "Resolve.DisableBackgroundTasksForCurrentResolveSession": "21.0",
+    "Project.GenerateSpeech": "21.0",
+    "Project.ResetIntellisearchAnalysis": "21.0",
+    "MediaPoolItem.PerformAudioClassification": "21.0",
+    "MediaPoolItem.ClearAudioClassification": "21.0",
+    "MediaPoolItem.AnalyzeForIntellisearch": "21.0",
+    "MediaPoolItem.AnalyzeForSlate": "21.0",
+    "MediaPoolItem.RemoveMotionBlur": "21.0",
+    "Folder.PerformAudioClassification": "21.0",
+    "Folder.ClearAudioClassification": "21.0",
+    "Folder.AnalyzeForIntellisearch": "21.0",
+    "Folder.AnalyzeForSlate": "21.0",
+    "Folder.RemoveMotionBlur": "21.0",
+    "Resolve.GetLayoutPresetList": "21.0.4",
+    "Resolve.GetBurnInPresetList": "21.0.4",
+    "Resolve.DeleteBurnInPreset": "21.0.4",
+    "Resolve.GetUserPreferencesPresetList": "21.0.4",
+    "Resolve.SaveUserPreferencesPreset": "21.0.4",
+    "Resolve.LoadUserPreferencesPreset": "21.0.4",
+    "Resolve.DeleteUserPreferencesPreset": "21.0.4",
+    "Resolve.ImportUserPreferencesPreset": "21.0.4",
+    "Resolve.ExportUserPreferencesPreset": "21.0.4",
+    "ProjectManager.GetProjectAttributesInCurrentFolder": "21.0.4",
+}
+
+#: Methods whose call-site guard names no usable floor. Recorded rather than
+#: silently dropped, because "we gate this and cannot say since when" is itself
+#: worth an agent knowing — it is a candidate for the next live bisect.
+UNDATED_FLOORS: Tuple[str, ...] = ("Project.GetRenderSettings",)
+
+_EVIDENCE_SYMBOLS = {gate["symbol"] for gate in _EVIDENCE_GATES}
+
+VERSION_GATES: List[Dict[str, Any]] = _EVIDENCE_GATES + [
+    {
+        "symbol": symbol,
+        "introduced_in": floor,
+        "source": "documented",
+        "note": (
+            "Floor enforced at this server's call site, from Blackmagic's "
+            "release documentation rather than a live bisect here. The guard "
+            "probes the live object first, so this supplies the explanation, "
+            "not the refusal."
+        ),
+        "issue": 132,
+    }
+    for symbol, floor in sorted(CODE_FLOORS.items())
+    # An evidence-backed entry always wins: it says how we know, and these
+    # would overwrite that with the weaker label.
+    if symbol not in _EVIDENCE_SYMBOLS
+]
+
 _GATES_BY_SYMBOL = {gate["symbol"].lower(): gate for gate in VERSION_GATES}
 
 AVAILABLE = "available"
@@ -174,12 +264,24 @@ UNKNOWN = "unknown"
 
 
 def gate_for(symbol: str) -> Optional[Dict[str, Any]]:
-    """The recorded gate for `symbol`, matched loosely. None if we have none."""
+    """The recorded gate for `symbol`, matched loosely. None if we have none.
+
+    Tried in order — exact, then bare method name, then substring — because the
+    registry now carries the same method on several classes (`SetName` is gated
+    on four). Iteration order decided which one a bare `"SetName"` lookup hit
+    when the registry was small enough for that not to matter; it now is not.
+    A bare name matching several classes only stays honest while their floors
+    agree, which `test_version_gate_drift` asserts.
+    """
     if not symbol:
         return None
     needle = symbol.strip().lower()
     if needle in _GATES_BY_SYMBOL:
         return _GATES_BY_SYMBOL[needle]
+    suffix = "." + needle
+    for key, gate in _GATES_BY_SYMBOL.items():
+        if key.endswith(suffix):
+            return gate
     for key, gate in _GATES_BY_SYMBOL.items():
         if needle in key or key in needle:
             return gate

package/src/utils/timeline_kernel_live_probe.py

@@ -17,6 +17,8 @@ import platform
 import subprocess
 import sys
 import tempfile
+
+from src.utils.resolve_probe import has_method
 import time
 import types
 import traceback
@@ -153,7 +155,7 @@ def _frame_int(value) -> int:
 
 
 def _source_start(item) -> int:
-    if hasattr(item, "GetSourceStartFrame"):
+    if has_method(item, "GetSourceStartFrame"):
         try:
             value = item.GetSourceStartFrame()
             if value is not None:

package/src/utils/timeline_versioning.py

@@ -30,6 +30,8 @@ import os
 import re
 import time
 import uuid
+
+from src.utils.resolve_probe import has_method
 from typing import Any, Dict, List, Optional, Tuple
 
 from src.utils import actor_identity, timeline_brain_db
@@ -280,12 +282,12 @@ def _resolve_media_pool_item_id(item: Any) -> Optional[str]:
     """
     try:
         mpi = item.GetMediaPoolItem()
-        if mpi is not None and hasattr(mpi, "GetUniqueId"):
+        if has_method(mpi, "GetUniqueId"):
             return str(mpi.GetUniqueId())
     except Exception:
         pass
     try:
-        return str(item.GetUniqueId()) if hasattr(item, "GetUniqueId") else None
+        return str(item.GetUniqueId()) if has_method(item, "GetUniqueId") else None
     except Exception:
         return None