davinci-resolve-mcp 2.98.6 → 2.98.8

package/CHANGELOG.md

@@ -2,8 +2,123 @@
 
 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
+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
 
+> **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
@@ -67,6 +182,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.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.6-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.6 版 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. 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. 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.6"
+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.6",
+  "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.6"
+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.6"
+VERSION = "2.98.8"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -427,15 +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. 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. 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.",
         "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 "