davinci-resolve-mcp 4.5.2 → 4.6.0

package/resolve-advanced/server/tools/drx.mjs

@@ -128,6 +128,8 @@ const relayoutSchema = z
     originX: z.number().int().optional().describe('Clean-row start x (default 290 — matches native Cleanup Node Graph)'),
     originY: z.number().int().optional().describe('Clean-row y (default 428)'),
     spacingX: z.number().int().optional().describe('Clean-row x spacing (default 495)'),
+    spacingY: z.number().int().optional().describe('Lane pitch for stacked branches (default 178; unmeasured against native Cleanup on mixers)'),
+    layout: z.enum(['topology', 'row']).optional().describe('topology (default): rank by wiring, stack branches; row: single row in list order'),
   })
   .refine((a) => a.drxPath || a.content, { message: 'provide drxPath or content' });
 
@@ -815,6 +817,8 @@ export const drxTool = {
         originX: p.originX,
         originY: p.originY,
         spacingX: p.spacingX,
+        spacingY: p.spacingY,
+        layout: p.layout,
       });
       // Splice the new Body into the ORIGINAL envelope (byte-lossless outside the
       // position varints — labels, keyframes, OFX, still metadata all pass through).
@@ -826,9 +830,9 @@ export const drxTool = {
       }
       if (p.outPath) {
         await fs.writeFile(p.outPath, out);
-        return { outPath: p.outPath, nodeCount: r.nodeCount, positionsBefore: before, positions: r.positions };
+        return { outPath: p.outPath, nodeCount: r.nodeCount, positionsBefore: before, positions: r.positions, layout: r.meta };
       }
-      return { content: out, nodeCount: r.nodeCount, positionsBefore: before, positions: r.positions };
+      return { content: out, nodeCount: r.nodeCount, positionsBefore: before, positions: r.positions, layout: r.meta };
     }
 
     if (action === 'contrast_normalize') {

package/resolve-advanced/server/tools/project_db.mjs

@@ -62,6 +62,8 @@ const relayoutSchema = z.object({
   originX: z.number().int().optional().describe('Clean-row start x (default 290 — matches native Cleanup Node Graph)'),
   originY: z.number().int().optional().describe('Clean-row y (default 428)'),
   spacingX: z.number().int().optional().describe('Clean-row x spacing (default 495)'),
+  spacingY: z.number().int().optional().describe('Lane pitch for stacked branches (default 178)'),
+  layout: z.enum(['topology', 'row']).optional().describe('topology (default) or row'),
   iConfirmProjectClosed: confirm,
 });
 
@@ -172,7 +174,7 @@ export const projectDbTool = {
     if (action === 'relayout_node_graphs') {
       const p = relayoutSchema.parse(args);
       const layout = require('../../vendor/drx-codec/node-layout.js');
-      const layoutOpts = { originX: p.originX, originY: p.originY, spacingX: p.spacingX };
+      const layoutOpts = { originX: p.originX, originY: p.originY, spacingX: p.spacingX, spacingY: p.spacingY, layout: p.layout };
       const dbPath = await resolveDbPath(p);
       const write = !p.dryRun;
       if (write) requireClosed(p);

package/resolve-advanced/vendor/drx-codec/node-layout.js

@@ -2,7 +2,8 @@
  * Node-graph LAYOUT rewriter — repositions nodes in a DRX/LmVersion grade Body
  * without touching any grade content.
  *
- * A grade Body is [0x81] + zstd(protobuf). Inside the protobuf, each F1 container
+ * A grade Body is [0x81] + zstd(protobuf), or [0x80] + protobuf STORED uncompressed
+ * (how Resolve serialises small/default graphs in .drp exports). Inside the protobuf, each F1 container
  * holds F7 node messages whose F4 (xPos) / F5 (yPos) varints are the node-editor
  * layout. Resolve's own "Cleanup Node Graph" rewrites ONLY those two fields
  * (verified by before/after Project.db diff, 2026-07): its clean layout is an
@@ -12,9 +13,22 @@
  * containing length prefixes) survives verbatim, so the rewrite is lossless for
  * OFX/uncalibrated params, keyframes, labels — everything.
  *
+ * TOPOLOGY (2026-09-14): positions come from the graph's own connections, not from
+ * the node list order. Each F1 container also carries F8 connection messages
+ * (F1 = from node id, F3 = to node id, F5/F6 = source/target port — 64 is the RGB
+ * path, 16 is a key link — F2/F4 = slot on multi-input nodes, F7 = creation order)
+ * and F9/F10 input/output markers whose F3.F4 name the chain's first and last node.
+ * Nodes are ranked by longest RGB path from the source (x), branches of a split are
+ * stacked into lanes (y) and a merge returns to its lowest input lane. A plain
+ * chain therefore lands on exactly the measured clean row — in CHAIN order, which
+ * the list order is not (Resolve lists nodes by id; a node inserted mid-chain has
+ * a high id). Key links never move a node. Lane spacing (spacingY, default 178 —
+ * Resolve's own vertical placement grid seen in every stacked export) is NOT yet
+ * measured against native Cleanup on a mixer graph; the x row is.
+ *
  * Consumed by the drx tool's `relayout` action (live single-shot path: grab →
- * relayout → ApplyGradeFromDRX) and project_db's `relayout_node_graphs`
- * (closed-project bulk patch of ListMgt::LmVersion rows).
+ * relayout → ApplyGradeFromDRX), drp's `relayout_node_graphs` (exported project
+ * sweep) and project_db's `relayout_node_graphs` (closed-project bulk patch).
  */
 
 'use strict';
@@ -65,6 +79,28 @@ async function getZstd() {
   return backend;
 }
 
+// ---- Body container: 0x81 = zstd-compressed, 0x80 = stored (uncompressed) ----
+
+const MAGIC_ZSTD = 0x81;
+const MAGIC_STORED = 0x80;
+
+/** Split a Body into its container kind and the raw protobuf. */
+async function unwrapBody(body) {
+  if (body[0] === MAGIC_ZSTD) {
+    const zstd = await getZstd();
+    return { magic: MAGIC_ZSTD, proto: zstd.decompress(body.subarray(1)) };
+  }
+  if (body[0] === MAGIC_STORED) return { magic: MAGIC_STORED, proto: Buffer.from(body.subarray(1)) };
+  throw new Error('not a grade Body (missing 0x81/0x80 magic)');
+}
+
+/** Re-wrap a protobuf in the SAME container kind it came from (lossless in kind). */
+async function wrapBody(magic, proto) {
+  if (magic === MAGIC_STORED) return Buffer.concat([Buffer.from([MAGIC_STORED]), proto]);
+  const zstd = await getZstd();
+  return Buffer.concat([Buffer.from([MAGIC_ZSTD]), zstd.compress(proto)]);
+}
+
 // ---- minimal protobuf walker (varint + length-delimited only, as the Body uses) ----
 
 function readVarint(buf, p) {
@@ -125,6 +161,160 @@ const F_NODE = 7; // node message inside the F1 container
 const F_X = 4;
 const F_Y = 5;
 
+// Connection message field numbers.
+const F_CONN = 8;
+const RGB_PORT = 64;
+const KEY_PORT = 16;
+
+/** Decode nodes (list order) + connections + chain endpoints from a decompressed Body. */
+function decodeTopology(proto) {
+  const nodes = [];
+  const edges = [];
+  let first = null;
+  let last = null;
+  for (const t of fields(proto)) {
+    if (t.f !== 1 || t.wt !== 2) continue;
+    for (const g of fields(t.val)) {
+      if (g.f === F_NODE && g.wt === 2) {
+        const n = { id: null, index: null, x: null, y: null };
+        for (const h of fields(g.val)) {
+          if (h.wt !== 0) continue;
+          if (h.f === 1) n.id = Number(h.val);
+          else if (h.f === 2) n.index = Number(h.val);
+          else if (h.f === F_X) n.x = Number(h.val);
+          else if (h.f === F_Y) n.y = Number(h.val);
+        }
+        nodes.push(n);
+      } else if (g.f === F_CONN && g.wt === 2) {
+        const e = { from: null, to: null, fromPort: RGB_PORT, toPort: RGB_PORT, fromSlot: 0, toSlot: 0, order: 0 };
+        for (const h of fields(g.val)) {
+          if (h.wt !== 0) continue;
+          const v = Number(h.val);
+          if (h.f === 1) e.from = v;
+          else if (h.f === 2) e.fromSlot = v;
+          else if (h.f === 3) e.to = v;
+          else if (h.f === 4) e.toSlot = v;
+          else if (h.f === 5) e.fromPort = v;
+          else if (h.f === 6) e.toPort = v;
+          else if (h.f === 7) e.order = v;
+        }
+        if (e.from !== null && e.to !== null) edges.push(e);
+      } else if ((g.f === 9 || g.f === 10) && g.wt === 2) {
+        for (const h of fields(g.val)) {
+          if (h.f !== 3 || h.wt !== 2) continue;
+          for (const k of fields(h.val)) if (k.f === 4 && k.wt === 0) (g.f === 9 ? (first = Number(k.val)) : (last = Number(k.val)));
+        }
+      }
+    }
+  }
+  return { nodes, edges, first, last };
+}
+
+/**
+ * Plan positions from topology. Returns positions in NODE LIST order (what
+ * relayoutBody writes) plus a meta block. Falls back to the plain row — in
+ * chain order when the graph has a chain, else list order — on anything it
+ * cannot rank (cycles, dangling ids).
+ *
+ * Lanes: walking ranks left→right, a node with k RGB outputs fans its children
+ * into lanes lane, lane+1, … (ordered by the target's input slot, then creation
+ * order); a node with several RGB inputs (a mixer) sits on the lowest of its
+ * input lanes; two nodes claiming one (rank, lane) cell push the later one down.
+ */
+function planPositions(topo, { originX = 290, originY = 428, spacingX = 495, spacingY = 178, layout = 'topology' } = {}) {
+  const n = topo.nodes.length;
+  const ids = topo.nodes.map((v) => v.id);
+  const byId = new Map(ids.map((id, i) => [id, i]));
+  const rowPositions = (orderIdx) => {
+    const pos = new Array(n);
+    orderIdx.forEach((listIdx, k) => (pos[listIdx] = [originX + k * spacingX, originY]));
+    return pos;
+  };
+  const listOrder = topo.nodes.map((_, i) => i);
+  if (n === 0) return { positions: [], meta: { kind: 'empty', ranks: 0, lanes: 0 } };
+  if (layout === 'row' || n === 1) return { positions: rowPositions(listOrder), meta: { kind: 'row', ranks: n, lanes: 1 } };
+
+  const flow = topo.edges.filter((e) => !(e.fromPort === KEY_PORT && e.toPort === KEY_PORT) && byId.has(e.from) && byId.has(e.to) && e.from !== e.to);
+  const keyLinks = topo.edges.length - flow.length;
+  if (!flow.length) {
+    // No wiring at all: order by Resolve's own index field, then list order.
+    const order = [...listOrder].sort((a, b) => (topo.nodes[a].index ?? 1e9) - (topo.nodes[b].index ?? 1e9) || a - b);
+    return { positions: rowPositions(order), meta: { kind: 'row', ranks: n, lanes: 1, keyLinks } };
+  }
+
+  const out = new Map(ids.map((id) => [id, []]));
+  const indeg = new Map(ids.map((id) => [id, 0]));
+  for (const e of flow) {
+    out.get(e.from).push(e);
+    indeg.set(e.to, indeg.get(e.to) + 1);
+  }
+  // Branch order at a fan-out: the slot this edge lands in, else the slot the
+  // branch eventually feeds on its merge (Resolve numbers mixer inputs top-down),
+  // else creation order.
+  const mergeSlot = (id) => Math.min(Infinity, ...(out.get(id) || []).map((e) => e.toSlot || Infinity));
+  for (const list of out.values()) list.sort((a, b) => (a.toSlot || 0) - (b.toSlot || 0) || mergeSlot(a.to) - mergeSlot(b.to) || a.order - b.order);
+
+  // Longest-path ranks (Kahn); a cycle leaves nodes unranked → fall back.
+  const rank = new Map();
+  const queue = ids.filter((id) => indeg.get(id) === 0);
+  const remaining = new Map(indeg);
+  for (const id of queue) rank.set(id, 0);
+  while (queue.length) {
+    const id = queue.shift();
+    for (const e of out.get(id)) {
+      rank.set(e.to, Math.max(rank.get(e.to) ?? 0, rank.get(id) + 1));
+      remaining.set(e.to, remaining.get(e.to) - 1);
+      if (remaining.get(e.to) === 0) queue.push(e.to);
+    }
+  }
+  if (rank.size !== n) {
+    const order = [...listOrder].sort((a, b) => (topo.nodes[a].index ?? 1e9) - (topo.nodes[b].index ?? 1e9) || a - b);
+    return { positions: rowPositions(order), meta: { kind: 'row', ranks: n, lanes: 1, keyLinks, fallback: 'unrankable graph' } };
+  }
+
+  // Lanes, walking ranks left → right (parents are always placed before children):
+  //   no input        → lane 0
+  //   one input p     → lane(p) + k, k = this edge's position among p's outputs
+  //   several inputs  → the lowest input lane (a merge comes back to the main line)
+  // A (rank, lane) cell taken by an earlier node pushes the later one down.
+  const lane = new Map();
+  const taken = new Set();
+  const claim = (id, want) => {
+    let l = want;
+    while (taken.has(`${rank.get(id)}:${l}`)) l += 1;
+    lane.set(id, l);
+    taken.add(`${rank.get(id)}:${l}`);
+  };
+  const idx = (id) => topo.nodes[byId.get(id)].index ?? 0;
+  const byRank = [...ids].sort((a, b) => rank.get(a) - rank.get(b) || (a === topo.first ? -1 : b === topo.first ? 1 : 0) || idx(a) - idx(b));
+  const inputsOf = new Map(ids.map((id) => [id, []]));
+  for (const e of flow) inputsOf.get(e.to).push(e);
+  for (const id of byRank) {
+    const ins = inputsOf.get(id);
+    let want = 0;
+    if (ins.length === 1) {
+      const p = ins[0].from;
+      const k = out.get(p).findIndex((e) => e.to === id);
+      want = (lane.get(p) ?? 0) + Math.max(0, k);
+    } else if (ins.length > 1) {
+      want = Math.min(...ins.map((e) => lane.get(e.from) ?? 0));
+    }
+    claim(id, want);
+  }
+
+  const positions = new Array(n);
+  let maxRank = 0;
+  let maxLane = 0;
+  for (const id of ids) {
+    const r = rank.get(id);
+    const l = lane.get(id);
+    maxRank = Math.max(maxRank, r);
+    maxLane = Math.max(maxLane, l);
+    positions[byId.get(id)] = [originX + r * spacingX, originY + l * spacingY];
+  }
+  return { positions, meta: { kind: maxLane > 0 ? 'dag' : 'chain', ranks: maxRank + 1, lanes: maxLane + 1, keyLinks } };
+}
+
 /**
  * Resolve-cleanup-style positions for n nodes: one evenly spaced row.
  * Defaults are the exact values Resolve's own Cleanup Node Graph produced
@@ -169,9 +359,7 @@ function rewriteNodeMessage(nodeBuf, x, y) {
  */
 async function relayoutBody(body, options = {}) {
   if (!Buffer.isBuffer(body)) body = Buffer.from(body);
-  if (body[0] !== 0x81) throw new Error('not a grade Body (missing 0x81 magic)');
-  const zstd = await getZstd();
-  const proto = zstd.decompress(body.subarray(1));
+  const { magic, proto } = await unwrapBody(body);
 
   // First pass: count nodes so the default layout can be sized.
   const top = fields(proto);
@@ -181,7 +369,13 @@ async function relayoutBody(body, options = {}) {
   }
   if (nodeCount === 0) throw new Error('relayout refused: Body decodes to 0 nodes');
 
-  const positions = options.positions || cleanRowPositions(nodeCount, options);
+  let meta = { kind: 'explicit', ranks: nodeCount, lanes: 1 };
+  let positions = options.positions;
+  if (!positions) {
+    const planned = planPositions(decodeTopology(proto), options);
+    positions = planned.positions;
+    meta = planned.meta;
+  }
   if (positions.length < nodeCount) {
     throw new Error(`positions has ${positions.length} entries but the grade has ${nodeCount} nodes`);
   }
@@ -213,8 +407,8 @@ async function relayoutBody(body, options = {}) {
     }
   }
 
-  const out = Buffer.concat([Buffer.from([0x81]), zstd.compress(Buffer.concat(rebuilt))]);
-  return { body: out, nodeCount, positions: positions.slice(0, nodeCount) };
+  const out = await wrapBody(magic, Buffer.concat(rebuilt));
+  return { body: out, nodeCount, positions: positions.slice(0, nodeCount), meta };
 }
 
 /** Hex-string convenience wrapper (DRX <Body> / DB dumps are handled as hex upstream). */
@@ -223,12 +417,19 @@ async function relayoutBodyHex(bodyHex, options = {}) {
   return { ...r, bodyHex: r.body.toString('hex') };
 }
 
+/** Decode nodes + connections + planned positions without rewriting anything. */
+async function readTopology(body, options = {}) {
+  if (!Buffer.isBuffer(body)) body = Buffer.from(body);
+  const { proto } = await unwrapBody(body);
+  const topo = decodeTopology(proto);
+  const planned = planPositions(topo, options);
+  return { ...topo, planned: planned.positions, meta: planned.meta };
+}
+
 /** Decode just the node positions from a Body (for dry runs / verification). */
 async function readNodePositions(body) {
   if (!Buffer.isBuffer(body)) body = Buffer.from(body);
-  if (body[0] !== 0x81) throw new Error('not a grade Body (missing 0x81 magic)');
-  const zstd = await getZstd();
-  const proto = zstd.decompress(body.subarray(1));
+  const { proto } = await unwrapBody(body);
   const positions = [];
   for (const t of fields(proto)) {
     if (t.f !== 1 || t.wt !== 2) continue;
@@ -246,4 +447,4 @@ async function readNodePositions(body) {
   return positions;
 }
 
-module.exports = { relayoutBody, relayoutBodyHex, readNodePositions, cleanRowPositions };
+module.exports = { relayoutBody, relayoutBodyHex, readNodePositions, readTopology, decodeTopology, planPositions, cleanRowPositions, unwrapBody, wrapBody, encodeVarint };

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.5.2"
+VERSION = "4.6.0"
 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/granular/project.py

@@ -769,23 +769,45 @@ def get_project_info_endpoint() -> Dict[str, Any]:
     return get_project_info(current_project)
 
 
-@mcp.tool()
-def archive_project(project_name: str, archive_path: str, archive_src_media: bool = True, archive_render_cache: bool = True, archive_proxy_media: bool = False) -> Dict[str, Any]:
-    """Archive a project to a file with optional media.
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+@granular_destructive_op()
+def archive_project(project_name: str, archive_path: str, archive_src_media: bool = False,
+                    archive_render_cache: bool = False, archive_proxy_media: bool = False,
+                    acknowledge_trap: bool = False) -> Dict[str, Any]:
+    """Archive a project to a file. On Resolve 21.1.0.14 this never produces an archive.
+
+    Measured: with source media and proxies off, ArchiveProject returns False and
+    writes nothing, open or closed. With either on it crashes Resolve and loses
+    unsaved work in the open project. So every flag defaults off, and the two
+    crashing flags are refused unless acknowledge_trap is true. The result
+    reports what the native call returned. See src/utils/archive_guard.py.
 
     Args:
         project_name: Name of the project to archive.
-        archive_path: Absolute path for the archive file (.dra).
-        archive_src_media: Include source media in archive. Default: True.
-        archive_render_cache: Include render cache. Default: True.
-        archive_proxy_media: Include proxy media. Default: False.
+        archive_path: Absolute path for the archive (.dra).
+        archive_src_media: Include source media. Crashes Resolve 21.1.0.14. Default: False.
+        archive_render_cache: Include render cache. Default: False.
+        archive_proxy_media: Include proxy media. Crashes Resolve 21.1.0.14. Default: False.
+        acknowledge_trap: Must be true to send either crashing flag.
     """
+    from src.utils import archive_guard
+    flags, flag_err = archive_guard.read_flags({
+        "src_media": archive_src_media, "render_cache": archive_render_cache,
+        "proxy_media": archive_proxy_media})
+    if flag_err:
+        return {"error": flag_err}
+    if not acknowledge_trap:
+        refused = archive_guard.crash_refusal("granular", "archive_project", flags)
+        if refused:
+            return refused
     resolve = get_resolve()
     if resolve is None:
         return {"error": "Not connected to DaVinci Resolve"}
     pm = resolve.GetProjectManager()
-    result = pm.ArchiveProject(project_name, archive_path, archive_src_media, archive_render_cache, archive_proxy_media)
-    return {"success": bool(result), "project_name": project_name, "archive_path": archive_path}
+    native = pm.ArchiveProject(project_name, archive_path, flags["src_media"],
+                               flags["render_cache"], flags["proxy_media"])
+    return archive_guard.outcome(native, flags, project_name=project_name,
+                                 archive_path=archive_path)
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.5.2"
+VERSION = "4.6.0"
 
 import base64
 import os
@@ -52,6 +52,7 @@ from src.utils.resolve211_edits import validate_edit_options, validate_transitio
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
+from src.utils import archive_guard
 from src.utils import typed_api_search
 from src.utils import lut_files
 from src.utils import resolve_writes as _resolve_writes
@@ -18544,11 +18545,18 @@ def _safe_project_archive(pm, p: Dict[str, Any]) -> Dict[str, Any]:
     path_err = _project_path_guard(path, require_temp_path=p.get("require_temp_path", True))
     if path_err:
         return path_err
-    src_media = bool(p.get("src_media", False))
-    render_cache = bool(p.get("render_cache", False))
-    proxy_media = bool(p.get("proxy_media", False))
+    flags, flag_err = archive_guard.read_flags(p)
+    if flag_err:
+        return _err(flag_err, code="INVALID_ARCHIVE_FLAG", category="invalid_input")
+    src_media, render_cache, proxy_media = (flags["src_media"], flags["render_cache"],
+                                            flags["proxy_media"])
     if (src_media or render_cache or proxy_media) and not p.get("allow_media_archive", False):
         return _err("Archive media/cache/proxy flags must stay false unless allow_media_archive=True")
+    # allow_media_archive guards size; this guards the crash. Both are required.
+    if not p.get("acknowledge_trap"):
+        refused = archive_guard.crash_refusal("project_manager", "safe_project_archive", flags)
+        if refused:
+            return refused
     os.makedirs(_project_path_parent(path), exist_ok=True)
     if p.get("dry_run"):
         return _ok(
@@ -18559,7 +18567,8 @@ def _safe_project_archive(pm, p: Dict[str, Any]) -> Dict[str, Any]:
             render_cache=render_cache,
             proxy_media=proxy_media,
         )
-    return {"success": bool(pm.ArchiveProject(name, path, src_media, render_cache, proxy_media))}
+    native = pm.ArchiveProject(name, path, src_media, render_cache, proxy_media)
+    return archive_guard.outcome(native, flags, name=name, path=path)
 
 
 def _safe_project_restore(pm, p: Dict[str, Any]) -> Dict[str, Any]:
@@ -19248,8 +19257,18 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         })
         if err:
             return _err(err)
-        return {"success": bool(pm.ArchiveProject(p["name"], p["path"],
-            p.get("src_media", True), p.get("render_cache", True), p.get("proxy_media", False)))}
+        # Every flag defaults OFF. The native defaults turn source media on, and on
+        # 21.1.0.14 that crashes Resolve (see utils/archive_guard.py).
+        flags, flag_err = archive_guard.read_flags(p)
+        if flag_err:
+            return _err(flag_err, code="INVALID_ARCHIVE_FLAG", category="invalid_input")
+        if not p.get("acknowledge_trap"):
+            refused = archive_guard.crash_refusal("project_manager", "archive", flags)
+            if refused:
+                return refused
+        native = pm.ArchiveProject(p["name"], p["path"], flags["src_media"],
+                                   flags["render_cache"], flags["proxy_media"])
+        return archive_guard.outcome(native, flags, name=p["name"], path=p["path"])
     elif action == "restore":
         if not p.get("path"):
             return _err("restore requires path")

package/src/utils/api_truth.py

@@ -3373,6 +3373,47 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "second contributor. The current-timeline pointer moved to "
                        "the duplicate, and SetCurrentTimeline put it back.",
     },
+    {
+        "symbol": "ProjectManager.ArchiveProject",
+        "object": "ProjectManager",
+        "signature": "(projectName, filePath, isArchiveSrcMedia=True, isArchiveRenderCache=True, isArchiveProxyMedia=False) -> bool",
+        "reality": "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.",
+        "recommended": "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"],
+        "submit": "bug",
+        "verified_on": "DaVinci Resolve Studio 21.1.0.14",
+        "measured": "2026-09-14 on a disposable local project with one synthetic "
+                    "clip, one isolated call per case: all flags off (open project) "
+                    "False; all off (closed) False; render cache only False; source "
+                    "media None + crash + empty dir; proxy media None + crash + empty "
+                    "dir; unrelated file at target with flags off False, file "
+                    "byte-identical; populated directory at target with flags off "
+                    "False, untouched; source media onto an existing file None + "
+                    "crash, file byte-identical. 19.1.3.7 (mode matrix 2026-08-02, "
+                    "GUI and headless): False for .dra and folder paths, flags off.",
+        "mitigation": ["project_manager.archive", "project_manager.safe_project_archive",
+                       "archive_project"],
+    },
 
 ]
 
@@ -3432,6 +3473,8 @@ ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
     ("timeline_item_color", "export_lut"): ["TimelineItem.ExportLUT"],
     ("timeline_item_color", "safe_export_lut"): ["TimelineItem.ExportLUT"],
     ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
+    ("project_manager", "archive"): ["ProjectManager.ArchiveProject"],
+    ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
 }
 
 

package/src/utils/archive_guard.py

@@ -0,0 +1,97 @@
+"""`ProjectManager.ArchiveProject` on Resolve 21.1: a silent no-op or a crash.
+
+Measured on Studio 21.1.0.14 against a disposable local project holding one
+synthetic clip, archived by name. Every row is one isolated call.
+
+=================================  ========  ====================================
+include flags                      returns   effect
+=================================  ========  ====================================
+all off (project open or closed)   ``False`` nothing written, instantly
+render cache only                  ``False`` nothing written, instantly
+source media                       ``None``  empty directory at the target, then
+                                             Resolve crashes (SIGSEGV)
+proxy media                        ``None``  same crash
+=================================  ========  ====================================
+
+Four crashes, one of them inside a Blackmagic Cloud library, share identical top
+stack frames, in Fusion script-symbol teardown on the UI thread. A crashing call
+comes back through the bridge as ``None`` rather than a bool, and every handle
+after it is dead. A file already at the target survived every case byte for
+byte, including the crash, so the destination is never the casualty. Unsaved
+work in whatever project is open is.
+
+On 19.1.3.7 this repo's mode matrix already 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.
+
+So the native defaults, ``isArchiveSrcMedia=True`` and ``isArchiveRenderCache=
+True``, crash Resolve 21.1.0.14, and so did both wrappers here, which inherited
+them. These helpers default every flag to off, refuse the two crashing flags
+unless the caller says ``acknowledge_trap``, and report what the native call
+actually returned rather than a bare bool.
+"""
+
+from typing import Any, Dict, Optional, Tuple
+
+#: Flags measured to crash Resolve 21.1.0.14 when set.
+CRASH_FLAGS = ("src_media", "proxy_media")
+FLAG_NAMES = ("src_media", "render_cache", "proxy_media")
+
+_MEASURED = ("Measured on DaVinci Resolve Studio 21.1.0.14; the full table is in "
+             "src/utils/archive_guard.py and the ProjectManager.ArchiveProject "
+             "api_truth entry.")
+
+
+def read_flags(params: Dict[str, Any]) -> Tuple[Optional[Dict[str, bool]], Optional[str]]:
+    """Every include flag, defaulting to off. Only real booleans are accepted.
+
+    A JSON caller sending ``"false"`` would have turned a flag ON through a bare
+    ``bool()``, and two of these flags crash Resolve.
+    """
+    flags: Dict[str, bool] = {}
+    for name in FLAG_NAMES:
+        value = params.get(name, False)
+        if not isinstance(value, bool):
+            return None, (f"{name} must be true or false, got {value!r}. Two of the "
+                          "archive flags crash Resolve 21.1, so a non-boolean is "
+                          "refused rather than guessed at.")
+        flags[name] = value
+    return flags, None
+
+
+def crash_refusal(tool: str, action: str, flags: Dict[str, bool]) -> Optional[Dict[str, Any]]:
+    """Refuse the crashing flags unless the caller explicitly accepts the risk."""
+    crashing = [f for f in CRASH_FLAGS if flags.get(f)]
+    if not crashing:
+        return None
+    return {
+        "success": False,
+        "error": (f"'{tool}.{action}' is refused: with {' and '.join(crashing)} on, "
+                  "ProjectManager.ArchiveProject crashes Resolve 21.1.0.14 before "
+                  "writing anything but an empty directory, and unsaved work in the "
+                  "open project is lost. Re-send with acknowledge_trap=true only on a "
+                  "build you have verified."),
+        "known_limitation": [_MEASURED],
+        "crash_flags": crashing,
+        "retry_with": {"acknowledge_trap": True},
+    }
+
+
+def outcome(native: Any, flags: Dict[str, bool], **extra: Any) -> Dict[str, Any]:
+    """Report the native return as an observation, never as an assumption."""
+    out: Dict[str, Any] = {"flags": dict(flags), "native_returned": native}
+    out.update(extra)
+    if native is True:
+        out["success"] = True
+    elif native is None:
+        out["success"] = False
+        out["error"] = ("ArchiveProject returned no result. On 21.1.0.14 that is what a "
+                        "crashed Resolve looks like through the bridge; check whether "
+                        "Resolve is still running.")
+    else:
+        out["success"] = False
+        out["error"] = ("Resolve returned False and wrote nothing. With source media and "
+                        "proxies off this is the measured result on 21.1.0.14 whether the "
+                        "project is open or closed; no scriptable call has produced an "
+                        "archive on 21.1.0.14 or 19.1.3.7.")
+    return out

package/src/utils/destructive_hook.py

@@ -104,7 +104,8 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "delete_by_color",
         "delete_by_custom_data",
     }),
-    "project_manager": frozenset({"delete", "safe_project_delete"}),
+    "project_manager": frozenset({"archive", "delete", "safe_project_archive",
+                                  "safe_project_delete"}),
     "project_settings": frozenset({"delete_color_group"}),
     "render": frozenset({"delete_all_jobs", "delete_job", "delete_preset"}),
     "render_presets": frozenset({"delete_burnin"}),
@@ -369,6 +370,7 @@ NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("script_plugin", "safe_install_extension"),
     ("script_plugin", "safe_remove_extension"),
     ("project_manager", "safe_project_delete"),
+    ("project_manager", "safe_project_archive"),
     ("lut", "attenuate"),
     ("lut", "install"),
     ("lut", "remove"),