davinci-resolve-mcp 2.98.6 → 2.98.7

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 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.98.7
+
+**Identifying the mechanism behind the Fusion comp-lock bug — and correcting the
+root cause, again.** v2.98.6 recorded that four of the six locked call paths did
+not reproduce the bug and that the rescuing mechanism was unknown. Isolating it
+turned up something more important: the root cause stated in v2.98.5 and v2.98.6
+was incomplete.
+
+### The precondition nobody had noticed
+
+A lock around a value write is **necessary but not sufficient**. The suppression
+only reproduces on a comp whose graph was **built through lock-wrapped
+`AddTool`/`ConnectInput` calls**. The identical locked write against a graph
+wired by plain attribute assignment renders normally.
+
+That is why every raw-API attempt to reproduce the bug came back green — a
+control that was supposed to fail, didn't, which is what exposed the gap. Holding
+the write constant and varying only how the graph was built:
+
+| graph built via | value written via | render |
+| --- | --- | --- |
+| MCP `add_tool`/`connect` | MCP, locked | **suppressed** |
+| raw attribute assignment | MCP, locked | rendered |
+| MCP `add_tool`/`connect` | raw, locked | **suppressed** |
+| raw attribute assignment | raw, locked | rendered |
+
+### What rescues it
+
+Given that precondition, with the locked write in place:
+
+| after the locked write | render |
+| --- | --- |
+| nothing | **suppressed** |
+| a subsequent **unlocked** value write | rescued |
+| `StartUndo` / `EndUndo` around the write | rescued |
+| a structural `ConnectInput` inside the lock | **suppressed** |
+| a `GetInput` readback after `Unlock` | **suppressed** |
+
+So `bulk_set_inputs` and `bulk_set_expressions` escape the bug because both wrap
+their write in `StartUndo`/`EndUndo`. **That answers the open question from
+v2.98.6 for two of the four.** `add_fusion_mask` and `set_text_plus` still escape
+for reasons not identified — but the two obvious candidates, a structural call in
+the same lock and a readback, were tested and ruled out.
+
+### Nothing changed in the fix
+
+The v2.98.5 change stands and remains verified: removing the lock from the value
+write is what makes these paths render, and the live harness still fails without
+it. What changed is the explanation, in `api_truth` and the harness docs.
+
+### Added
+
+- `tests/live_fusion_lock_mechanism_probe.py` — the isolation experiment itself,
+  kept runnable rather than written up and thrown away, so the result can be
+  re-checked on another Resolve build instead of taken on trust. It is not a
+  pass/fail test; it prints the five-case matrix above.
+
 ## What's New in v2.98.6
 
 **Correcting the scope of the v2.98.5 Fusion fix, and covering all six paths
@@ -67,6 +124,12 @@ one no readback can check.
 
 ## What's New in v2.98.5
 
+> **Scope corrected in v2.98.6.** Six sites had the lock removed, but only
+> `set_input` and `safe_set_inputs` were ever verified to suppress the render.
+> The other four were changed by inference, and mutation-checking each of them
+> afterwards showed the lock does not break them. No code changed back; only the
+> claim did. See the v2.98.6 entry above for the per-site measurement.
+
 **Every Fusion parameter this server wrote was ignored at render.** A value
 write (`SetInput` / `SetExpression`) wrapped in `Comp.Lock()`/`Unlock()` is
 stored in the graph and reads back correctly — `GetInput` returns it, and so

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.98.6-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.98.7-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-35%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.98.6-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.98.7-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-35%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.98.6 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.98.7 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/reference/api-limitations.md

@@ -343,7 +343,7 @@ values, or automation-hostile modal prompts.
 
 - **Object:** `Composition (Fusion, via TimelineItem comps)`
 - **Signature:** `Lock() / Unlock()`
-- **Behavior:** A numeric tool.SetInput() performed between Comp.Lock() and Comp.Unlock(), when that write is the only thing the call does, is stored in the graph and reads back correctly from GetInput() but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code. SCOPE, measured by reintroducing the lock at each site and re-rendering: it reproduces for a bare numeric SetInput (2 of 6 call paths tested) and does NOT reproduce when the same call also wraps the write in StartUndo/EndUndo, performs an AddTool, or writes a string to StyledText (4 of 6). Which of those rescues the write is not established — only that they do. Treat the safe cases as unexplained rather than proven safe, and keep value writes outside the lock everywhere.
+- **Behavior:** A numeric tool.SetInput() performed between Comp.Lock() and Comp.Unlock(), when that write is the only thing the call does, is stored in the graph and reads back correctly from GetInput() but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code. PRECONDITION (2026-08-22): the suppression only reproduces on a graph that was BUILT through lock-wrapped AddTool/ConnectInput calls. The same locked write against a graph wired by plain attribute assignment renders normally, so 'a lock around a value write' is necessary but not sufficient — the comp has to have been through prior lock cycles. RESCUERS, each verified by rendering: Comp.EndUndo() after the locked write restores it, and so does any subsequent UNLOCKED value write. NOT rescuers: a structural ConnectInput inside the same lock, and a GetInput readback after the Unlock — both still render the stale frame. This explains why undo-wrapped bulk writes escape the bug; two further call shapes (a mask whose inputs are written right after AddTool, and a StyledText string write) escape it for reasons still unidentified. Keep value writes outside the lock everywhere rather than relying on an escape.
 - **Workaround / current handling:** Never hold a comp lock across a value write. Lock only structural work (AddTool/ConnectInput) and set inputs outside it. Because every readback the API offers agrees with the value that was written, this failure is invisible without a render — prove Fusion parameter changes with a delivered frame or gallery_stills grab_and_export, never with GetInput.
 - **Tags:** fusion, silent-failure, render, readback
 

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.98.6"
+VERSION = "2.98.7"
 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 353-tool granular server instead
 """
 
-VERSION = "2.98.6"
+VERSION = "2.98.7"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -427,15 +427,23 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "suppresses the parameter-change invalidation that a value "
                    "write depends on. Lock() is widely recommended for "
                    "batching Fusion edits, which is how this reaches "
-                   "production code. SCOPE, measured by reintroducing the lock "
-                   "at each site and re-rendering: it reproduces for a bare "
-                   "numeric SetInput (2 of 6 call paths tested) and does NOT "
-                   "reproduce when the same call also wraps the write in "
-                   "StartUndo/EndUndo, performs an AddTool, or writes a string "
-                   "to StyledText (4 of 6). Which of those rescues the write is "
-                   "not established — only that they do. Treat the safe cases as "
-                   "unexplained rather than proven safe, and keep value writes "
-                   "outside the lock everywhere.",
+                   "production code. PRECONDITION (2026-08-22): the "
+                   "suppression only reproduces on a graph that was BUILT "
+                   "through lock-wrapped AddTool/ConnectInput calls. The same "
+                   "locked write against a graph wired by plain attribute "
+                   "assignment renders normally, so 'a lock around a value "
+                   "write' is necessary but not sufficient — the comp has to "
+                   "have been through prior lock cycles. RESCUERS, each "
+                   "verified by rendering: Comp.EndUndo() after the locked "
+                   "write restores it, and so does any subsequent UNLOCKED "
+                   "value write. NOT rescuers: a structural ConnectInput "
+                   "inside the same lock, and a GetInput readback after the "
+                   "Unlock — both still render the stale frame. This explains "
+                   "why undo-wrapped bulk writes escape the bug; two further "
+                   "call shapes (a mask whose inputs are written right after "
+                   "AddTool, and a StyledText string write) escape it for "
+                   "reasons still unidentified. Keep value writes outside the "
+                   "lock everywhere rather than relying on an escape.",
         "recommended": "Never hold a comp lock across a value write. Lock only "
                        "structural work (AddTool/ConnectInput) and set inputs "
                        "outside it. Because every readback the API offers "