davinci-resolve-mcp 2.33.3 → 2.33.4

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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.33.4
+
+Internal reliability framework.
+
+- **Added** `verify_by_readback` (`src/utils/readback.py`) — a primitive for
+  mutating Resolve ops that verifies an action by reading the real post-state
+  back instead of trusting the API's frequently-unreliable return value. A
+  contradiction (reported success but a failing readback) is logged as a
+  reliability signal.
+- **Changed** Auto-sync audio now runs through `verify_by_readback` as its first
+  user and reports a `verified` field alongside `linked`/`newly_linked`. Behavior
+  is unchanged; the bespoke readback loop is replaced by the shared primitive.
+
 ## What's New in v2.33.3
 
 Two read tools that surface existing project state.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.33.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.33.4-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-32%20(341%20full)-blue.svg)](#server-modes)

package/install.py

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.33.3"
+VERSION = "2.33.4"
 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.33.3"
+VERSION = "2.33.4"
 
 import base64
 import os
@@ -43,6 +43,7 @@ for p in [current_dir, project_dir]:
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
+from src.utils.readback import verify_by_readback
 from src.utils.update_check import (
     check_for_updates,
     clear_update_prompt_preferences,
@@ -5535,19 +5536,34 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     # Read-back verification: AutoSyncAudio's boolean return is unreliable, so
     # capture each clip's "Synced Audio" linkage before and after and report the
     # delta. Trust `linked`/`newly_linked`, not `success`.
-    before = [_synced_audio(c) for c in clips]
-    ok = bool(mp.AutoSyncAudio(clips, settings))
-    linked, newly_linked, already_linked = [], [], []
-    for c, was in zip(clips, before):
-        name = _clip_name(c)
-        if _synced_audio(c):
-            linked.append(name)
-            (already_linked if was else newly_linked).append(name)
+    def _categorize(before, observed):
+        linked, newly, already = [], [], []
+        for c, was, now in zip(clips, before, observed):
+            if now:
+                name = _clip_name(c)
+                linked.append(name)
+                (already if was else newly).append(name)
+        return {
+            "linked": linked,
+            "newly_linked": newly,
+            "already_linked": already,
+            "verified": bool(linked),
+        }
+
+    res = verify_by_readback(
+        mutate=lambda: mp.AutoSyncAudio(clips, settings),
+        observe=lambda: [_synced_audio(c) for c in clips],
+        snapshot=lambda: [_synced_audio(c) for c in clips],
+        compare=_categorize,
+        label="auto_sync_audio",
+        intent={"clip_count": len(clips)},
+    )
     return {
-        "success": ok,
-        "linked": linked,
-        "newly_linked": newly_linked,
-        "already_linked": already_linked,
+        "success": res["success_raw"],
+        "verified": res["verified"],
+        "linked": res["linked"],
+        "newly_linked": res["newly_linked"],
+        "already_linked": res["already_linked"],
         "count": len(clips),
         "missing": missing,
         "settings": settings,

package/src/utils/readback.py

@@ -0,0 +1,70 @@
+"""Readback verification for unreliable Resolve API mutations.
+
+The Resolve scripting API frequently returns a success value that does not
+reflect what actually happened: ``AutoSyncAudio`` returns a boolean unrelated to
+whether clips linked, ``AppendToTimeline`` may not hand back the new item id,
+many setters return ``True`` regardless of effect, and Fusion ``Paste()`` can
+report nothing while creating nothing. The defense is to **verify by reading the
+real post-state back** instead of trusting the return value.
+
+``verify_by_readback`` is the small primitive every mutating op can use. A
+mutation that reports success while the readback disagrees is a *contradiction*
+— the single most valuable reliability signal — and is logged.
+"""
+import logging
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger("davinci-resolve-mcp")
+
+
+def verify_by_readback(
+    mutate: Callable[[], Any],
+    observe: Callable[[], Any],
+    *,
+    snapshot: Optional[Callable[[], Any]] = None,
+    compare: Optional[Callable[[Any, Any], Dict[str, Any]]] = None,
+    intent: Optional[Dict[str, Any]] = None,
+    label: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Run a mutation and verify it by reading actual state back.
+
+    Args:
+        mutate:   performs the Resolve call; its return value is the unreliable
+                  ``success_raw``.
+        observe:  reads the relevant state AFTER the mutation.
+        snapshot: optional — captures pre-state for delta comparisons (passed to
+                  ``compare`` as ``before``).
+        compare:  ``(before, observed) -> dict`` merged into the result. It should
+                  set ``verified: bool``. Defaults to ``verified = truthy(observed)``.
+        intent:   optional description of what we meant to do (for the ledger).
+        label:    optional op name, used in the contradiction log line.
+
+    Returns a dict with at least ``success_raw`` and ``verified``, plus whatever
+    ``compare`` contributed and (if given) ``intent``.
+    """
+    before = snapshot() if snapshot is not None else None
+    raw = mutate()
+    observed = observe()
+
+    result: Dict[str, Any] = {"success_raw": bool(raw), "observed": observed}
+    if compare is not None:
+        result.update(compare(before, observed))
+    else:
+        result["verified"] = bool(observed)
+    if intent is not None:
+        result["intent"] = intent
+
+    # A contradiction — reported success but the readback disagrees — is the
+    # signal worth surfacing loudly.
+    if result.get("success_raw") and not result.get("verified"):
+        logger.warning(
+            "readback contradiction%s: API reported success but post-state "
+            "verification failed%s",
+            f" [{label}]" if label else "",
+            f" (intent={intent})" if intent else "",
+        )
+        result["contradiction"] = True
+    else:
+        result["contradiction"] = False
+
+    return result