davinci-resolve-mcp 4.15.3 → 4.15.5

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 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 v4.15.5 — DRX applies say which graph changed
+
+`graph.apply_grade_from_drx` and `timeline_item_color.safe_apply_drx` no
+longer report a bare `success` from `ApplyGradeFromDRX`. They read the graphs
+back, and they refuse a timeline apply that would load no timeline grade.
+
+### Fixed
+
+- **A timeline apply of a .drx with no timeline grade is refused** (#318).
+  A .drx keeps the clip grade in `<pClipFullVer>` and the timeline grade in
+  `<pTrackVer>`. `drx generate`'s single-node path writes no `<pTrackVer>`,
+  and native stills and the multi-node path write one with
+  `HasCorrection false`. On Studio 21.1.1.10 such an apply was reported to
+  return True, add nothing and empty the timeline graph. With
+  `source="timeline"`, both actions now return `DRX_NO_TIMELINE_GRADE` before
+  the confirm token is issued and before Resolve is called.
+- **DRX applies read back every graph the grade could land in** (#319).
+  The node count, labels and LUTs of the clip graph, the clip's color-group
+  pre- and post-clip graphs and the timeline graph are read before and
+  after. The result carries `changed_graphs`, a per-graph before/after count
+  and a `verification` block, so the result no longer says
+  `readback_checked: false`. When only a graph you did not target changed,
+  the call fails with `DRX_APPLIED_TO_OTHER_GRAPH`. When no graph changed it
+  still reports success, with a `warning`: a grade with the same node
+  structure changes only parameters, which no readback reaches.
+
+### Documentation
+
+- Two `api_truth` entries for the reported behaviour, mapped to both apply
+  actions, with what Studio 19.1.3.7 did when we measured it.
+- New live harness `tests/live_drx_apply_readback_validation.py`.
+
+### Validation
+
+- Full offline suite: 4,242 tests, OK. 12 new unit tests cover the file
+  check, both refusals, the group pre-clip landing case, a verified change,
+  the no-change warning, a color-group target and `safe_apply_drx`.
+- Live on Studio 19.1.3.7, disposable project, one synthetic clip, a grade
+  from `drx generate`: 0 failures. The refusal fired and left the timeline
+  graph alone; the clip apply was detected through the node label
+  (`changed_graphs: ["item"]`); the same-structure re-apply warned; a
+  grouped clip's readback covered both group graphs.
+- Neither reported behaviour reproduces on 19.1.3.7. Every timeline-graph
+  apply returned False and changed nothing, with or without a timeline
+  grade, so a successful timeline apply was not observed. A grouped clip took
+  the grade in its own graph. Both were reported on Studio 21.1.1.10, which
+  was not available for this release.
+
+## What's New in v4.15.4 — add_keyframe no longer leaves a stray key
+
+### Fixed
+
+- **`fusion_comp(action="add_keyframe")` removes the key Fusion adds when an
+  input is first animated** (#317, thanks @assassin007-hub). Attaching an
+  empty BezierSpline keys the comp's current time with the input's old value,
+  so keying frames 10 and 20 left keys `[0, 10, 20]` and the curve ramped from
+  the old value instead of holding until the first intended key. The first
+  call on an input now deletes that key after the real one is written, reads
+  the keys back, and returns `removed_stray_keys`, or `stray_keys_remaining`
+  with a `warning` pointing to `delete_keyframe` if a key survives. A key
+  written at the current time simply overwrites it. Text Follower range
+  bounds (±1e9) are not treated as keys.
+
+### Documentation
+
+- Two measured `api_truth` entries: BezierSpline LH/RH handles are offsets
+  from their key, not absolute points; and the stray key an empty spline
+  attach leaves, now attached to `fusion_comp add_keyframe`.
+
+### Validation
+
+- CI passed on Python 3.10 and 3.11 and on the advanced Node suite under
+  Node 20 and 22. Full offline suite run against main: 4,230 tests, with only
+  the 4 `source_media_guard` failures that always occur in a scratch worktree.
+- Live behavior was measured by the contributor on Studio 21.0.2.4 (keys
+  `[0, 10, 20]` before, `[10, 20]` after `DeleteKeyFrames`). It was not
+  re-run on 19.1.3.7 for this release.
+
 ## What's New in v4.15.3 — CI covers the version floors
 
 No server behavior changed. Pull requests are now tested on the oldest Python

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.15.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.15.5-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-37%20(390%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/install.py

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

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.15.3"
+VERSION = "4.15.5"
 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 377-tool granular server instead
 """
 
-VERSION = "4.15.3"
+VERSION = "4.15.5"
 
 import base64
 import os
@@ -29221,6 +29221,160 @@ def _color_graph_from_params(proj, item, p: Dict[str, Any]):
     return None, source, _err(f"Unknown color graph source: {source}")
 
 
+def _drx_track_grade_state(path) -> str:
+    """What a .drx holds for a TIMELINE apply: "present", "empty", "missing" or "unreadable".
+
+    A .drx keeps the clip grade in <pClipFullVer> and the timeline grade in
+    <pTrackVer>. A timeline ApplyGradeFromDRX loads <pTrackVer>, and when that
+    block has HasCorrection false it replaces the timeline graph with an empty
+    one and still returns True (issue #318).
+    """
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except OSError:
+        return "unreadable"
+    block = re.search(r"<pTrackVer>(.*?)</pTrackVer>", text, re.DOTALL)
+    if not block:
+        return "missing"
+    has = re.search(r"<HasCorrection>\s*(true|false)\s*</HasCorrection>", block.group(1), re.IGNORECASE)
+    return "present" if has and has.group(1).lower() == "true" else "empty"
+
+
+def _refuse_empty_track_grade(path, source):
+    """Error envelope when a timeline apply would load no timeline grade, else None."""
+    if source != "timeline":
+        return None
+    state = _drx_track_grade_state(path)
+    if state not in ("missing", "empty"):
+        return None
+    return _err(
+        "This .drx carries no timeline grade (<pTrackVer> is "
+        f"{'absent' if state == 'missing' else 'empty, HasCorrection false'}). Applying it to the "
+        "timeline graph would change nothing and replace the existing timeline graph with an empty one.",
+        code="DRX_NO_TIMELINE_GRADE", category="invalid_input",
+        remediation="Apply it to a clip (source='item') instead, or use a .drx exported from a "
+                    "timeline grade. To clear the timeline graph on purpose, use reset_all_grades.",
+        state={"path": path, "track_grade": state},
+    )
+
+
+def _graph_fingerprint(g):
+    """Node count plus each node's label and LUT; None when the graph can't be read.
+
+    GetToolsInNode is left out on purpose: it crashes Resolve 19.1.3 on some graphs.
+    """
+    if not g:
+        return None
+    try:
+        count = int(g.GetNumNodes() or 0)
+    except Exception:
+        return None
+    nodes = []
+    for node_index in range(1, count + 1):
+        row = {}
+        for key, method_name in (("label", "GetNodeLabel"), ("lut", "GetLUT")):
+            if _has_method(g, method_name):
+                try:
+                    row[key] = _ser(getattr(g, method_name)(node_index))
+                except Exception:
+                    row[key] = None
+        nodes.append(row)
+    return {"num_nodes": count, "nodes": nodes}
+
+
+def _drx_candidate_graphs(source, *, item=None, tl=None, group=None, layer_index=None):
+    """{name: getter} for every graph a .drx apply could land in, the target included.
+
+    The clip graph, its color group's pre/post-clip graphs and the timeline graph
+    are all candidates: on a clip in a group the grade can land in the group's
+    pre-clip graph instead of the clip's (issue #319).
+    """
+    out = {}
+    if item is not None:
+        out["item"] = lambda: item.GetNodeGraph(layer_index) if layer_index is not None else item.GetNodeGraph()
+        if group is None:
+            try:
+                group = item.GetColorGroup()
+            except Exception:
+                group = None
+    if group is not None:
+        out["color_group_pre"] = group.GetPreClipNodeGraph
+        out["color_group_post"] = group.GetPostClipNodeGraph
+    if tl is None:
+        try:
+            _, tl, _tl_err = _get_tl()
+        except Exception:
+            tl = None
+    if tl is not None:
+        out["timeline"] = tl.GetNodeGraph
+    if source not in out:
+        out[source] = None
+    return out
+
+
+def _apply_drx_with_readback(graph, source, path, grade_mode, candidates):
+    """ApplyGradeFromDRX, with every candidate graph read before and after.
+
+    The native True does not say where the grade went or whether anything
+    changed, so the result reports which graphs changed. A grade that lands only
+    in another graph is a failure. Nothing changing is reported but not failed:
+    a same-structure apply changes only parameters, which the API cannot read.
+    """
+    def read(getter):
+        try:
+            return _graph_fingerprint(getter()) if getter else None
+        except Exception:
+            return None
+
+    if candidates.get(source) is None:
+        candidates = {**candidates, source: lambda: graph}
+    before = {name: read(getter) for name, getter in candidates.items()}
+    native = bool(graph.ApplyGradeFromDRX(path, grade_mode))
+    after = {name: read(getter) for name, getter in candidates.items()}
+
+    graphs = {}
+    changed, unreadable = [], []
+    for name in candidates:
+        b, a = before[name], after[name]
+        if b is None or a is None:
+            unreadable.append(name)
+            graphs[name] = {"readable": False}
+            continue
+        graphs[name] = {"num_nodes_before": b["num_nodes"], "num_nodes_after": a["num_nodes"],
+                        "changed": b != a}
+        if b != a:
+            changed.append(name)
+
+    landed_elsewhere = bool(changed) and source not in changed
+    verification = {
+        "verified": source in changed,
+        "contradiction": landed_elsewhere,
+        "method": "node count, labels and LUTs of each graph before and after",
+    }
+    result = {"success": native, "path": path, "source": source, "changed_graphs": changed,
+              "graphs": graphs, "verification": verification}
+    if unreadable:
+        result["unreadable_graphs"] = unreadable
+    if landed_elsewhere:
+        err = _err(
+            f"The grade was applied to the {', '.join(changed)} graph, not the {source} graph that "
+            "was targeted. Resolve returned " + ("True" if native else "False") + ".",
+            code="DRX_APPLIED_TO_OTHER_GRAPH", category="resolve_api_failed", retryable=False,
+            remediation="Check the Node Editor's graph dropdown (Clip / Group Pre-Clip / Group "
+                        "Post-Clip / Timeline) on the Color page, then restore the changed graph "
+                        "from a still or grade version before retrying.",
+            state={"targeted": source, "changed_graphs": changed},
+        )
+        return {**result, **err, "success": False}
+    if native and not changed:
+        result["warning"] = (
+            "No graph changed its node count, labels or LUTs. Either the grade has the same node "
+            "structure as before (only parameters changed, which the API cannot read back) or "
+            "nothing was applied; confirm with a rendered frame or the scopes.")
+    return result
+
+
 def _grade_version_snapshot(item, p: Dict[str, Any]):
     out = {"current": None, "local": [], "remote": [], "errors": []}
     try:
@@ -29487,6 +29641,9 @@ def _safe_apply_drx(proj, item, p: Dict[str, Any]):
     if not _has_method(graph, "ApplyGradeFromDRX"):
         return _err(f"{source} graph does not expose ApplyGradeFromDRX",
                     code="APPLY_DRX_UNSUPPORTED", category="unsupported")
+    refused = _refuse_empty_track_grade(path, source)
+    if refused:
+        return refused
     if _coerce_bool(p.get("dry_run")):
         return _ok(path=path, source=source, grade_mode=p.get("grade_mode", p.get("mode", 0)), would_apply=True)
     # B2 — Whole-grade replacement is catastrophic; require confirmation.
@@ -29503,8 +29660,13 @@ def _safe_apply_drx(proj, item, p: Dict[str, Any]):
     blocked = _consume_confirm_token(action="safe_apply_drx", params=p)
     if blocked:
         return blocked
-    success = bool(graph.ApplyGradeFromDRX(path, p.get("grade_mode", p.get("mode", 0))))
-    return {"success": success, "path": path, "source": source}
+    group = None
+    if source in ("color_group_pre", "color_group_post"):
+        group = next((g for g in proj.GetColorGroupsList() or [] if g.GetName() == p.get("group_name")), None)
+    candidates = _drx_candidate_graphs(
+        source, item=item, group=group,
+        layer_index=p.get("layer_index") if source == "item" else None)
+    return _apply_drx_with_readback(graph, source, path, p.get("grade_mode", p.get("mode", 0)), candidates)
 
 
 # ── color_trace apply driver ─────────────────────────────────────────────────
@@ -29920,7 +30082,7 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
         "safe_apply_drx": {
             "summary": "Apply a .drx grade. REPLACES the target graph; gated by confirm_token.",
             "params": "path: str, source?, grade_mode? (0=no keyframes, 1=source TC aligned, 2=start aligned), require_temp_path?, confirm_token?",
-            "returns": "{success, path, source}",
+            "returns": "{success, path, source, changed_graphs, graphs, verification, warning?} (same readback and refusals as graph.apply_grade_from_drx)",
             "example": (
                 'timeline_item_color(action="safe_apply_drx", params={\n'
                 '  "track_type": "video", "track_index": 1, "item_index": 0,\n'
@@ -30110,7 +30272,7 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
         "apply_grade_from_drx": {
             "summary": "REPLACES the entire node graph from a .drx. Confirm_token required.",
             "params": "path, grade_mode? (0/1/2), source?",
-            "returns": "{success}",
+            "returns": "{success, path, source, changed_graphs, graphs, verification, warning?} — changed_graphs names every graph whose node count, labels or LUTs changed; DRX_APPLIED_TO_OTHER_GRAPH when only a graph you did not target changed; DRX_NO_TIMELINE_GRADE when source=timeline and the .drx has no timeline grade",
             "example": (
                 'graph(action="apply_grade_from_drx", params={\n'
                 '  "path": "/tmp/look.drx", "grade_mode": 0, "source": "item"\n'
@@ -30726,7 +30888,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
     propose_grade       -> {accepted: bool, validation, plan_id?, preview_path?, error?}
     safe_set_cdl        -> {success, validation, normalized, node_preflight, diagnosis?}
     safe_copy_grade     -> {success, targets, missing}
-    safe_apply_drx      -> {success, path, source}  # first call may return confirm_token
+    safe_apply_drx      -> {success, path, source, changed_graphs, graphs, verification, warning?}  # first call may return confirm_token
     apply_trace_plan    -> {success, timeline, applied, failed, skipped, summary}  # dry_run → {resolution}; first live call returns confirm_token
     grade_capabilities  -> {item_methods, graph_sources, lut_export_types, guards}
     grade_boundary_report -> {capabilities, item, color_groups, gallery}
@@ -30766,7 +30928,7 @@ def timeline_item_color(action: str, params: Optional[Dict[str, Any]] = None) ->
       safe_copy_grade(target_ids, dry_run?, ...) -> {success, targets, missing}
         Copies grade to N items; dry_run reports targets without mutating.
         # example: action_help(name='<action_name>')
-      safe_apply_drx(path, source?, grade_mode?, require_temp_path?) -> {success}
+      safe_apply_drx(path, source?, grade_mode?, require_temp_path?) -> {success, path, source, changed_graphs, graphs, verification, warning?}
         REPLACES the target graph. Captures a version snapshot first; require_temp_path defaults True.
         # example: action_help(name='<action_name>')
       apply_trace_plan(plan_path|plan, dry_run?, min_confidence?=0.8, start_tolerance?=0, grade_mode?=0, version_name?, require_temp_path?=True, allow_timeline_mismatch?, max_rows?=40, verbose?, report_path?, confirm_token?) -> {success, applied, failed, skipped, attention, summary, report_path}
@@ -31332,7 +31494,10 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         UNSAFE. Assigns a LUT to an existing node. No snapshot/dry_run.
       set_node_cache(node_index, cache_value, source?, ...) -> {success}
       set_node_enabled(node_index, enabled, source?, ...) -> {success}
-      apply_grade_from_drx(path, grade_mode?, source?, ...) -> {success}
+      apply_grade_from_drx(path, grade_mode?, source?, ...) -> {success, path, source, changed_graphs, graphs, verification, warning?}
+        Reads the clip, color-group pre/post and timeline graphs before and after and
+        reports changed_graphs; fails if the grade landed only in a graph not targeted.
+        source="timeline" refuses a .drx whose <pTrackVer> has no correction.
         CATASTROPHIC. REPLACES the entire node graph. Prefer timeline_item_color.safe_apply_drx
         (confirm-token gated + validated; it does NOT snapshot — grab a still/.drx backup
         first, and ALWAYS pass track_type/track_index/item_index explicitly: the default
@@ -31359,6 +31524,7 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
 
     # Get the graph object based on source
     g = None
+    item = group = None
     if source == "timeline":
         _, tl, err = _get_tl()
         if err:
@@ -31376,6 +31542,7 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         groups = proj.GetColorGroupsList() or []
         for cg in groups:
             if cg.GetName() == p.get("group_name"):
+                group = cg
                 g = cg.GetPreClipNodeGraph() if source == "color_group_pre" else cg.GetPostClipNodeGraph()
                 break
         if g is None:
@@ -31429,6 +31596,9 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     elif action == "set_node_enabled":
         return {"success": bool(g.SetNodeEnabled(p["node_index"], p["enabled"]))}
     elif action == "apply_grade_from_drx":
+        refused = _refuse_empty_track_grade(p["path"], source)
+        if refused:
+            return refused
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="graph.apply_grade_from_drx",
@@ -31440,7 +31610,9 @@ def graph(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         blocked = _consume_confirm_token(action="graph.apply_grade_from_drx", params=p)
         if blocked:
             return blocked
-        return {"success": bool(g.ApplyGradeFromDRX(p["path"], p.get("grade_mode", p.get("mode", 0))))}
+        candidates = _drx_candidate_graphs(source, item=item, group=group,
+                                           layer_index=p.get("layer_index"))
+        return _apply_drx_with_readback(g, source, p["path"], p.get("grade_mode", p.get("mode", 0)), candidates)
     elif action == "apply_arri_cdl_lut":
         return {"success": bool(g.ApplyArriCdlLut())}
     elif action == "reset_all_grades":
@@ -32535,6 +32707,32 @@ def _fusion_input_spline(inp):
         return None
 
 
+def _fusion_remove_stray_keys(inp, stray: List[float]) -> Dict[str, Any]:
+    """Delete the keys Fusion added when add_keyframe attached a spline.
+
+    The result is read back rather than trusted: a key that is still there is
+    reported, so a caller is never told the curve holds only what it wrote.
+    """
+    spline = _fusion_input_spline(inp)
+    if spline is not None and _has_method(spline, "DeleteKeyFrames"):
+        for frame in stray:
+            try:
+                spline.DeleteKeyFrames(frame)
+            except Exception:
+                pass
+    remaining = [f for f in _fusion_keyframe_frames(inp)
+                 if any(abs(f - s) < 1e-6 for s in stray)]
+    removed = [s for s in stray if not any(abs(s - f) < 1e-6 for f in remaining)]
+    if not remaining:
+        return _ok(removed_stray_keys=removed)
+    return _ok(
+        removed_stray_keys=removed,
+        stray_keys_remaining=remaining,
+        warning=(f"Attaching the spline also keyed frame(s) {remaining} with the old value "
+                 "and they could not be removed; remove them with delete_keyframe."),
+    )
+
+
 def _fusion_delete_keyframe(tool, p: Dict[str, Any]) -> Dict[str, Any]:
     """Remove one keyframe from an animated Fusion input. (issue #155)
 
@@ -32953,6 +33151,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 _already_animated = inp.GetConnectedOutput() is not None
             except Exception:
                 _already_animated = False
+            _stray = []
             if not _already_animated:
                 _is_nest, _members = _fusion_nest_members(tool, p["input_name"])
                 if _is_nest:
@@ -32986,8 +33185,21 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                                     "attach it with add_modifier, then drive the "
                                     "modifier tool it returns.",
                     )
+                # Attaching an empty spline keys the comp's CURRENT time with the
+                # input's old value (measured on Studio 21.0.2.4: keying 10 and 20
+                # left [0, 10, 20]). Note it now; it is removed after the real key
+                # lands, since DeleteKeyFrames will not remove a spline's only key.
+                # Only a spline holds keys; a text Follower answers GetKeyFrames
+                # with its +/-1e9 render-range bounds, which are not keys.
+                _spline = _fusion_input_spline(tool[p["input_name"]])
+                if _spline is not None and _has_method(_spline, "DeleteKeyFrames"):
+                    _stray = [f for f in _fusion_keyframe_frames(tool[p["input_name"]])
+                              if abs(f) < 1e8]
             tool[p["input_name"]][p["time"]] = p["value"]
-            return _ok()
+            _stray = [f for f in _stray if abs(f - float(p["time"])) >= 1e-6]
+            if not _stray:
+                return _ok()
+            return _fusion_remove_stray_keys(tool[p["input_name"]], _stray)
         finally:
             comp.EndUndo(True)
 

package/src/utils/api_truth.py

@@ -2016,6 +2016,62 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "reports {page: {before, switched, restored}}.",
         "tags": ["silent-failure", "color", "grade", "page", "drx", "version"],
     },
+    {
+        "symbol": "Graph.ApplyGradeFromDRX (timeline graph, empty pTrackVer)",
+        "object": "Graph",
+        "signature": "Timeline.GetNodeGraph().ApplyGradeFromDRX(path, gradeMode) -> bool",
+        "reality": "A .drx holds the clip grade in <pClipFullVer> (VerType 0) and the "
+                   "timeline grade in <pTrackVer> (VerType 1); a timeline-graph apply "
+                   "loads <pTrackVer>. When that block has HasCorrection false, which is "
+                   "what drx generate (direct) writes and what a clip still carries, "
+                   "the apply returns True, adds no grade and replaces the existing "
+                   "timeline graph with an empty one, deleting any node on it. Copying "
+                   "the clip <Body> into <pTrackVer> with HasCorrection true applied as "
+                   "expected (0 -> 1 node, no other graph changed).",
+        "recommended": "Check the file's <pTrackVer> before a timeline apply. "
+                       "graph.apply_grade_from_drx and timeline_item_color.safe_apply_drx "
+                       "with source='timeline' refuse a .drx whose <pTrackVer> is absent or "
+                       "has HasCorrection false (DRX_NO_TIMELINE_GRADE). Clear the "
+                       "timeline graph on purpose with reset_all_grades.",
+        "tags": ["silent-failure", "color", "grade", "drx", "node-graph", "timeline"],
+        "issue": 318,
+        "mitigation": ["_refuse_empty_track_grade"],
+        "verified_on": "DaVinci Resolve Studio 21.1.1.10 (issue #318; not re-measured here)",
+        "measured": "2026-10-27 on Studio 19.1.3.7 (tests/live_drx_apply_readback_validation.py): "
+                    "every Timeline.GetNodeGraph().ApplyGradeFromDRX returned False and left the "
+                    "timeline graph at 0 nodes, with the timeline grade present or empty, so "
+                    "the empty-graph replacement does not reproduce on that build. drx "
+                    "generate's single-node path writes no <pTrackVer> at all; the multi-node "
+                    "path writes one with HasCorrection false.",
+    },
+    {
+        "symbol": "Graph.ApplyGradeFromDRX (grade lands in another graph)",
+        "object": "Graph",
+        "signature": "TimelineItem.GetNodeGraph().ApplyGradeFromDRX(path, gradeMode) -> bool",
+        "reality": "The True return does not say which graph took the grade. On a clip "
+                   "in a color group, applying to the clip's graph replaced node 1 of "
+                   "the group's pre-clip graph instead (removing the LUT the group "
+                   "shared) and left the clip graph at one empty node. The manual says "
+                   "the Node Editor's graph dropdown (Clip / Group Pre-Clip / Group "
+                   "Post-Clip / Timeline) decides where a still's grade lands; whether "
+                   "the API follows the same rule has not been confirmed.",
+        "recommended": "Read every graph the grade could land in before and after the "
+                       "apply. graph.apply_grade_from_drx and "
+                       "timeline_item_color.safe_apply_drx compare node count, labels and "
+                       "LUTs of the clip, group pre/post and timeline graphs, return "
+                       "changed_graphs, and fail with DRX_APPLIED_TO_OTHER_GRAPH when only "
+                       "an untargeted graph changed. No change at all is reported, not "
+                       "failed: a same-structure grade changes only parameters, which no "
+                       "readback reaches, so confirm with a rendered frame.",
+        "tags": ["silent-failure", "color", "grade", "drx", "node-graph", "readback"],
+        "issue": 319,
+        "mitigation": ["_apply_drx_with_readback"],
+        "verified_on": "DaVinci Resolve Studio 21.1.1.10 (issue #319; not re-measured here)",
+        "measured": "2026-10-27 on Studio 19.1.3.7 (tests/live_drx_apply_readback_validation.py): "
+                    "a clip assigned to a color group took the grade in its own graph; the "
+                    "group pre/post graphs did not change. The readback detected the clip "
+                    "change through the node label.",
+    },
     {
         "symbol": "MediaPool.AppendToTimeline clipInfo endFrame (exclusive bound)",
         "object": "MediaPool",
@@ -3915,6 +3971,64 @@ API_TRUTH: List[Dict[str, Any]] = [
         "verified_on": "DaVinci Resolve Studio 19.1.3.7",
         "mitigation": ["_timeline_replace_source_range_impl"],
     },
+    {
+        "symbol": "BezierSpline.SetKeyFrames (handle coordinates)",
+        "object": "Fusion BezierSpline",
+        "signature": "(keyframes, replace) -> None",
+        "reality": "A key's LH/RH handles are OFFSETS from that key, {1: dTime, 2: dValue}, "
+                   "not absolute (time, value) points. GetKeyFrames() reads them back the "
+                   "same way: Fusion's own auto-created first key returns RH {1: 2.0, "
+                   "2: -0.333} for a key at frame 0 easing toward the next one. Absolute "
+                   "coordinates are accepted without complaint and read back verbatim, so "
+                   "nothing flags the mistake; the curve is simply wrong. Measured with keys "
+                   "0 -> 1 at frames 10 -> 20: flat handles written relative ({3, 0} / "
+                   "{-3, 0}) sample 0, 0.113, 0.5, 0.887, 1 at frames 10/12/15/18/20, a clean "
+                   "ease-in-out; the same intent written absolute ({13, 0} / {17, 1}) "
+                   "samples 0, 0.015, 0.089, 0.217, 1. A whip authored with absolute handles "
+                   "moved the wrong way (0.5 -> 0.56) before snapping to its end value.",
+        "recommended": "Write handles relative to their key: RH = {segment * k, 0} and "
+                       "LH = {-segment * k, 0} gives a flat-tangent ease, where k is the handle "
+                       "length as a fraction of the segment (0.33 is a standard ease, 0.6 to "
+                       "0.75 an expo-like snap). Prove a curve by sampling "
+                       "tool.GetInput(name, frame) at a few frames, not by reading the keys "
+                       "back.",
+        "tags": ["fusion", "keyframe", "silent-failure", "units"],
+        "verified_on": "DaVinci Resolve Studio 21.0.2.4",
+        "measured": "2026-10-26 on a Fusion composition clip: BezierSpline keyed 10 -> 20 "
+                    "with relative vs absolute flat handles, connected to Blur YBlurSize, "
+                    "sampled with GetInput at frames 10/12/15/18/20; whip Transform Center "
+                    "via XYPath confirmed in rendered frames.",
+    },
+    {
+        "symbol": "BezierSpline attach (stray key at the current time)",
+        "object": "Fusion Tool input / BezierSpline",
+        "signature": "tool.AddModifier(input, 'BezierSpline') | tool[input] = comp.BezierSpline()",
+        "reality": "Connecting an EMPTY spline to an input, by either route, adds a key at "
+                   "the comp's current time holding the input's old value. Keys set "
+                   "afterwards are added next to it, and SetKeyFrames(keys, True) does not "
+                   "remove it despite the replace flag. Measured with CurrentTime 0: "
+                   "AddModifier then input[10] = 5, input[20] = 9 left keys [0, 10, 20] with "
+                   "1.0 (the old value) at frame 0, so the value drifts from 1.0 before the "
+                   "first intended key instead of holding. The stray key can be deleted with "
+                   "spline.DeleteKeyFrames(time) once other keys exist; deleting it while it "
+                   "is the only key does nothing. A spline that already has keys when it is "
+                   "connected gets no extra key.",
+        "recommended": "Build the spline first and connect it last: s = comp.BezierSpline(); "
+                       "s.SetKeyFrames(keys, True); tool[input] = s. When the spline is "
+                       "already attached, delete the stray key (DeleteKeyFrames(time)) after "
+                       "the intended keys are written, then confirm with GetKeyFrames(). "
+                       "fusion_comp add_keyframe does this itself: its first call on an "
+                       "input deletes the stray key, reports it as removed_stray_keys, and "
+                       "returns stray_keys_remaining plus a warning if it survives.",
+        "tags": ["fusion", "keyframe", "silent-failure"],
+        "mitigation": ["fusion_comp.add_keyframe", "_fusion_remove_stray_keys"],
+        "verified_on": "DaVinci Resolve Studio 21.0.2.4",
+        "measured": "2026-10-26 on a Fusion composition clip (CurrentTime 0), on a Blur: "
+                    "AddModifier + two indexed writes -> keys [0, 10, 20]; empty spline "
+                    "connected then SetKeyFrames(replace=True) -> [0, 10, 20]; "
+                    "DeleteKeyFrames(0.0) then -> [10, 20]; spline keyed before connect -> "
+                    "[10, 20].",
+    },
 
 ]
 
@@ -3973,10 +4087,21 @@ ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
     ("timeline", "apply_look_to_items"): ["TimelineItem.CopyGrades"],
     ("timeline_item_color", "export_lut"): ["TimelineItem.ExportLUT"],
     ("timeline_item_color", "safe_export_lut"): ["TimelineItem.ExportLUT"],
+    ("graph", "apply_grade_from_drx"): [
+        "Graph.ApplyGradeFromDRX (timeline graph, empty pTrackVer)",
+        "Graph.ApplyGradeFromDRX (grade lands in another graph)",
+    ],
+    ("timeline_item_color", "safe_apply_drx"): [
+        "Graph.ApplyGradeFromDRX (timeline graph, empty pTrackVer)",
+        "Graph.ApplyGradeFromDRX (grade lands in another graph)",
+    ],
     ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
     ("project_manager", "archive"): ["ProjectManager.ArchiveProject"],
     ("fusion_comp", "add_modifier"): ["Tool.AddModifier", "Tool.AddModifier (NestControl inputs)"],
-    ("fusion_comp", "add_keyframe"): ["Tool.AddModifier (NestControl inputs)"],
+    ("fusion_comp", "add_keyframe"): [
+        "Tool.AddModifier (NestControl inputs)",
+        "BezierSpline attach (stray key at the current time)",
+    ],
     ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
     ("render", "start"): ["Project.StartRendering"],
     ("resolve_control", "set_high_priority"): [