davinci-resolve-mcp 2.71.0 → 2.72.0

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.71.0"
+VERSION = "2.72.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.71.0",
+  "version": "2.72.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.71.0"
+VERSION = "2.72.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.71.0"
+VERSION = "2.72.0"
 
 import base64
 import os
@@ -1784,6 +1784,36 @@ def _requires_method(obj, method_name, min_version):
         return None
     return _err(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. Route every AI return through here instead: a string
+    is always a failure, and its text is the reason worth surfacing.
+    """
+    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
+
 def _is_truncated(text):
     """True if a transcription preview was cut off.
 
@@ -3795,6 +3825,81 @@ def _timeline_item_ids(items):
     return ids
 
 
+def _timeline_items_presence(tl, items):
+    """Are these timeline items still on the timeline? present/absent/unknown.
+
+    'absent' is a positive finding: every item was identifiable and a
+    completed track walk did not see any of them. A walk that raised, that
+    could not enumerate a single track, or items whose unique ID cannot be
+    read all yield 'unknown' — the readback saw nothing, which is not the
+    same as nothing being there. Callers must never treat 'unknown' as
+    verified-gone.
+    """
+    target_ids = []
+    unreadable_item = False
+    for item in items:
+        item_id = _safe_timeline_item_id(item)
+        if item_id:
+            target_ids.append(item_id)
+        else:
+            unreadable_item = True
+    target_ids = set(target_ids)
+
+    tracks_walked = 0
+    walk_failed = False
+    for track_type in ("video", "audio", "subtitle"):
+        try:
+            track_count = int(tl.GetTrackCount(track_type) or 0)
+        except Exception:
+            walk_failed = True
+            continue
+        for index in range(1, track_count + 1):
+            try:
+                track_items = tl.GetItemListInTrack(track_type, index) or []
+            except Exception:
+                walk_failed = True
+                continue
+            tracks_walked += 1
+            for track_item in track_items:
+                # A sighting is definitive even if another track failed.
+                if _safe_timeline_item_id(track_item) in target_ids:
+                    return "present"
+
+    if walk_failed or tracks_walked == 0 or unreadable_item or not target_ids:
+        return "unknown"
+    return "absent"
+
+
+def _timeline_delete_clips_verified(tl, items, ripple):
+    """Timeline.DeleteClips with readback-and-retry.
+
+    api_truth 'Timeline.DeleteClips (flaky first attempt)': the call can
+    return False while every item is still present, and an identical retry
+    then succeeds. On a False, read the tracks back:
+
+      absent  -> the delete landed despite the False; report success.
+      present -> retry the identical call once, then read back again.
+      unknown -> report failure and do NOT retry. An unverifiable delete must
+                 not be claimed as success, and a retry whose outcome we
+                 equally cannot read is a second destructive call bought with
+                 no information.
+
+    ripple=True caveat: a retry is not idempotent in principle. If the first
+    call deleted some items and left others, the readback reports 'present'
+    for the survivors and the retry passes the original list back in — stale
+    handles to already-deleted items included. That could not be made to
+    misbehave against a fake; it is recorded, not resolved.
+    """
+    if bool(tl.DeleteClips(items, ripple)):
+        return True
+    presence = _timeline_items_presence(tl, items)
+    if presence != "present":
+        return presence == "absent"
+    if bool(tl.DeleteClips(items, ripple)):
+        return True
+    return _timeline_items_presence(tl, items) == "absent"
+
+
 def _timeline_items_by_ids(tl, ids, track_types=("video", "audio", "subtitle")):
     ids_set = {str(item_id) for item_id in ids if item_id is not None}
     found = []
@@ -4168,7 +4273,7 @@ def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_source
                 seen_delete_ids.add(item_id)
         if delete_items:
             try:
-                out["deleted_sources"] = bool(tl.DeleteClips(delete_items, bool(p.get("ripple", False))))
+                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)))
                 out["deleted_source_ids"] = _timeline_item_ids(delete_items)
             except Exception as exc:
                 out["deleted_sources"] = False
@@ -4283,7 +4388,7 @@ def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool =
                     if existing_start < dest_end and existing_end > dest_start:
                         delete_targets.append(existing)
         if delete_targets:
-            deleted = bool(tl.DeleteClips(delete_targets, False))
+            deleted = _timeline_delete_clips_verified(tl, delete_targets, False)
 
     results = []
     for track_type, source_track, item, overlap_start, overlap_end in items:
@@ -4376,7 +4481,7 @@ def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
         return {"success": True, "deleted": 0, "range": {"start": start, "end": end}}
     deleted_ids = _timeline_item_ids(delete_items)
     return {
-        "success": bool(tl.DeleteClips(delete_items, bool(p.get("ripple", False)))),
+        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False))),
         "deleted": len(delete_items),
         "deleted_ids": deleted_ids,
         "range": {"start": start, "end": end},
@@ -15384,6 +15489,7 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
       delete_color_group(name) -> {success}
       apply_fairlight_preset(preset_name) -> {success}
       generate_speech(speech_generation_settings, timecode?) -> {success, new, new_id}  — Resolve 21+, AI Speech Generator; creates new audio media (confirm-gated)
+      reset_intellisearch_analysis() -> {success}  — Resolve 21+; clears the project's IntelliSearch analysis data
     """
     p = _params(params)
     _, proj, err = _check()
@@ -15482,16 +15588,29 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
             return blocked
         with _ai_ledger_timed("generate_speech") as _rec:
             new_item = proj.GenerateSpeech(settings, timecode)
-            _rec.success = bool(new_item)
-            if new_item:
+            # GenerateSpeech returns an error STRING when the AI Speech Generator
+            # Extra is absent (verified on Studio 21.0.2.4), not a MediaPoolItem.
+            # A bare truthiness test lets that string through to .GetName() and
+            # raises AttributeError, so normalize before touching the result.
+            ok, message = _ai_result(new_item)
+            _rec.success = ok
+            if ok:
                 path, nbytes = _clip_file_size(new_item)
                 _rec.output_path = path
                 _rec.output_bytes = nbytes
-        if not new_item:
-            return {"success": False}
+        if not ok:
+            return {"success": False, "error": message} if message else {"success": False}
         return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId(),
                 "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
-    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","project_summary","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech"])
+    elif action == "reset_intellisearch_analysis":
+        missing = _requires_method(proj, "ResetIntellisearchAnalysis", "21.0")
+        if missing:
+            return missing
+        with _ai_ledger_timed("reset_intellisearch_analysis") as _rec:
+            result = _ai_result_payload(proj.ResetIntellisearchAnalysis())
+            _rec.success = result["success"]
+        return result
+    return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","project_summary","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech","reset_intellisearch_analysis"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -16931,17 +17050,17 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if missing:
             return missing
         with _ai_ledger_timed("perform_audio_classification") as _rec:
-            ok = bool(f.PerformAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.PerformAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "clear_audio_classification":
         missing = _requires_method(f, "ClearAudioClassification", "21.0")
         if missing:
             return missing
         with _ai_ledger_timed("clear_audio_classification") as _rec:
-            ok = bool(f.ClearAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.ClearAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(f, "AnalyzeForIntellisearch", "21.0")
         if missing:
@@ -16949,9 +17068,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
         with _ai_ledger_timed("analyze_for_intellisearch") as _rec:
-            ok = bool(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_slate":
         missing = _requires_method(f, "AnalyzeForSlate", "21.0")
         if missing:
@@ -16960,9 +17079,9 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
         with _ai_ledger_timed("analyze_for_slate") as _rec:
-            ok = bool(f.AnalyzeForSlate(marker_color))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(f.AnalyzeForSlate(marker_color))
+            _rec.success = result["success"]
+        return result
     elif action == "remove_motion_blur":
         missing = _requires_method(f, "RemoveMotionBlur", "21.0")
         if missing:
@@ -16987,11 +17106,18 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if blocked:
             return blocked
         with _ai_ledger_timed("remove_motion_blur") as _rec:
+            # RemoveMotionBlur needs the AI Motion Deblur Extra, so it belongs to
+            # the same family as the methods above: absent the pack, the return
+            # can be an error STRING rather than the documented list. Iterating a
+            # string yields characters, the pair-unpack raises, `except Exception`
+            # swallows it, and the action reported success:true with created:[]
+            # — a silent lie in the confirm-gated path that renders new media.
             result = f.RemoveMotionBlur(deblur)
-            _rec.success = bool(result)
+            ok, message = _ai_result(result)
+            _rec.success = ok
             created = []
             total_bytes = 0
-            for pair in (result or []):
+            for pair in (result or []) if ok else []:
                 try:
                     orig, new = pair
                     path, nbytes = _clip_file_size(new)
@@ -17005,7 +17131,10 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
             if created:
                 _rec.output_path = created[0].get("output_path")
                 _rec.output_bytes = total_bytes or None
-        return {"success": bool(result), "created": created}
+        payload = {"success": ok, "created": created}
+        if message:
+            payload["error"] = message
+        return payload
     return _unknown(action, ["get_clips","get_name","get_subfolders","is_stale","get_unique_id","export","transcribe_audio","clear_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur"])
 
 
@@ -17329,17 +17458,17 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if missing:
             return missing
         with _ai_ledger_timed("perform_audio_classification", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.PerformAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.PerformAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "clear_audio_classification":
         missing = _requires_method(clip, "ClearAudioClassification", "21.0")
         if missing:
             return missing
         with _ai_ledger_timed("clear_audio_classification", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.ClearAudioClassification())
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.ClearAudioClassification())
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(clip, "AnalyzeForIntellisearch", "21.0")
         if missing:
@@ -17347,9 +17476,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
         with _ai_ledger_timed("analyze_for_intellisearch", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = result["success"]
+        return result
     elif action == "analyze_for_slate":
         missing = _requires_method(clip, "AnalyzeForSlate", "21.0")
         if missing:
@@ -17358,9 +17487,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
         with _ai_ledger_timed("analyze_for_slate", clip_id=p.get("clip_id")) as _rec:
-            ok = bool(clip.AnalyzeForSlate(marker_color))
-            _rec.success = ok
-        return {"success": ok}
+            result = _ai_result_payload(clip.AnalyzeForSlate(marker_color))
+            _rec.success = result["success"]
+        return result
     elif action == "remove_motion_blur":
         missing = _requires_method(clip, "RemoveMotionBlur", "21.0")
         if missing:
@@ -17385,14 +17514,19 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if blocked:
             return blocked
         with _ai_ledger_timed("remove_motion_blur", clip_id=p.get("clip_id")) as _rec:
+            # Same shape as generate_speech: a MediaPoolItem return, and an error
+            # STRING when the AI Motion Deblur Extra is absent. `_clip_file_size`
+            # swallows its own AttributeError, so the string survived to
+            # `.GetName()` and raised there instead.
             new_clip = clip.RemoveMotionBlur(deblur)
-            _rec.success = bool(new_clip)
-            if new_clip:
+            ok, message = _ai_result(new_clip)
+            _rec.success = ok
+            if ok:
                 path, nbytes = _clip_file_size(new_clip)
                 _rec.output_path = path
                 _rec.output_bytes = nbytes
-        if not new_clip:
-            return {"success": False}
+        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(),
                 "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
     elif action == "get_audio_mapping":
@@ -20773,7 +20907,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             blocked = _consume_confirm_token(action="timeline.delete_clips_ripple", params=p)
             if blocked:
                 return blocked
-        return {"success": bool(tl.DeleteClips(found, ripple))}
+        return {"success": _timeline_delete_clips_verified(tl, found, ripple)}
     elif action == "set_clips_linked":
         ids_set = set(p["clip_ids"])
         found = []

package/src/utils/api_truth.py

@@ -26,7 +26,7 @@ When you add or change a ``submit``-tagged entry, regenerate the report
 """
 from typing import Any, Dict, List, Optional
 
-VERIFIED_ON = "DaVinci Resolve Studio 21.0.0"
+VERIFIED_ON = "DaVinci Resolve Studio 21.0.2"
 
 # Each entry: symbol, object, reality, recommended, tags. `signature` optional.
 API_TRUTH: List[Dict[str, Any]] = [
@@ -717,18 +717,143 @@ API_TRUTH: List[Dict[str, Any]] = [
     {
         "symbol": "hasattr() / getattr() on Resolve API objects (attribute fabrication)",
         "object": "(all Resolve scripting objects)",
-        "reality": "The Python bridge returns a callable for ANY attribute name, so "
-                   "hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr "
-                   "never raises. This makes capability detection by hasattr "
-                   "impossible — verified on 21.0.0 (hasattr reported SetStart, "
-                   "Razor, AddNode, GenerateProxy, AddSmartBin etc. as present "
-                   "though none exist). Only dir() lists the real methods.",
-        "recommended": "Never probe method existence with hasattr/getattr; test "
-                       "membership against dir(obj) instead. Calling a fabricated "
-                       "method typically returns None/False with no error.",
+        "reality": "UNRESOLVED — the two measurements do not test the same thing. "
+                   "On 21.0.0 the bridge was recorded as returning a callable for "
+                   "ANY attribute name, making capability detection by hasattr "
+                   "impossible; the evidence was REAL API method names borrowed from "
+                   "other object types (SetStart, Razor, AddNode, GenerateProxy, "
+                   "AddSmartBin reported present on objects that do not have them). "
+                   "A 21.0.2.4 control probe of the invented name "
+                   "'TotallyMadeUpMethod_xyz123' returned getattr-callable False on "
+                   "all eight object types, matching dir() in every case. That does "
+                   "NOT refute the 21.0.0 record: if the bridge resolves any name "
+                   "known to the RemoteObject method table rather than literally any "
+                   "string, an invented name is correctly rejected on both builds and "
+                   "the probe never exercised the failing case. Re-running the probe "
+                   "with those five real names is what would settle it; until then, "
+                   "assume fabrication is possible.",
+        "recommended": "Use dir(obj) membership for capability probes. It is correct "
+                       "on every build measured, and it is the only form not affected "
+                       "by whichever way this resolves. server._has_method uses "
+                       "hasattr/getattr and so may over-report on builds where "
+                       "fabrication is live — that is the case _requires_method gates "
+                       "guard, so it matters most exactly where it is least tested. "
+                       "Calling a fabricated method typically returns None/False with "
+                       "no error.",
         "tags": ["bridge", "introspection", "silent-failure"],
         "submit": "bug",
     },
+    {
+        "symbol": "Resolve 21 AI methods (AnalyzeForIntellisearch, GenerateSpeech, "
+                  "AnalyzeForSlate) — inconsistent failure return type",
+        "object": "MediaPoolItem / Folder / Project",
+        "signature": "-> Bool (documented)",
+        "reality": "When the required Extras pack is not installed, these methods do "
+                   "not agree on how they say so, and the documented Bool is not what "
+                   "you get. Verified live on Studio 21.0.2.4 with only AI Motion "
+                   "Deblur installed: AnalyzeForSlate returned False, but "
+                   "AnalyzeForIntellisearch returned the STRING \"Required package 'AI "
+                   "Intellisearch - Faster' is not installed.\" and GenerateSpeech "
+                   "returned the STRING \"Required Package, 'AI Speech Generator' is "
+                   "not Installed.\". A non-empty string is truthy in Python, so "
+                   "bool(result) reports SUCCESS for a call that definitively did not "
+                   "run, and treating GenerateSpeech's return as a MediaPoolItem "
+                   "raises AttributeError: 'str' object has no attribute 'GetName'.",
+        "recommended": "Never bool() an AI-method return directly. Route it through "
+                       "server._ai_result / _ai_result_payload, which treat any string "
+                       "as a failure and surface its text as the error — the message is "
+                       "the only machine-readable signal that an Extras pack is "
+                       "missing, since there is no scripting API to enumerate "
+                       "installed Extras.",
+        "tags": ["ai", "extras", "unreliable-return", "silent-failure", "resolve-21"],
+        "submit": "bug",
+        "mitigation": ["_ai_result", "_ai_result_payload"],
+    },
+    {
+        "symbol": "Installed AI Extras packs are not discoverable from scripting",
+        "object": "Resolve",
+        "reality": "AnalyzeForIntellisearch, AnalyzeForSlate, GenerateSpeech and "
+                   "RemoveMotionBlur each require a separately-downloaded Extras pack, "
+                   "but nothing in the scripting API reports which packs are installed. "
+                   "A caller cannot distinguish 'the Extra is missing' from 'the "
+                   "analysis ran and found nothing' ahead of time; on 21.0.2.4 two of "
+                   "the four leak the reason only as free text in the return value, and "
+                   "AnalyzeForSlate's bare False carries no reason at all.",
+        "recommended": "Until an API exists, treat a string return as the reason and "
+                       "read the pack names out of the Extras directory "
+                       "(Blackmagic Design/DaVinci Resolve/Extras/*/log.dpl1) for "
+                       "diagnostics only — that path is undocumented and may change.",
+        "tags": ["ai", "extras", "introspection", "resolve-21"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Folder.AnalyzeForSlate / MediaPoolItem.AnalyzeForSlate markerColor",
+        "object": "MediaPoolItem / Folder",
+        "signature": "(markerColor) -> Bool",
+        "reality": "The shipped 21.0.2 scripting README says markerColor must be one of "
+                   "the resolve.MARKER_* constants (resolve.MARKER_BLUE etc.). Those "
+                   "constants do not exist: on Studio 21.0.2.4, "
+                   "[c for c in dir(resolve) if c.startswith('MARKER_')] is empty. "
+                   "There is therefore no documented-correct way to call this method. "
+                   "The plain colour string the server passes is the only option "
+                   "available, and it returns False here — though with AI Slate ID "
+                   "absent, a string-rejection bug cannot be distinguished from the "
+                   "missing pack on this machine.",
+        "recommended": "Keep passing the plain colour name (server._MARKER_COLORS) — "
+                       "the documented constants are unavailable. Re-test on a machine "
+                       "with the AI Slate ID Extra installed before concluding the "
+                       "string form is rejected.",
+        # Deliberately NOT tagged `enum`: that tag denotes the issue-#70 class,
+        # where plain strings are rejected and a resolver must translate them
+        # into live enum constants. Here the documented constants do not exist
+        # on the handle at all, so there is nothing to resolve — the defect is
+        # in the documentation, not in a missing resolver.
+        "tags": ["ai", "extras", "missing-constant", "documentation", "resolve-21"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "Project.ResetIntellisearchAnalysis",
+        "object": "Project",
+        "signature": "() -> Bool",
+        "reality": "Documented in the scripting README shipped with Resolve 21.0.2 "
+                   "(dated 26 May 2026) but absent from the 5 May 2026 copy the repo "
+                   "bundled, so it was missing from the coverage tables. Present in "
+                   "dir(project) and returns True on Studio 21.0.2.4.",
+        "recommended": "Exposed as project_settings('reset_intellisearch_analysis').",
+        "tags": ["resolve-21", "documentation"],
+    },
+    {
+        "symbol": "Resolve.DisableBackgroundTasksForCurrentResolveSession",
+        "object": "Resolve",
+        "signature": "() -> None",
+        "reality": "Returns None, so a caller cannot tell whether it took effect, and "
+                   "there is no Enable... counterpart anywhere in the shipped 21.0.2 "
+                   "scripting README — the only documented way back is restarting "
+                   "Resolve. The scope is the whole session, so a script disables "
+                   "background tasks for every project open in that instance, not just "
+                   "its own. Present in dir(resolve) on Studio 21.0.2.4; deliberately "
+                   "not executed during validation for exactly that reason.",
+        "recommended": "Treat as irreversible within a session. server returns _ok() "
+                       "unconditionally because there is nothing to check.",
+        "tags": ["resolve-21", "unreliable-return", "irreversible", "session-wide"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "MediaPoolItem.PerformAudioClassification / ClearAudioClassification",
+        "object": "MediaPoolItem / Folder",
+        "signature": "() -> Bool",
+        "reality": "Both work without any Extras pack and the effect is observable, "
+                   "which is unusual for this family. Verified on Studio 21.0.2.4 "
+                   "against a synthetic speech clip: PerformAudioClassification "
+                   "returned True and set the clip property 'Category' from '' to "
+                   "'Dialogue' (also surfacing Category/Subcategory in GetMetadata); "
+                   "ClearAudioClassification returned True and reset 'Category' to "
+                   "'Uncategorized' — note the cleared state is 'Uncategorized', NOT "
+                   "the original empty string.",
+        "recommended": "Read back GetClipProperty('Category'); treat both '' and "
+                       "'Uncategorized' as unclassified.",
+        "tags": ["ai", "audio", "resolve-21", "readback"],
+    },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
         "object": "(server runtime)",
@@ -807,6 +932,81 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "when mirroring keep-ranges into clipInfos.",
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
+    {
+        "symbol": "Timeline.DeleteClips (flaky first attempt)",
+        "object": "Timeline",
+        "signature": "([TimelineItem], ripple) -> bool",
+        "reality": "Can return False on the first call even when every item in "
+                   "the list is a valid, present TimelineItem; an identical "
+                   "immediate retry succeeds. Observed once, on Studio 21.0 "
+                   "during a cut-video edit session (items confirmed still "
+                   "present after the False, deleted cleanly on retry). Cause "
+                   "unknown — do NOT read this as the ProjectManager."
+                   "DeleteProject shape: that one has an identified mechanism "
+                   "(the project being, or recently having been, current) that "
+                   "retrying does not clear, whereas a single retry cleared "
+                   "this in the one instance seen. One observation is not a "
+                   "mechanism; if a retry is ever seen to fail repeatedly here, "
+                   "this entry needs revisiting.",
+        "recommended": "Treat a False return as advisory: re-list the track and "
+                       "check whether the items are actually gone; if still "
+                       "present, retry the identical call once before failing. "
+                       "A readback that raised, enumerated nothing, or covered "
+                       "items whose unique ID cannot be read is UNKNOWN, not "
+                       "gone — never report an unverifiable delete as success, "
+                       "and do not spend a second destructive call on an "
+                       "outcome you equally cannot read.",
+        "tags": ["unreliable-return", "flaky", "timeline", "edit"],
+        "submit": "bug",
+        "mitigation": ["_timeline_delete_clips_verified", "_timeline_items_presence"],
+    },
+    {
+        "symbol": "Timeline.DeleteClips (linked audio not deleted)",
+        "object": "Timeline",
+        "signature": "([TimelineItem], ripple) -> bool",
+        "reality": "Deleting video items does NOT delete their linked audio "
+                   "items — the UI's linked-selection behavior does not apply "
+                   "to the API, which deletes exactly the items passed. The "
+                   "orphaned audio stays on its track and collides with any "
+                   "later append into the same record range.",
+        "recommended": "When deleting a video item that has linked audio, list "
+                       "the audio track(s) (timeline get_items, track_type "
+                       "'audio'), find the overlapping linked items, and pass "
+                       "their IDs in the same delete. Verify with "
+                       "detect_gaps_overlaps across both track types.",
+        "tags": ["timeline", "edit", "audio", "silent-failure"],
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline with mixed-fps sources (duration floor)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, ...}]) -> [TimelineItem]",
+        "reality": "start/endFrame are in SOURCE frames. When the source fps "
+                   "differs from the timeline fps (e.g. 24.0 or 29.97 source in "
+                   "a 23.976 timeline), Resolve converts the source range to "
+                   "timeline frames by flooring — so a range planned to fill an "
+                   "exact record slot lands one frame short, leaving a 1-frame "
+                   "gap before the next clip.",
+        "recommended": "Plan durations in timeline frames "
+                       "(floor(src_frames * timeline_fps / source_fps)); if the "
+                       "floored duration misses the slot, extend endFrame by a "
+                       "source frame and re-check. Always finish with "
+                       "detect_gaps_overlaps.",
+        "tags": ["timeline", "edit", "off-by-one", "mixed-fps"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.ImportMedia (current-folder destination only)",
+        "object": "MediaPool",
+        "signature": "([paths] | [clipInfos]) -> [MediaPoolItem]",
+        "reality": "Imports always land in the CURRENT media pool folder; the "
+                   "call has no destination-folder parameter, and passing an "
+                   "unrecognized one to the MCP tool is silently ignored.",
+        "recommended": "SetCurrentFolder to the target bin first (media_pool "
+                       "set_current_folder), import, then restore the previous "
+                       "current folder if it matters.",
+        "tags": ["media-pool", "import"],
+        "submit": "missing",
+    },
     {
         "symbol": "Graph.SetLUT (master-LUT-dir-only resolution)",
         "object": "Graph",