davinci-resolve-mcp 2.98.4 → 2.98.6

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 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.6
+
+**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
+the time; the other four were changed by inference. Extending the live harness to
+cover the remaining four showed that inference was too broad.
+
+Every site was mutation-checked by reintroducing the lock and re-rendering on
+Studio 19.1.3.7:
+
+| call path | with the lock back |
+| --- | --- |
+| `set_input` | **PSNR inf — suppressed** |
+| `safe_set_inputs` | **PSNR inf — suppressed** |
+| `bulk_set_inputs` | unchanged, still rendered |
+| `bulk_set_expressions` | unchanged, still rendered |
+| `add_fusion_mask` | unchanged, still rendered |
+| `set_text_plus` | unchanged, still rendered |
+
+The two that break are the two where the locked write is the only thing the call
+does. The four that survive each do something else in the same call that appears
+to invalidate the graph anyway — `bulk_set_inputs` and `bulk_set_expressions`
+wrap the write in `StartUndo`/`EndUndo`, `add_fusion_mask` performs an `AddTool`,
+and `set_text_plus` writes a string rather than a number. **Which of those is the
+rescuing mechanism is not established** — only that the four do not reproduce.
+
+No code changed back. Removing the lock from a single write buys nothing and
+costs nothing, and treating the four as merely unexplained rather than proven
+safe is the conservative reading. What changed is the claim: `api_truth`,
+`docs/SKILL.md` and the AST guard's failure message now state the measured scope
+instead of "any value write".
+
+If you read the v2.98.5 notes and concluded every Fusion parameter this server
+ever wrote was ignored at render, that was overstated — it was true for
+`set_input` and `safe_set_inputs`.
+
+### Tests
+
+`tests/live_fusion_value_write_validation.py` grows from two cases to six,
+covering every site the fix touched:
+
+```
+set_input: PSNR 24.375987 -> APPLIED at render
+safe_set_inputs: PSNR 24.375987 -> APPLIED at render
+set_text_plus: PSNR 13.33844 -> APPLIED at render
+bulk_set_expressions: PSNR 24.375987 -> APPLIED at render
+bulk_set_inputs: PSNR 24.375987 -> APPLIED at render
+add_fusion_mask: PSNR 30.369794 -> APPLIED at render
+```
+
+The `set_text_plus` case builds a rooted `MediaIn -> Merge -> MediaOut` graph
+with the Text+ in the foreground — a comp whose MediaOut is fed only by a Text+
+is bypassed at render for an unrelated reason and would have failed for the
+wrong cause. The `add_fusion_mask` case cannot use a baseline/after comparison,
+because a default-sized mask still changes the render; it builds the same graph
+twice, once with a default mask and once with an explicitly tiny one, and
+requires the two renders to differ.
+
+Four of the six cases do not discriminate the lock. They are kept because they
+still prove the write reaches the render — the property that matters, and the
+one no readback can check.
+
+## What's New in v2.98.5
+
+**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
+did this server's own `get_input` — while the delivered render ignores it
+completely. Found on 2026-08-21 while re-running a Fusion isolation on Studio
+19.1.3.7 to settle a conflicting measurement reported in
+[#156](https://github.com/samuelgursky/davinci-resolve-mcp/pull/156).
+
+Measured on Studio 19.1.3.7 with `MediaIn -> Blur(XBlurSize 20) -> MediaOut` on
+a media-backed clip, rendering the same 48 frames to H.264 each time:
+
+| value written via | render vs no-comp baseline |
+| --- | --- |
+| `fusion_comp set_input` (write inside `Comp.Lock()`) | PSNR **inf** — bit-identical, ignored |
+| the same write, lock removed | PSNR **24.38 dB**, 2.0 MB → 727 KB |
+| raw `tool.XBlurSize = 20.0` | PSNR **24.38 dB** |
+| raw `tool.SetInput("XBlurSize", 20)` | PSNR **24.38 dB** |
+
+The variable was isolated against the comp handle (`AddFusionComp`,
+`GetFusionCompByIndex` and `GetFusionCompByName` all render), the node name, and
+the write form. Only the lock around the write decides it. **Structural** edits
+are unaffected — `AddTool` and `ConnectInput` inside a lock render normally — so
+this is not "Lock is unsafe"; the lock suppresses the parameter-change
+invalidation that a value write depends on.
+
+### Fixed
+
+- **Six value-write sites no longer hold a comp lock across the write:**
+  `fusion_comp set_input`, `fusion_comp safe_set_inputs`, `bulk_set_inputs`,
+  `bulk_set_expressions`, the Text+ writer behind `set_text`, and
+  `add_mask` — where the lock spanned `AddTool` *and* every input write, so a
+  mask was created at default size and position and every parameter the caller
+  passed did nothing. Structural work keeps its lock; in `add_mask` the lock now
+  closes after the node is created and renamed.
+
+### Why this went unnoticed
+
+Every readback the API offers agreed with the value that was written. This is
+the failure mode the repo's own guidance describes — prove a Fusion or grade
+claim with a rendered frame, never with readback — except the cause was ours,
+not Resolve's. It also explains an unknown share of past "the comp was ignored"
+reports, which look identical from the API side.
+
+### Tests
+
+- `tests/live_fusion_value_write_validation.py` — renders a baseline, writes a
+  blur size through the compound tool, renders again, and asserts PSNR actually
+  moved. Disposable project, synthetic media, restores the previous project.
+- `tests/test_fusion_value_write_lock.py` — AST guard failing any value write
+  that sits inside a `Comp.Lock()`/`Unlock()` region, with a self-check that the
+  guard can still see a known-bad shape.
+
+Both were mutation-checked against the pre-fix code: reintroducing the lock in
+`set_input` makes the live harness report `PSNR inf -> IGNORED at render` and
+fails the offline guard.
+
+- `api_truth`: new `Composition.Lock` entry; the `AddFusionComp` entry records
+  that its 2026-08-02 rooted-comp result **reproduced** on 19.1.3.7 (PSNR 24.38 dB).
+
 ## What's New in v2.98.4
 
 **Setup reported success over an install that could never work.** Reported and

package/README.md

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

package/docs/SKILL.md

@@ -1690,6 +1690,20 @@ Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, o
 `timeline_item={track_type, track_index, item_index}`) or from the active Fusion
 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
+`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,
+so confirm any Fusion look with a rendered frame (`gallery_stills
+grab_and_export` or a frame from a delivered render), never with `get_input`.
+
 Key actions:
 - `add_tool(tool_type, x?, y?, name?)` — common types: `Merge`, `Background`,
   `TextPlus`, `Transform`, `Blur`, `ColorCorrector`, `RectangleMask`,

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 27 missing capabilities, 35 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 36 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -339,10 +339,18 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Author OTIO for Resolve by mirroring what Resolve itself exports, and give every event its media timecode origin. editorial.convert_to_interchange (target 'otio') does this and reports any event whose origin had to be assumed in `mediaOriginAssumed` — a non-empty list means the file will only import if that media really starts at 00:00:00:00. To debug a refusal, export any timeline with EXPORT_OTIO and diff your document against it; do NOT chase missing media or reach for sanitize_media, which cannot even parse a .otio (it is JSON, not XML).
 - **Tags:** timeline, import, interchange, otio, silent-failure, conform
 
+### Composition.Lock (suppresses render invalidation for value writes)
+
+- **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.
+- **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
+
 ### TimelineItem.AddFusionComp / LoadFusionCompByName
 
 - **Object:** `TimelineItem (media-backed clip)`
-- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally.
+- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side.
 - **Workaround / current handling:** Wire the graph so MediaOut descends from MediaIn — that is the difference between a comp that renders and one that is silently bypassed, and it is what made this look like 'Fusion never renders from the API'. Never leave a tool unrooted: a MediaOut fed by a tool with no source failed the render job outright. For text or effects over picture, insert a Fusion title/generator as its own timeline clip and set its Text+ (fusion_comp set_text_plus), rather than attaching a comp to the media clip. Note the destination track cannot be chosen from the API (see the Track Selector entry), so overlaying onto an existing clip's track is not currently reachable end-to-end. Building the comp in the Fusion page UI works; only the API-created comp is ignored.
 - **Tags:** fusion, silent-failure, render
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.98.4"
+VERSION = "2.98.6"
 # 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.4",
+  "version": "2.98.6",
   "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.4"
+VERSION = "2.98.6"
 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.4"
+VERSION = "2.98.6"
 
 import base64
 import os
@@ -25841,6 +25841,35 @@ def _fusion_group_settings_splice_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+# Why no comp.Lock() around Fusion VALUE writes.
+#
+# Wrapping a value write (SetInput / SetExpression) in comp.Lock()/Unlock()
+# leaves the value fully readable — GetInput returns it, and so does this
+# server's own get_input — while the RENDER ignores it entirely. Measured live
+# on Studio 19.1.3.7 with a MediaIn -> Blur(XBlurSize 20) -> MediaOut comp on a
+# media-backed clip: identical graph, identical readback, delivered render
+# bit-identical to the no-comp baseline (ffmpeg PSNR inf). Removing the lock
+# from the write 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 / GetFusionCompByName all render), the
+# node name, and the write form (attribute assignment and SetInput both render
+# unlocked) — only the lock around the write decides it.
+#
+# STRUCTURAL edits are a different case and KEEP their lock: AddTool,
+# ConnectInput and friends invalidate the render through another path and were
+# verified to render while locked. So this is not "Lock is unsafe", it is
+# "Lock suppresses the parameter-change invalidation that a value write needs".
+#
+# This is why grade/Fusion claims are proven with a rendered frame and never
+# with comp readback: every readback the API offers agreed the value was set.
+_FUSION_VALUE_WRITE_NOTE = (
+    "Fusion value writes (SetInput/SetExpression) must not be wrapped in "
+    "comp.Lock()/Unlock(): the value reads back correctly but is ignored at "
+    "render (Studio 19.1.3.7, PSNR inf vs baseline). Structural edits "
+    "(AddTool/ConnectInput) are unaffected and keep their lock."
+)
+
+
 def _fusion_group_settings_load(comp, p: Dict[str, Any]) -> Dict[str, Any]:
     group_name = p.get("group_name")
     if not group_name:
@@ -25946,16 +25975,13 @@ def _fusion_comp_bulk_set_expressions(p: Dict[str, Any]) -> Dict[str, Any]:
                 undo_started = True
             except Exception:
                 undo_started = False
-            comp.Lock()
-            try:
-                time = op.get("time", 0)
-                inp = tool[op["input_name"]]
-                if not inp:
-                    raise ValueError(f"Input {op['input_name']!r} not found on {op['tool_name']!r}")
-                inp.SetExpression(str(op["expression"]), time)
-                keep_undo = True
-            finally:
-                comp.Unlock()
+            # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+            time = op.get("time", 0)
+            inp = tool[op["input_name"]]
+            if not inp:
+                raise ValueError(f"Input {op['input_name']!r} not found on {op['tool_name']!r}")
+            inp.SetExpression(str(op["expression"]), time)
+            keep_undo = True
         except Exception as exc:
             error_message = str(exc)
         finally:
@@ -26074,15 +26100,12 @@ def _fusion_comp_bulk_set_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
                 undo_started = True
             except Exception:
                 undo_started = False
-            comp.Lock()
-            try:
-                if "time" in op:
-                    tool.SetInput(op["input_name"], op["value"], op["time"])
-                else:
-                    tool.SetInput(op["input_name"], op["value"])
-                keep_undo = True
-            finally:
-                comp.Unlock()
+            # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+            if "time" in op:
+                tool.SetInput(op["input_name"], op["value"], op["time"])
+            else:
+                tool.SetInput(op["input_name"], op["value"])
+            keep_undo = True
         except Exception as exc:
             error_message = str(exc)
         finally:
@@ -26255,25 +26278,22 @@ def _safe_set_fusion_inputs(comp, p: Dict[str, Any]):
     if p.get("dry_run"):
         return _ok(tool_name=tool_name, inputs=inputs, would_set=True)
     results = {}
-    comp.Lock()
-    try:
-        for input_name, value in inputs.items():
-            try:
-                if "time" in p:
-                    tool.SetInput(input_name, value, p["time"])
-                else:
-                    tool.SetInput(input_name, value)
-                row = {"success": True}
-                if p.get("readback", True):
-                    try:
-                        row["value"] = _ser(tool.GetInput(input_name, p["time"])) if "time" in p else _ser(tool.GetInput(input_name))
-                    except Exception as exc:
-                        row["readback_error"] = str(exc)
-                results[input_name] = row
-            except Exception as exc:
-                results[input_name] = {"success": False, "error": str(exc)}
-    finally:
-        comp.Unlock()
+    # No comp.Lock() around value writes — see _FUSION_VALUE_WRITE_NOTE.
+    for input_name, value in inputs.items():
+        try:
+            if "time" in p:
+                tool.SetInput(input_name, value, p["time"])
+            else:
+                tool.SetInput(input_name, value)
+            row = {"success": True}
+            if p.get("readback", True):
+                try:
+                    row["value"] = _ser(tool.GetInput(input_name, p["time"])) if "time" in p else _ser(tool.GetInput(input_name))
+                except Exception as exc:
+                    row["readback_error"] = str(exc)
+            results[input_name] = row
+        except Exception as exc:
+            results[input_name] = {"success": False, "error": str(exc)}
     return {"success": all(row.get("success") for row in results.values()), "tool_name": tool_name, "results": results}
 
 
@@ -26438,6 +26458,11 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
     y = p.get("y", -1)
     readback = bool(p.get("readback", True))
 
+    # The lock covers only the STRUCTURAL half (AddTool + rename). The input
+    # writes below must run outside it — see _FUSION_VALUE_WRITE_NOTE: a value
+    # written under the lock reads back correctly and is ignored at render,
+    # which on a mask means the shape exists at default size and position and
+    # every parameter the caller passed silently does nothing.
     comp.Lock()
     try:
         tool = comp.AddTool(tool_type, x, y)
@@ -26449,83 +26474,84 @@ def _fusion_add_mask(comp, p: Dict[str, Any]) -> Dict[str, Any]:
         name = p.get("name")
         if name:
             tool.SetAttrs({"TOOLS_Name": str(name)})
-        attrs = tool.GetAttrs() or {}
-        tool_name = attrs.get("TOOLS_Name", "")
-
-        results: List[Dict[str, Any]] = []
-
-        # Center: accept center=[x,y]/{1:x,2:y}, or center_x / center_y.
-        center = p.get("center")
-        cx, cy = p.get("center_x"), p.get("center_y")
-        if center is None and (cx is not None or cy is not None):
-            center = [cx if cx is not None else 0.5, cy if cy is not None else 0.5]
-        if center is not None:
-            ok, err, applied = _fusion_set_point_input(tool, "Center", center)
-            rec = {"input": "Center", "value": center, "success": ok}
-            if not ok:
-                rec["error"] = err
-            elif readback:
+    finally:
+        comp.Unlock()
+
+    attrs = tool.GetAttrs() or {}
+    tool_name = attrs.get("TOOLS_Name", "")
+
+    results: List[Dict[str, Any]] = []
+
+    # Center: accept center=[x,y]/{1:x,2:y}, or center_x / center_y.
+    center = p.get("center")
+    cx, cy = p.get("center_x"), p.get("center_y")
+    if center is None and (cx is not None or cy is not None):
+        center = [cx if cx is not None else 0.5, cy if cy is not None else 0.5]
+    if center is not None:
+        ok, err, applied = _fusion_set_point_input(tool, "Center", center)
+        rec = {"input": "Center", "value": center, "success": ok}
+        if not ok:
+            rec["error"] = err
+        elif readback:
+            try:
+                rec["readback"] = _ser(tool.GetInput("Center"))
+            except Exception as exc:
+                rec["readback_error"] = str(exc)
+        results.append(rec)
+
+    # Scalar inputs (friendly aliases) + any raw passthrough inputs.
+    to_set: List[tuple] = []
+    for friendly, fusion_id in _MASK_INPUT_ALIASES.items():
+        if friendly in p:
+            to_set.append((fusion_id, p[friendly]))
+    raw_inputs = p.get("inputs")
+    if isinstance(raw_inputs, dict):
+        for k, v in raw_inputs.items():
+            to_set.append((str(k), v))
+
+    for fusion_id, value in to_set:
+        rec = {"input": fusion_id, "value": value}
+        try:
+            tool.SetInput(fusion_id, value)
+            rec["success"] = True
+            if readback:
                 try:
-                    rec["readback"] = _ser(tool.GetInput("Center"))
+                    rec["readback"] = _ser(tool.GetInput(fusion_id))
                 except Exception as exc:
                     rec["readback_error"] = str(exc)
-            results.append(rec)
-
-        # Scalar inputs (friendly aliases) + any raw passthrough inputs.
-        to_set: List[tuple] = []
-        for friendly, fusion_id in _MASK_INPUT_ALIASES.items():
-            if friendly in p:
-                to_set.append((fusion_id, p[friendly]))
-        raw_inputs = p.get("inputs")
-        if isinstance(raw_inputs, dict):
-            for k, v in raw_inputs.items():
-                to_set.append((str(k), v))
-
-        for fusion_id, value in to_set:
-            rec = {"input": fusion_id, "value": value}
-            try:
-                tool.SetInput(fusion_id, value)
-                rec["success"] = True
-                if readback:
-                    try:
-                        rec["readback"] = _ser(tool.GetInput(fusion_id))
-                    except Exception as exc:
-                        rec["readback_error"] = str(exc)
-            except Exception as exc:
-                rec["success"] = False
-                rec["error"] = str(exc)
-            results.append(rec)
+        except Exception as exc:
+            rec["success"] = False
+            rec["error"] = str(exc)
+        results.append(rec)
 
-        out: Dict[str, Any] = {
-            "success": True,
-            "tool_name": tool_name,
-            "tool_type": attrs.get("TOOLS_RegID", tool_type),
-            "inputs_set": results,
-        }
+    out: Dict[str, Any] = {
+        "success": True,
+        "tool_name": tool_name,
+        "tool_type": attrs.get("TOOLS_RegID", tool_type),
+        "inputs_set": results,
+    }
 
-        # Optional wiring: connect this mask into a tool's mask input.
-        connect_to = p.get("connect_to")
-        if connect_to:
-            input_name = p.get("connect_input", "EffectMask")
-            target = comp.FindTool(str(connect_to))
-            if not target:
+    # Optional wiring: connect this mask into a tool's mask input.
+    connect_to = p.get("connect_to")
+    if connect_to:
+        input_name = p.get("connect_input", "EffectMask")
+        target = comp.FindTool(str(connect_to))
+        if not target:
+            out["connection"] = {
+                "success": False,
+                "error": f"connect_to tool '{connect_to}' not found",
+            }
+        else:
+            try:
+                ok = bool(target.ConnectInput(input_name, tool))
                 out["connection"] = {
-                    "success": False,
-                    "error": f"connect_to tool '{connect_to}' not found",
+                    "success": ok,
+                    "target": str(connect_to),
+                    "input_name": input_name,
                 }
-            else:
-                try:
-                    ok = bool(target.ConnectInput(input_name, tool))
-                    out["connection"] = {
-                        "success": ok,
-                        "target": str(connect_to),
-                        "input_name": input_name,
-                    }
-                except Exception as exc:
-                    out["connection"] = {"success": False, "error": str(exc)}
-        return out
-    finally:
-        comp.Unlock()
+            except Exception as exc:
+                out["connection"] = {"success": False, "error": str(exc)}
+    return out
 
 
 def _fusion_find_text_tool(comp, p: Dict[str, Any]):
@@ -26561,25 +26587,22 @@ def _fusion_set_text_plus(comp, p: Dict[str, Any]) -> Dict[str, Any]:
         return err
     input_id = p.get("input_name", "StyledText")
     readback = bool(p.get("readback", True))
-    comp.Lock()
+    # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
     try:
+        tool.SetInput(input_id, text)
+    except Exception as exc:
+        return _err(f"SetInput({input_id!r}) failed: {exc}")
+    out = {
+        "success": True,
+        "tool_name": (tool.GetAttrs() or {}).get("TOOLS_Name", ""),
+        "input_name": input_id,
+    }
+    if readback:
         try:
-            tool.SetInput(input_id, text)
+            out["readback"] = _ser(tool.GetInput(input_id))
         except Exception as exc:
-            return _err(f"SetInput({input_id!r}) failed: {exc}")
-        out = {
-            "success": True,
-            "tool_name": (tool.GetAttrs() or {}).get("TOOLS_Name", ""),
-            "input_name": input_id,
-        }
-        if readback:
-            try:
-                out["readback"] = _ser(tool.GetInput(input_id))
-            except Exception as exc:
-                out["readback_error"] = str(exc)
-        return out
-    finally:
-        comp.Unlock()
+            out["readback_error"] = str(exc)
+    return out
 
 
 def _fusion_keyframe_frames(inp) -> List[float]:
@@ -26956,15 +26979,12 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         tool = comp.FindTool(p["tool_name"])
         if not tool:
             return _err(f"Tool '{p['tool_name']}' not found")
-        comp.Lock()
-        try:
-            if "time" in p:
-                tool.SetInput(p["input_name"], p["value"], p["time"])
-            else:
-                tool.SetInput(p["input_name"], p["value"])
-            return _ok()
-        finally:
-            comp.Unlock()
+        # No comp.Lock() around a value write — see _FUSION_VALUE_WRITE_NOTE.
+        if "time" in p:
+            tool.SetInput(p["input_name"], p["value"], p["time"])
+        else:
+            tool.SetInput(p["input_name"], p["value"])
+        return _ok()
 
     elif action == "get_input":
         tool = comp.FindTool(p["tool_name"])

package/src/utils/api_truth.py

@@ -403,6 +403,52 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "import", "interchange", "otio", "silent-failure", "conform"],
         "submit": "bug",
     },
+    {
+        "symbol": "Composition.Lock (suppresses render invalidation for value writes)",
+        "object": "Composition (Fusion, via TimelineItem comps)",
+        "signature": "Lock() / Unlock()",
+        "reality": "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.",
+        "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 "
+                       "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"],
+        "submit": "bug",
+        "mitigation": ["_FUSION_VALUE_WRITE_NOTE",
+                       "tests/live_fusion_value_write_validation.py",
+                       "tests/test_fusion_value_write_lock.py"],
+    },
     {
         "symbol": "TimelineItem.AddFusionComp / LoadFusionCompByName",
         "object": "TimelineItem (media-backed clip)",
@@ -434,7 +480,16 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "either. Contrast InsertFusionTitleIntoTimeline, whose comp "
                    "DOES render — text set via SetInput('StyledText') appears in "
                    "the output — so this is specific to comps attached to "
-                   "media-backed clips, not to Fusion through the API generally.",
+                   "media-backed clips, not to Fusion through the API generally. "
+                   "REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted "
+                   "MediaIn -> Blur -> MediaOut comp built entirely through "
+                   "the API renders (PSNR 24.38 dB vs the no-comp baseline), "
+                   "so the 2026-08-02 correction stands. Note that an "
+                   "important share of 'the comp was ignored' readings are "
+                   "NOT this entry at all but the Composition.Lock bug above "
+                   "— a parameter written under a comp lock reads back "
+                   "correctly and never reaches the render, which looks "
+                   "identical from the API side.",
         "recommended": "Wire the graph so MediaOut descends from MediaIn — that "
                        "is the difference between a comp that renders and one "
                        "that is silently bypassed, and it is what made this look "