davinci-resolve-mcp 2.98.7 → 2.98.8

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 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.8
+
+**The comp-lock mechanism, settled — and the v2.98.6 scope correction was itself
+wrong.** Chasing why `add_fusion_mask` and `set_text_plus` escaped the bug found
+that they don't. Their test cases were priming the comp and could not have
+failed.
+
+### The mechanism
+
+| | |
+| --- | --- |
+| **Precondition** | The comp's graph was built through lock-wrapped `AddTool`/`ConnectInput`. The same locked write against a graph wired by plain attribute assignment renders normally. |
+| **Trigger** | The locked write is the **first value write to that comp** since the build. |
+| **Primes it away** | **Any** unlocked value write anywhere in the comp — even writing a *default* value to an *unrelated* tool. Also `StartUndo`/`EndUndo` around the write. |
+| **Does not** | A structural `ConnectInput` inside the same lock; a `GetInput` readback after `Unlock`. |
+
+Priming is why every raw-API attempt to reproduce the bug kept coming back green,
+and why a control that was supposed to fail didn't.
+
+### The corrected scope
+
+| path | locked write |
+| --- | --- |
+| `set_input` | **suppressed** |
+| `safe_set_inputs` | **suppressed** |
+| `set_text_plus` | **suppressed** |
+| `add_fusion_mask` | **suppressed** |
+| `bulk_set_inputs` | escapes — wrapped in `StartUndo`/`EndUndo` |
+| `bulk_set_expressions` | escapes — wrapped in `StartUndo`/`EndUndo` |
+
+So **four of six** paths were genuinely broken, not two. v2.98.5's original
+"all six were the same bug" was closer to right than v2.98.6's correction of it;
+the two real escapes are explained by their undo wrapper.
+
+### Fixed in the tests
+
+`tests/live_fusion_value_write_validation.py` had two cases that could not fail.
+Both set up their graph with plain `SetInput` calls — a text `Size`, a blur
+amount — before the call under test, which primed the comp. Removing that:
+
+- the `set_text_plus` case now builds its rooted graph and writes **nothing**
+  before the call, leaving the Text+ at its default size;
+- the `add_fusion_mask` case composites a **Background** rather than making a
+  Blur visible, because a Background is visible at its defaults and needs no
+  setup write.
+
+Both now report `PSNR inf -> IGNORED at render` with the lock reintroduced, and
+13–17 dB APPLIED without it. The header carries a standing rule: a case in that
+file must perform no value write of any kind before the call it is testing.
+
+No production code changed. The v2.98.5 fix has been correct throughout; this is
+the third and final correction to the *description* of what it fixed.
+
 ## What's New in v2.98.7
 
 **Identifying the mechanism behind the Fusion comp-lock bug — and correcting the
@@ -61,6 +114,11 @@ it. What changed is the explanation, in `api_truth` and the harness docs.
 
 ## What's New in v2.98.6
 
+> **Corrected in v2.98.8.** The table below says four of six paths escape the
+> bug. Two of those four — `set_text_plus` and `add_fusion_mask` — do not; their
+> test cases primed the comp with setup writes and could not fail. Only
+> `bulk_set_inputs` and `bulk_set_expressions` genuinely escape.
+
 **Correcting the scope of the v2.98.5 Fusion fix, and covering all six paths
 with a render.** v2.98.5 removed a `Comp.Lock()` from six Fusion value writes and
 described all six as the same bug. Only two of them were proven with a render at

package/README.md

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

package/docs/SKILL.md

@@ -1691,13 +1691,13 @@ Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, o
 page comp (omit timeline scope).
 
 READBACK IS NOT PROOF FOR FUSION PARAMETERS. Up to v2.98.4 every value write
-here ran inside a `Comp.Lock()`. For `set_input` and `safe_set_inputs` that was
-load-bearing: the value is stored in the graph and returned by `get_input` while
-the RENDER ignores it entirely (Studio 19.1.3.7: PSNR inf vs the no-comp
-baseline — the delivered file was bit-identical to no comp at all). The other
-four locked paths did not reproduce it, so the blast radius was narrower than
-first reported; the locks came off all six regardless. Fixed in v2.98.5
-(measurement corrected in v2.98.6), and guarded by
+here ran inside a `Comp.Lock()`, and a value written under a comp lock is stored
+in the graph and returned by `get_input` while the RENDER ignores it entirely
+(Studio 19.1.3.7: PSNR inf vs the no-comp baseline). Four of the six affected
+paths — `set_input`, `safe_set_inputs`, `set_text_plus`, `add_fusion_mask` — were
+confirmed broken by rendering; `bulk_set_inputs` and `bulk_set_expressions`
+escape because they wrap their write in `StartUndo`/`EndUndo`. Fixed in v2.98.5,
+mechanism settled in v2.98.8, and guarded by
 `tests/test_fusion_value_write_lock.py` plus the rendered-frame harness
 `tests/live_fusion_value_write_validation.py`. The lesson outlives the bug: a
 Fusion parameter that reads back correctly has proven nothing about the output,

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. 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.
+- **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. MECHANISM (settled 2026-08-22). PRECONDITION: it only reproduces on a comp whose graph was BUILT through lock-wrapped AddTool/ConnectInput; the same locked write against a graph wired by plain attribute assignment renders normally. TRIGGER: the locked write is lost when it is the FIRST value write to that comp since the build. PRIMING: any unlocked value write anywhere in the comp clears the condition permanently — even writing a DEFAULT value to an unrelated tool — and so does StartUndo/EndUndo around the write. A structural ConnectInput inside the same lock does NOT clear it, and neither does a GetInput readback. Priming makes false negatives easy: a test that sets anything up with a plain SetInput before the call under test will pass even with the bug present.
 - **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.7"
+VERSION = "2.98.8"
 # 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.7",
+  "version": "2.98.8",
   "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.7"
+VERSION = "2.98.8"
 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.7"
+VERSION = "2.98.8"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -427,23 +427,21 @@ 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. PRECONDITION (2026-08-22): the "
-                   "suppression only reproduces on a graph that was BUILT "
-                   "through lock-wrapped AddTool/ConnectInput calls. The same "
+                   "production code. MECHANISM (settled 2026-08-22). "
+                   "PRECONDITION: it only reproduces on a comp whose graph was "
+                   "BUILT through lock-wrapped AddTool/ConnectInput; 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.",
+                   "assignment renders normally. TRIGGER: the locked write is "
+                   "lost when it is the FIRST value write to that comp since "
+                   "the build. PRIMING: any unlocked value write anywhere in "
+                   "the comp clears the condition permanently — even writing a "
+                   "DEFAULT value to an unrelated tool — and so does "
+                   "StartUndo/EndUndo around the write. A structural "
+                   "ConnectInput inside the same lock does NOT clear it, and "
+                   "neither does a GetInput readback. Priming makes false "
+                   "negatives easy: a test that sets anything up with a plain "
+                   "SetInput before the call under test will pass even with the "
+                   "bug present.",
         "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 "