davinci-resolve-mcp 4.5.2 → 4.6.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 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.6.0 — a default project archive no longer crashes Resolve 21.1
+
+The archive coverage measured by @legionsound in [#233](https://github.com/samuelgursky/davinci-resolve-mcp/pull/233), plus the offline node-graph relayout work that was sitting unreleased on `main`.
+
+### Fixed
+
+- **`project_manager` `archive` defaulted source media and render cache ON, and on
+  Resolve 21.1.0.14 a default call crashes Resolve.** ([#233](https://github.com/samuelgursky/davinci-resolve-mcp/pull/233), @legionsound)
+  Measured on Studio 21.1.0.14, one isolated call per case on a disposable project:
+  with source media and proxies off, `ProjectManager.ArchiveProject` returns `False`
+  instantly and writes nothing, open or closed, render cache on or off. With either
+  `isArchiveSrcMedia` or `isArchiveProxyMedia` on it creates an empty directory at the
+  target and Resolve SIGSEGVs in the same second (4 of 4; flags-off 0 of 5), the call
+  comes back through the bridge as `None`, and unsaved work in the open project is
+  lost. A file or folder already at the target survived every case byte for byte, so
+  the destination is never the casualty. 19.1.3.7 agrees where it was measured: this
+  repo's 2026-08-02 mode matrix recorded `False` for `.dra` and folder paths with
+  every flag off. **No scriptable call on either build has produced an archive.**
+  - New `src/utils/archive_guard.py`, shared by the compound `archive`,
+    `safe_project_archive`, and the granular `archive_project`: every flag defaults
+    off; only real booleans are accepted (`bool("false")` is `True`, and two of these
+    flags crash); `src_media` and `proxy_media` are refused unless
+    `acknowledge_trap=true`; the result reports the native return as observed —
+    `True`, `False` ("wrote nothing"), or `None` ("likely crashed; check Resolve is
+    running") — instead of a bare bool.
+  - `safe_project_archive` keeps `allow_media_archive` as the size guard and now also
+    needs `acknowledge_trap` for the crashing flags. One guards size, the other the
+    crash.
+  - Granular `archive_project` now carries the `DESTRUCTIVE_TOOL` annotation and
+    `@granular_destructive_op()`. It previously fell through to plain `WRITE_TOOL`
+    (`archive_` is in no verb table) with no gate.
+  - Both compound actions are in the `destructive_hook` registry and rated MEDIUM in
+    the risk sets, off the ratchet backlog; `safe_project_archive` honours `dry_run`
+    natively and is in `NATIVE_DRY_RUN_ACTIONS`. The refusal is at parameter level
+    rather than a symbol-level `destroys_prior_work`, because a flags-off call is a
+    harmless no-op that should not need acknowledgement.
+  - `api_truth`: new `ProjectManager.ArchiveProject` entry (`verified_on:
+    21.1.0.14`, tagged `reported` — the contributor's measurement) and
+    `ACTION_SYMBOLS` for both actions, so the fact rides on every result as a
+    `known_limitation`. `docs/reference/api-coverage.md` row corrected from "API
+    accepts; archiving is slow"; evidence in `docs/reference/project-archive.md` and
+    `docs/reference/evidence/project-archive-21.1.json`.
+  - Not measured: `RestoreProject` round-trip (nothing produced an archive to
+    restore), render cache on a project that has one, headless 21.1, builds after
+    21.1.0.14, Windows/Linux, and whether the media flags crash 19.1.3.7 — this
+    machine's Resolve was left alone rather than risked on it.
+
+### Added
+
+- **`drp` `relayout_node_graphs` — whole-project Cleanup Node Graph on an exported `.drp`.**
+  The UI command has no scripting API and the two existing paths each had a gap: `drx`
+  `relayout` is one clip at a time, and `project_db` `relayout_node_graphs` needs the
+  project closed plus a full Resolve quit. This one runs on `ExportProject` output and
+  round-trips through `ImportProject` as a sibling, so the open project is never touched.
+  - Indexes **every** node graph the export carries: every LOCAL version of every timeline
+    clip (a clip with three versions is three graphs — the earlier `extract_node_graphs` /
+    `inject_grades` only ever saw the first `<Body>`), remote versions on media-pool clips,
+    group pre/post graphs (`project.xml`), timeline-level graphs.
+  - Scope by anything the `.drp` can name: timeline globs, video track, clip id, clip name /
+    media globs, absolute frame range (overlap), clip position range, color group (a group
+    = its clips + its own graphs), graph kind, active-only / version-name globs, node count,
+    node label. Several scopes union. Unknown selectors are refused (zod `.strict()`), never
+    ignored — an ignored selector would silently widen the sweep to the whole project.
+  - Byte-preserving: only the position varints move (node-layout.js); `HasCorrection` is
+    left exactly as found (this is not a grade change). Resolve's 0x80 **STORED** body
+    container (how it serialises small/default graphs in exports) is now decoded and
+    re-wrapped in kind — before this every ungraded clip read as "not a grade Body".
+  - The default body carries no node message at all (Resolve creates the node lazily in
+    the UI): reported as `empty`, not skipped, not an error. Measured on a 737-clip
+    export: 746 empty, 3 real graphs, 0 skipped.
+  - Write path re-indexes the written file from scratch: same graph count, every rewritten
+    body at the target positions with its node count intact, every untouched body
+    byte-identical, every flag unchanged — a failed read-back deletes the output and throws.
+  - Tests: `test/drp-node-graph-relayout.test.mjs` — fixture in the measured Resolve 19.1.3
+    shapes with a two-version clip, a remote version, group graphs, an empty default, an
+    undecodable body; the full scope matrix incl. a null control; write + idempotence +
+    layout tuning.
+- **Topology-aware relayout (node-layout.js, all three relayout paths).** Positions now
+  come from the graph's own wiring: F8 connection messages (from/to node id, ports —
+  64 = RGB path, 16 = key link — input slot, creation order) and the F9/F10 markers
+  naming the chain's first and last node. Nodes are ranked by longest RGB path (x), a
+  fan-out stacks its branches into lanes ordered by the mixer input slot they feed (y),
+  a merge returns to its lowest input lane, key links never move a node, and an
+  unrankable graph (cycle) falls back to a row in index order and says so in `meta`.
+  - Fixes a latent bug in the row layout: it placed nodes in LIST order, and Resolve
+    lists nodes by id, so any chain with a node inserted mid-way (every traced KICK
+    graph: index order 4,3,6,5,2,7,8,9,1) was laid out scrambled. A chain now lands on
+    the measured row in chain order; generator chains are byte-identical to before.
+  - New options everywhere (`drx` `relayout`, `drp` `relayout_node_graphs`,
+    `project_db` `relayout_node_graphs`): `spacingY` (lane pitch, default 178 —
+    Resolve's own vertical placement grid seen in every stacked export) and
+    `layout`/`mode` = `topology` (default) | `row` (the old behaviour). Every result
+    carries `layout: {kind: chain|dag|row, ranks, lanes, keyLinks}`; the sweep report
+    counts `stackedGraphs`.
+  - NOT yet measured: native Cleanup Node Graph on a graph with a parallel/layer
+    mixer (the lane pitch and how Resolve orders branches). The x row is measured;
+    the lane pitch is a documented default until a mixer graph is cleaned natively
+    and read back. `test/node-layout-topology.test.mjs` pins the planner on rewired
+    real bodies (fan-out + merge, slot order, key link, cycle, row mode, single node).
+
+
 ## What's New in v4.5.2 — granular safety stops guessing, and the audit log stops lying
 
 Two findings from a review of the v4.5.0 enforcement hook, both measured before and

package/README.md

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

package/docs/SKILL.md

@@ -403,7 +403,17 @@ Operating rules an agent must know:
   has no API). Single clip, live: `gallery_stills.grab_and_export` → advanced
   `drx(action="relayout")` → `graph.reset_all_grades` → `safe_apply_drx` with
   EXPLICIT item indices (the reset is required — a same-structure apply keeps
-  the old layout). Whole project, offline: `project_db(action="relayout_node_graphs")`.
+  the old layout). Whole project, offline: `project_db(action="relayout_node_graphs")`
+  (closed project + quit/relaunch). Whole project or ANY SUBSET **without closing it**:
+  `project_manager.export_project` → advanced `drp(action="relayout_node_graphs")`
+  (scope by timeline/track/clip id/name/media/frames/clip position/group/version/node
+  count/node label; covers every LOCAL version of every clip, remote versions, group
+  pre/post and timeline graphs; dry-run first, read-back verified on write) →
+  `project_manager.import_project` as a sibling `<name>_CLEANED`, then re-export THAT
+  and dry-run again to prove the effect. BPA's "Node Graph Cleanup" job is this loop.
+  Layout is topology-aware (rank by RGB wiring, branches stacked into lanes at
+  `spacingY`, key links untouched); the lane pitch is NOT measured against native
+  Cleanup on a mixer graph yet — the x row is.
 - **project_db patches** require the project CLOSED in Resolve plus
   `iConfirmProjectClosed:true`; every write auto-backs-up and read-back
   verifies. Resolve caches open projects in memory: after patching, fully QUIT
@@ -820,7 +830,11 @@ lifecycle, settings, database, preset, and archive boundary helpers:
 - `safe_project_create(name, media_location_path?, dry_run?)`
 - `safe_project_export(name, path, with_stills_and_luts?, dry_run?)`
 - `safe_project_import(path, name, dry_run?)`
-- `safe_project_archive(name, path, src_media=false, render_cache=false, proxy_media=false, dry_run?)`
+- `safe_project_archive(name, path, src_media=false, render_cache=false, proxy_media=false, allow_media_archive?, acknowledge_trap?, dry_run?)`
+  — `src_media` and `proxy_media` crash Resolve 21.1.0.14 (reported, #233); they are refused
+  unless `acknowledge_trap=true`, and every flag defaults off on `archive` too. No
+  scriptable call has produced an archive on 19.1.3.7 or 21.1.0.14; see
+  `docs/reference/project-archive.md`.
 - `safe_project_restore(path, name, dry_run?)`
 - `safe_project_delete(name, close_current?, dry_run?)`
 - `safe_set_project_settings(settings, restore?, dry_run?)`

package/docs/kernels/color-grade-kernel.md

@@ -155,6 +155,9 @@ Cross-server rules an agent must know:
   `drx(action="relayout")` → `graph.reset_all_grades` → `safe_apply_drx` with
   explicit indices (a same-structure apply keeps the OLD layout — the reset is
   required). Whole project, offline: `project_db(action="relayout_node_graphs")`.
+  Any scope, open project: export → `drp(action="relayout_node_graphs")` (every
+  version of every clip + group/timeline graphs; dry-run, read-back verify) →
+  import as a sibling → re-export the sibling and dry-run again.
 - **Deps.** The grading catalog needs `sharp`; call the advanced `capabilities`
   tool for live status and install hints.
 

package/docs/reference/api-coverage.md

@@ -251,7 +251,7 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 
 | # | Method | Status | Test Result / Notes |
 |---|--------|--------|---------------------|
-| 1 | `ArchiveProject(projectName, filePath, ...)` | ⚠️ | API accepts; archiving is slow |
+| 1 | `ArchiveProject(projectName, filePath, ...)` | ⚠️ | Never produces an archive by script: returns `False` and writes nothing with source media and proxies off; either on crashes Resolve 21.1.0.14. Wrappers default every flag off and refuse the crashing two unless `acknowledge_trap`. See [project archive](project-archive.md). |
 | 2 | `CreateProject(projectName, mediaLocationPath)` | ✅ | Creates new project; optional media location added in Resolve 20.2.2 |
 | 3 | `DeleteProject(projectName)` | ⚠️ | Returns `False` if project is open |
 | 4 | `LoadProject(projectName)` | ✅ | Returns Project object |

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 41 missing capabilities, 53 bugs / unreliable behaviors.
+**Totals:** 41 missing capabilities, 54 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -776,3 +776,11 @@ values, or automation-hostile modal prompts.
 - **Behavior:** Gated on the Color page. Measured on all six pages: returns False from media, edit, fusion, fairlight and deliver, and True only from color. The refusal is a bare False with no reason. It does at least fail cleanly - no file is written on the failing pages, so there is no stale-file trap here.
 - **Workaround / current handling:** resolve.OpenPage('color') before the call and restore the prior page afterwards. Treat a False as 'you were on the wrong page' before suspecting the path.
 - **Tags:** page-gated, silent-failure, lut
+
+### ProjectManager.ArchiveProject
+
+- **Object:** `ProjectManager`
+- **Signature:** `(projectName, filePath, isArchiveSrcMedia=True, isArchiveRenderCache=True, isArchiveProxyMedia=False) -> bool`
+- **Behavior:** No scriptable call produces an archive. With source media and proxies off it returns False instantly and writes nothing, for an open or a closed project and with render cache on or off. With isArchiveSrcMedia or isArchiveProxyMedia on it creates an empty directory at the target and Resolve crashes (SIGSEGV) in the same second; the call comes back through the bridge as None and every later handle is dead. Four crashes, one of them in a Blackmagic Cloud library, share identical top stack frames in Fusion script-symbol teardown on the UI thread; a separate crash in the same session during DeleteProject/LoadProject had a different stack, so the signature belongs to the archive calls. Media-flag calls crashed 4 of 4, flags-off calls 0 of 5. A file already at the target survived every case byte for byte, including a crash, so the destination is never overwritten; unsaved work in the open project is what is lost. The native defaults turn source media on, so a default call crashes Resolve. Resolve logs nothing about the False returns.
+- **Workaround / current handling:** Keep isArchiveSrcMedia and isArchiveProxyMedia off unless you have verified the build, and save every open project first. Treat False as 'nothing archived', not as a path problem: a .dra and a folder-style path fail identically. Archive from the Project Manager UI when you need a real archive.
+- **Tags:** crash, unreliable-return, silent-failure, project, reported

package/docs/reference/project-archive.md

@@ -0,0 +1,81 @@
+# Project archive on Resolve 21.1
+
+`ProjectManager.ArchiveProject` has no `api_truth` entry until now, and both of
+this server's archive actions sat in the ratchet's unrated backlog. The native
+defaults, `isArchiveSrcMedia=True` and `isArchiveRenderCache=True`, were
+inherited by both the compound `project_manager archive` action and the granular
+`archive_project` tool. On Studio 21.1.0.14 a default call crashes Resolve.
+
+## Measured
+
+Studio 21.1.0.14, local disk database, one disposable project with one synthetic
+2-second clip on one timeline, archived by name. One isolated call per row, with
+breadcrumbs written to disk before and after so a crash cannot hide which call
+caused it. Presence was checked with `dir()` membership against a known-present
+control, not `hasattr`, which Resolve answers True for any name.
+
+| Case | Returns | Effect |
+| --- | --- | --- |
+| Open project, all flags off | `False` | nothing written, instantly |
+| Closed project, all flags off | `False` | nothing written, instantly |
+| Closed project, render cache only | `False` | nothing written, instantly |
+| Closed project, source media | `None` | empty directory at the target, then Resolve crashes |
+| Closed project, proxy media | `None` | empty directory at the target, then Resolve crashes |
+| Unrelated file at target, flags off | `False` | file byte-identical |
+| Populated directory at target, flags off | `False` | untouched |
+| Source media onto an existing file | `None` | Resolve crashes; file byte-identical |
+
+The crash is SIGSEGV, stamped the same second as the call. A crashing call comes
+back through the bridge as `None`, not a bool, and every handle after it is dead.
+Resolve logs nothing about the `False` returns.
+
+**Media-flag calls crashed 4 of 4; flags-off calls crashed 0 of 5.** The four
+crashes, one of them in a Blackmagic Cloud library on an earlier attempt, share
+identical top stack frames in Fusion script-symbol teardown on the UI thread. A
+fifth crash in the same session, during `DeleteProject` then `LoadProject` 44
+seconds after a relaunch, has a different stack past the generic crash-handler
+frames, so the archive signature is not a general instability. Crash uptimes were
+1:45, 14:16, 1:31 and 0:45.
+
+**The destination is never the casualty.** A file or folder already at the target
+survived every case byte for byte, including the crash. Resolve cannot create its
+bundle folder over an existing file and crashes anyway, so the crash is in starting
+the archive job, not in writing the destination. What is lost is unsaved work in
+the open project.
+
+19.1.3.7 agrees on the part it measured: this repo's mode matrix (2026-08-02, GUI
+and headless) and the project-lifecycle kernel recorded `False` for both a `.dra`
+and a folder-style path with every flag off. No scriptable call on either build has
+produced an archive.
+
+## What changed
+
+- `src/utils/archive_guard.py`: every flag defaults off; only real booleans are
+  accepted, since `bool("false")` is `True` and two flags crash; source media and
+  proxy media are refused unless `acknowledge_trap=true`; the result reports the
+  native return as observed (`True`, `False` with "wrote nothing", or `None` with
+  "likely crashed") rather than a bare bool.
+- Compound `project_manager archive` and `safe_project_archive` use it.
+  `safe_project_archive` keeps its existing `allow_media_archive` size guard and
+  now also needs `acknowledge_trap` for the crashing flags: one guards size, the
+  other the crash.
+- Granular `archive_project`: defaults off, `acknowledge_trap` for the crashing
+  flags, `DESTRUCTIVE_TOOL` annotation and `@granular_destructive_op()`.
+- Both compound actions are registered, rated MEDIUM, and removed from the ratchet
+  backlog. `safe_project_archive` honours `dry_run` natively and is listed as such.
+- `api_truth` gains a `ProjectManager.ArchiveProject` entry and `ACTION_SYMBOLS`
+  maps both compound actions to it, so the measured fact rides on every result.
+
+## A design question for the maintainer
+
+The entry deliberately does **not** set `destroys_prior_work`. That flag is
+symbol-level, so every mapped action would refuse until acknowledged, including
+the flags-off call, which is a harmless no-op. The refusal here is parameter-level
+instead, in the wrappers. If the symbol-level trap is preferred, it is a one-line
+change plus the granular confirmation tier.
+
+## Not tested
+
+No scriptable call produced an archive, so a `RestoreProject` round-trip could not
+be measured. Also untested: render cache on a project that has one, headless mode
+on 21.1, builds after 21.1.0.14, and Windows or Linux.

package/install.py

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

package/resolve-advanced/README.md

@@ -79,6 +79,16 @@ Each dispatches on an `action`. Highlights:
 - **`drx`** — per-clip grade (`.drx`) codec: `parse`, `generate`, `generate_from_request`,
   `export_cdl`, `merge`, plus the **grading/QC catalog** below.
 - **`drp` / `drt`** — project / timeline file authoring + editing + grade injection + structural diff.
+  `drp` `relayout_node_graphs` is the whole-project **Cleanup Node Graph** (the UI command has
+  no API): every node graph an exported `.drp` carries — every LOCAL version of every clip,
+  remote versions, group pre/post, timeline-level — relaid out to Resolve's clean row with the
+  grade bytes untouched and `HasCorrection` as found; scoped by timeline / track / clip id /
+  name / media / frame range / clip position / color group / version / node count / node
+  label; dry-run report, read-back verify. Round trip: `export_project` → `relayout_node_graphs`
+  → `import_project` as a sibling. Single `.drx`: `drx` `relayout`; closed `Project.db`:
+  `project_db` `relayout_node_graphs`. All three are topology-aware: nodes rank by their
+  RGB wiring (chain order, not list order), branches stack into lanes, key links stay put;
+  `layout: row` is the old single-row mode.
 - **`conform`** — offline conform/relink QC engine (frame-oracle math, not filename matching),
   reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC (sampled clear of
   transition windows; ingests Resolve's own FCP7 export — `-1` edges → junctions, no ticks needed).