davinci-resolve-mcp 2.98.7 → 2.99.0

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 "
@@ -497,7 +495,19 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "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.",
+                   "identical from the API side. That is what an independent "
+                   "2026-08-20 report on Studio 21.0.4.5 was measuring: a "
+                   "wired MediaIn -> Blur -> MediaOut comp, and a Transform "
+                   "variant, both delivered renders bit-identical to the "
+                   "no-comp baseline (PSNR inf) when built and set through "
+                   "this server. It was read at the time as a version "
+                   "regression (19.1.3.7 honours a wired comp, 21.0.4.5 does "
+                   "not); with the lock bug identified, the simpler reading is "
+                   "that the same defect reproduces on 21.0.4.5 — and since "
+                   "the lock bug has only been isolated on 19.1.3.7, that "
+                   "report is the only evidence it is not build-specific. "
+                   "Treat 'a wired comp renders' as established for 19.1.3.7 "
+                   "and unverified elsewhere.",
         "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 "
@@ -511,8 +521,16 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "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"],
+                       "UI works; only the API-created comp is ignored. "
+                       "Never claim a Fusion effect from comp readback alone — "
+                       "prove it with a rendered frame (gallery_stills "
+                       "grab_and_export before/after, or a delivered render). On "
+                       "setups where even the wired comp does not render (see the "
+                       "2026-08-20 measurement), treat per-item Fusion effects as "
+                       "HITL (a human builds or activates the comp in the UI) and "
+                       "bake stills motion with ffmpeg when unattended output is "
+                       "required.",
+        "tags": ["fusion", "silent-failure", "render", "readback", "hitl"],
         "submit": "bug",
     },
     {
@@ -2146,6 +2164,69 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["gallery", "stills", "headless", "unreliable-return"],
         "submit": "bug",
     },
+    {
+        "symbol": "MediaPool.AppendToTimeline (null-id timeline items)",
+        "object": "MediaPool",
+        "signature": "([{clipInfo}, ...]) -> [TimelineItem]",
+        "reality": "The returned TimelineItem objects can have an unreadable/empty "
+                   "GetUniqueId, notably when the clipInfo recordFrame lands in a "
+                   "span still occupied by another item (any duplicate-then-delete "
+                   "'move' whose offset is smaller than the item duration hits "
+                   "this). The item may not actually exist on the timeline. A "
+                   "session that trusted the non-empty return and deleted the "
+                   "sources lost 26 clips (Portugal timeline, 2026-08-19).",
+        "recommended": "Never treat AppendToTimeline's return as proof of "
+                       "placement. Re-enumerate the track and match on record "
+                       "frame + duration before any dependent delete; never "
+                       "shift items by duplicate-then-delete into occupied "
+                       "spans — use timeline.ripple_insert, which rebuilds the "
+                       "tail into free space and verifies by readback.",
+        "tags": ["editorial", "silent-failure", "unreliable-return", "timeline"],
+        "submit": "bug",
+        "mitigation": ["_append_and_recover_timeline_item duplicate_verified gate",
+                       "_timeline_ripple_insert_impl"],
+    },
+    {
+        "symbol": "TimelineItem.CreateMagicMask (needs operator clicks)",
+        "object": "TimelineItem",
+        "signature": "(mode) -> bool",
+        "reality": "Returns False when the item carries no Magic Mask clicks. "
+                   "Magic Mask v2 is click-driven (manual ch. 139; strokes are "
+                   "the legacy v1 interface) and the scripting API has no way to "
+                   "place a click, so on a fresh item the call can never isolate "
+                   "anything — it only tracks a mask the operator already seeded. "
+                   "Mode strings are 'F', 'B', 'BI'; long spellings like "
+                   "'Forward' are rejected.",
+        "recommended": "Treat CreateMagicMask as track-only: have the operator "
+                       "click the subject (Color page > Magic Mask palette) and "
+                       "then call it, or surface the HITL steps instead of a "
+                       "bare False. Verify isolation with a rendered frame "
+                       "(gallery_stills grab_and_export), never a thumbnail.",
+        "tags": ["ai", "magic-mask", "hitl", "silent-failure"],
+        "submit": "missing",
+        "mitigation": ["_magic_mask_hitl_result"],
+    },
+    {
+        "symbol": "TimelineItem.SetCDL (write-only, no GetCDL)",
+        "object": "TimelineItem",
+        "signature": "({NodeIndex, Slope, Offset, Power, Saturation}) -> bool",
+        "reality": "There is no GetCDL, so applied CDL values cannot be read "
+                   "back; the bool is the only signal and it returns False "
+                   "with no reason (missing node, still/generator item, values "
+                   "silently rejected). NodeIndex is 1-based (README line 6) "
+                   "and must not exceed Graph.GetNumNodes() — note "
+                   "TimelineItem.GetNumNodes is deprecated; the count lives on "
+                   "item.GetNodeGraph().",
+        "recommended": "Read item.GetNodeGraph().GetNumNodes() before SetCDL "
+                       "and diagnose a False against the node count and clip "
+                       "type. Prove the applied look with a rendered frame "
+                       "(gallery_stills grab_and_export or "
+                       "Project.ExportCurrentFrameAsStill), not the return "
+                       "value.",
+        "tags": ["color", "cdl", "readback", "silent-failure"],
+        "submit": "missing",
+        "mitigation": ["_cdl_node_preflight", "_cdl_failure_diagnosis"],
+    },
 ]
 
 

package/src/utils/destructive_hook.py

@@ -78,6 +78,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "move_clips",
         "duplicate_clips",
         "copy_clips",
+        "ripple_insert",
         "copy_range",
         "duplicate_range",
         "overwrite_range",
@@ -225,6 +226,31 @@ STRICT_DEFAULT_ACTIONS: frozenset = frozenset({
 })
 
 
+# ── Plan-only (dry-run) actions ─────────────────────────────────────────────
+#
+# Actions whose payload can declare the call non-mutating. `ripple_insert` is
+# the only destructive action that DEFAULTS to a plan-only call, so without
+# this every routine dry-run plan archives a timeline version — the same waste
+# the pending-confirm skip (F4) exists to prevent, except the pending-confirm
+# skip only fires while the confirm-token preference is ON. With it off, the
+# read-only path of the action littered the version chain.
+
+DRY_RUN_DEFAULT_TRUE_ACTIONS: frozenset = frozenset({
+    ("timeline", "ripple_insert"),
+})
+
+
+def _payload_is_plan_only(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]],
+) -> bool:
+    """True iff this call only produces a plan and mutates nothing."""
+    if (tool_name, action) not in DRY_RUN_DEFAULT_TRUE_ACTIONS:
+        return False
+    if not isinstance(params, dict):
+        return True  # dry_run defaults to True for these actions
+    return bool(params.get("dry_run", params.get("dryRun", True)))
+
+
 def _payload_only_touches_no_archive_keys(
     tool_name: str, action: str, params: Optional[Dict[str, Any]],
 ) -> bool:
@@ -249,6 +275,8 @@ def is_destructive(tool_name: str, action: str, params: Optional[Dict[str, Any]]
         return False
     if _payload_only_touches_no_archive_keys(tool_name, action, params):
         return False
+    if _payload_is_plan_only(tool_name, action, params):
+        return False
     return True