davinci-resolve-mcp 2.164.0 → 2.165.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.165.0 — E107: frame QC reads Resolve's own XML and samples clear of transitions
+
+The lineage store's `ingest_xml` was measured against a verbatim
+`EXPORT_FCP_7_XML` of a fade-in → clip → centered dissolve → clip → fade-out
+timeline (rendered and luma-verified: 18→123 over the fade-in, a blend over
+96–119, 230→21 over the fade-out). Every transition-adjacent cut landed at
+record `-1` with no oracle frame — the reference sampled at frame 0 read
+black and the conform side could not be sampled at all, so each read as a
+false yellow turnover. Two laws of Resolve's writer explain it.
+
+### Fixed
+
+- **`-1` clip edges resolve to junctions in the lineage ingest** (the E105
+  law the editorial parser already knew), and with a record-order cursor:
+  under three centered transitions two equal-length clips both carry
+  `-1/-1` edges, and the first junction pair that fits placed BOTH clips at
+  the same position — in the editorial parser too. Both parsers now walk
+  clips with a cursor; the verbatim export is a permanent fixture.
+- **Resolve writes no `pproTicksIn`.** The oracle insisted on Premiere ticks
+  and derived no source frame for any cut of a Resolve export. When ticks
+  are absent, `<in>` (record-aligned by the `-1` resolution) is the oracle
+  frame; the ingest reports `ticksAbsent`, `resolvedEdges`, `unresolvedEdges`.
+- **Frame QC samples clear of transition windows.** Each cut records the
+  windows its edges sit in (`cuts.transition`, plus `cuts.speed`; existing
+  sidecars migrate in place) and `qc` compares the first frame past the
+  incoming window and before the outgoing one, advancing the source frame
+  at the cut's speed (reverse walks backward). Measured on the render:
+  structure 0.982 at the dissolve junction → 0.999 clear of it; the result
+  carries `sample_note` saying where it looked, and a cut swallowed whole by
+  its windows samples its midpoint and says so.
+
+### Measured (filed in api-limitations)
+
+- `EXPORT_FCP_7_XML` writes no `pproTicksIn`/`pproTicksOut`, `-1` on every
+  transition-adjacent edge (junction), `center` alignment for every
+  centered-authored dissolve and fade, and Solid Color generatoritems for
+  black legs. A flat/untextured frame (a white card) is `UNREADABLE` to the
+  brightness-robust classifier — an honest review, not a false verdict.
+
 ## What's New in v2.164.0 — E106: the changelist sees junctions
 
 `editorial.turnover_changelist` diffed clips and was blind to everything

package/README.md

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

package/README.zh-CN.md

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

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -135,7 +135,9 @@ files and the project DB.
   source). Also: reverse/retimed subclip DB repair (reversed `source_start` =
   `masterFrames − 1 − endoffset`, live-validated), sequence lineage store + diff +
   rollback (hashed snapshots), and per-cut frame QC (oracle-frame vs
-  reference-render, scale-corrected, red/yellow/cyan verdicts).
+  reference-render, scale-corrected, red/yellow/cyan verdicts; each cut is
+  compared clear of its transition windows, and Resolve's own FCP7 export
+  ingests with its `-1` edges resolved and its missing ticks tolerated).
 - **`color_trace`** — cross-project clip matching → a trace plan for carrying
   grades across a re-conform (pairs with the color kernel's `drx grade_transfer`).
 - **`offline_ref`** — offline-reference clips have **no scripting API** but live

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 36 missing capabilities, 50 bugs / unreliable behaviors.
+**Totals:** 37 missing capabilities, 50 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -309,6 +309,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** For round-trip QC prefer EXPORT_OTIO (carries audio, retimes as LinearTimeWarp/FreezeFrame, exact spans). When an EDL is the required deliverable, expect no audio (editorial.verify_roundtrip reports audioNotInExport) and resolve AX reels through the clip-name comments (parseEDL does). Use EXPORT_EDL — there is no EXPORT_CMX_3600 constant, and an unknown name reaches Export as a string that returns a bare False (timeline.export_timeline_checked now refuses it loudly).
 - **Tags:** timeline, export, edl, audio, silent-failure
 
+### Timeline.Export EXPORT_FCP_7_XML (no pproTicksIn, -1 edges under transitions)
+
+- **Object:** `Timeline`
+- **Signature:** `(filePath, EXPORT_FCP_7_XML, EXPORT_NONE) -> bool`
+- **Behavior:** Resolve's FCP7 XML writer (measured on Studio 19.1.3.7, E107, verbatim export kept as a fixture) emits NO pproTicksIn/pproTicksOut on any clipitem — the Premiere tick fields a Premiere-shaped oracle treats as the authoritative source position are simply absent, so a reader that requires them derives no source frame for ANY cut of a Resolve export. Every clipitem edge that sits under a transitionitem is written as -1 and means the transition's junction (span center for alignment center; the writer emitted `center` for every dissolve and fade authored centered), `out - in` is the record duration, and a -1 START edge's <in> is the source at the overlap start. With three centered transitions two equal-length clips both carry -1/-1 edges, so a reader must pair junctions in record order — the first pair that fits places both clips at the same position. Black legs are Solid Color generatoritems whose -1 edge resolves the same way.
+- **Workaround / current handling:** Read <in> as the literal source frame (Resolve reads and writes it that way), record-align it by the junction-minus-span-start offset on a -1 start, and walk -1/-1 clips with a record-order cursor. conform.snapshot ingest_xml and editorial.parse_interchange both do; the frame QC then samples each cut CLEAR of its transition windows (inside one the reference is a blend, or black for a fade).
+- **Tags:** timeline, export, xml, fcp7, transitions, silent-failure
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return

package/install.py

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

package/resolve-advanced/README.md

@@ -80,7 +80,8 @@ Each dispatches on an `action`. Highlights:
   `export_cdl`, `merge`, plus the **grading/QC catalog** below.
 - **`drp` / `drt`** — project / timeline file authoring + editing + grade injection + structural diff.
 - **`conform`** — offline conform/relink QC engine (frame-oracle math, not filename matching),
-  reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC.
+  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).
 - **`color_trace`** — cross-project clip matching → a trace plan for carrying grades across a re-conform.
 - **`project_read` / `project_db`** — read/patch the Resolve project DB (SQLite or Postgres).
   Includes `list_subtitle_styles` / `set_subtitle_style` — caption font family/size/weight/italic

package/resolve-advanced/server/editorial.mjs

@@ -297,7 +297,13 @@ export function parseXMEMLEvents(xml, opts = {}) {
   let idx = 1;
   const seqRate = opts.fps || 24;
   let currentJunctions = [];
-  const walk = (node, track) => {
+  // Record-order cursor for -1/-1 edge resolution (E107): a clip whose both
+  // edges are -1 pairs junctions at or after the previous CLIP's end —
+  // generator legs (walked first) never advance it. Without this, two
+  // equal-length clips under three centered transitions both resolved to
+  // the first junction pair (measured against Resolve's own writer).
+  let clipCursor = 0;
+  const walk = (node, track, advanceCursor = true) => {
     if (!node) return;
     const items = Array.isArray(node) ? node : [node];
     for (const it of items) {
@@ -340,9 +346,11 @@ export function parseXMEMLEvents(xml, opts = {}) {
       else if (end === -1 && start !== -1 && dur != null) end = start + dur;
       else if (start === -1 && end === -1 && dur != null && junctions.length) {
         const js = junctions.map((j) => j.frame).sort((a, b) => a - b);
-        const pair = js.find((a) => js.includes(a + dur));
+        const floor = advanceCursor ? clipCursor : 0;
+        const pair = js.find((a) => a >= floor && js.includes(a + dur));
         if (pair != null) { start = pair; end = pair + dur; }
       }
+      if (advanceCursor && Number.isFinite(end) && end >= 0) clipCursor = Math.max(clipCursor, end);
       // A -1 START edge's `in` is the source at the OVERLAP start (the
       // clip's material begins under the transition), while the resolved
       // start is the junction — so `in` advances by the same offset to stay
@@ -383,8 +391,9 @@ export function parseXMEMLEvents(xml, opts = {}) {
       const gens = t.generatoritem ? (Array.isArray(t.generatoritem) ? t.generatoritem : [t.generatoritem]) : [];
       for (const g of gens) {
         if (!/solid color|black/i.test(String(g.name || ''))) continue;
-        walk([{ ...g, name: 'BL', filter: undefined, marker: undefined }], label);
+        walk([{ ...g, name: 'BL', filter: undefined, marker: undefined }], label, false);
       }
+      clipCursor = 0;
       if (t.clipitem) walk(t.clipitem, label);
       currentJunctions = [];
       // <transitionitem> siblings: attach each to the INCOMING clip event —

package/resolve-advanced/server/lineage-db.mjs

@@ -34,7 +34,7 @@ CREATE TABLE IF NOT EXISTS cuts (snapshot_id TEXT, cut_index INTEGER, record_sta
  source_basename TEXT, source_path TEXT, xml_in INTEGER, xml_out INTEGER,
  ppro_ticks_in INTEGER, oracle_source_frame INTEGER, is_subclip INTEGER,
  subclip_startoffset INTEGER, subclip_endoffset INTEGER, reverse INTEGER,
- scale_corrected REAL, pan_h REAL, pan_v REAL, rotation REAL, transition TEXT,
+ scale_corrected REAL, pan_h REAL, pan_v REAL, rotation REAL, transition TEXT, speed REAL,
  cut_hash TEXT, PRIMARY KEY (snapshot_id, cut_index));
 CREATE TABLE IF NOT EXISTS qc_verdicts (snapshot_id TEXT, cut_index INTEGER, reference_ref TEXT, reference_frame INTEGER,
  verdict TEXT, category TEXT, structure REAL, psnr REAL, dx INTEGER, dy INTEGER,
@@ -48,6 +48,10 @@ export function openStore(dbPath) {
   const db = new Database(dbPath);
   db.pragma('journal_mode = WAL');
   db.exec(SCHEMA);
+  // Sidecars created before E107 lack cuts.speed — CREATE IF NOT EXISTS
+  // cannot add a column, so migrate in place (idempotent).
+  const cols = db.prepare('PRAGMA table_info(cuts)').all().map((c) => c.name);
+  if (!cols.includes('speed')) db.exec('ALTER TABLE cuts ADD COLUMN speed REAL');
   return db;
 }
 
@@ -79,6 +83,9 @@ function cutHash(cut) {
 
 function buildCuts(xml, mediaFrames) {
   const g = parse.parseGeometry(xml);
+  const unresolvedEdges = [];
+  let resolvedEdges = 0;
+  let ticksAbsent = 0;
   const seqW = g.sequence.width || null;
   const seqH = g.sequence.height || null;
   const fps = g.sequence.fps || 24;
@@ -92,6 +99,15 @@ function buildCuts(xml, mediaFrames) {
     } catch {
       /* reverse w/o frame count, etc. */
     }
+    // Resolve's FCP7 writer emits NO pproTicksIn (measured, E107) and the
+    // oracle insists on ticks, so every cut of a Resolve export lost its
+    // source frame — the conform side could never be sampled. Resolve reads
+    // and writes <in> as the literal source frame (api-truth), and the -1
+    // resolution above has already record-aligned it, so <in> IS the frame.
+    if (oracleFrame == null && c.pproTicksIn == null && c.xml_in != null && !c.reverse) {
+      oracleFrame = (c.is_subclip ? c.subclip_startoffset || 0 : 0) + c.xml_in;
+      ticksAbsent += 1;
+    }
     try {
       scaleCorrected = resolveTarget.deriveScaleCorrected(c, ctx);
     } catch {
@@ -115,12 +131,20 @@ function buildCuts(xml, mediaFrames) {
       pan_h: c.center ? c.center.h : null,
       pan_v: c.center ? c.center.v : null,
       rotation: c.rotation ?? null,
-      transition: null,
+      // The transition windows this cut's edges sit in (E107): frame-QC
+      // samples clear of them — inside a window the reference is a blend, or
+      // black for a fade, and the first frame of the cut proves nothing.
+      transition: c.transition_in || c.transition_out
+        ? JSON.stringify({ in: c.transition_in || null, out: c.transition_out || null })
+        : null,
+      speed: c.speed ?? null,
     };
+    if (c.edges_resolved) resolvedEdges += 1;
+    if (c.edges_unresolved) unresolvedEdges.push({ cut_index: i, source_basename: cut.source_basename });
     cut.cut_hash = cutHash(cut);
     return cut;
   });
-  return { cuts, seqW, seqH, fps, transitions: g.transitions };
+  return { cuts, seqW, seqH, fps, transitions: g.transitions, unresolvedEdges, resolvedEdges, ticksAbsent };
 }
 
 // Write a built cut list as a snapshot (dedup on (reel, content_hash)). Shared by
@@ -136,8 +160,8 @@ function writeSnapshot(dbPath, cuts, meta) {
  (snapshot_id, reel, kind, source_ref, label, parent_id, content_hash, seq_w, seq_h, fps, cut_count, created_at, provenance)
  VALUES (@snapshot_id,@reel,@kind,@source_ref,@label,@parent_id,@content_hash,@seq_w,@seq_h,@fps,@cut_count,@created_at,@provenance)`);
     const insertCut = db.prepare(`INSERT INTO cuts
- (snapshot_id, cut_index, record_start, record_end, source_basename, source_path, xml_in, xml_out, ppro_ticks_in, oracle_source_frame, is_subclip, subclip_startoffset, subclip_endoffset, reverse, scale_corrected, pan_h, pan_v, rotation, transition, cut_hash)
- VALUES (@snapshot_id,@cut_index,@record_start,@record_end,@source_basename,@source_path,@xml_in,@xml_out,@ppro_ticks_in,@oracle_source_frame,@is_subclip,@subclip_startoffset,@subclip_endoffset,@reverse,@scale_corrected,@pan_h,@pan_v,@rotation,@transition,@cut_hash)`);
+ (snapshot_id, cut_index, record_start, record_end, source_basename, source_path, xml_in, xml_out, ppro_ticks_in, oracle_source_frame, is_subclip, subclip_startoffset, subclip_endoffset, reverse, scale_corrected, pan_h, pan_v, rotation, transition, speed, cut_hash)
+ VALUES (@snapshot_id,@cut_index,@record_start,@record_end,@source_basename,@source_path,@xml_in,@xml_out,@ppro_ticks_in,@oracle_source_frame,@is_subclip,@subclip_startoffset,@subclip_endoffset,@reverse,@scale_corrected,@pan_h,@pan_v,@rotation,@transition,@speed,@cut_hash)`);
     db.transaction(() => {
       insertSnap.run({
         snapshot_id: snapshotId,
@@ -170,8 +194,11 @@ function writeSnapshot(dbPath, cuts, meta) {
  */
 export function ingestXml(dbPath, xmlPath, opts = {}) {
   const xml = fs.readFileSync(xmlPath, 'utf8');
-  const { cuts, seqW, seqH, fps } = buildCuts(xml, opts.mediaFrames || {});
-  return writeSnapshot(dbPath, cuts, {
+  const { cuts, seqW, seqH, fps, unresolvedEdges, resolvedEdges, ticksAbsent } = buildCuts(xml, opts.mediaFrames || {});
+  // Edge accounting rides on the ingest result: how many Resolve-written -1
+  // edges resolved to junctions, and which (if any) could not be anchored.
+  const withEdges = (r) => ({ ...r, resolvedEdges, unresolvedEdges, ticksAbsent });
+  return withEdges(writeSnapshot(dbPath, cuts, {
     ...opts,
     kind: opts.kind ?? 'conform_xml',
     source_ref: xmlPath,
@@ -179,7 +206,7 @@ export function ingestXml(dbPath, xmlPath, opts = {}) {
     seqH,
     fps,
     provenance: opts.provenance ?? 'ingestXml',
-  });
+  }));
 }
 
 function loadPg() {
@@ -267,6 +294,7 @@ export async function ingestLiveTimeline(dbPath, opts = {}) {
       pan_v: t.pan_v ?? null,
       rotation: t.rotation ?? null,
       transition: null,
+      speed: null,
     };
     cut.cut_hash = cutHash(cut);
     return cut;

package/resolve-advanced/server/qc-frame.mjs

@@ -95,6 +95,60 @@ export function markerCategory(verdict, sat = {}) {
   return { category: 'conform', color: 'Red' };
 }
 
+
+/**
+ * Which frame to compare for a cut (E107). A cut whose edge sits under a
+ * transition is a BLEND there — or black, for a fade — so its first record
+ * frame proves nothing: a fade-in reads REF_OFFLINE, a dissolve reads WRONG,
+ * both false. Sample the first frame CLEAR of the incoming window and before
+ * the outgoing one; advance the source frame by the same record offset at the
+ * cut's speed (reverse walks backward). A cut that lies entirely inside its
+ * windows samples its midpoint and says so — the verdict is then a blend
+ * compare, reported, never silently trusted.
+ * @returns {{recordFrame:number|null, sourceFrame:number|null, offset:number, note:string|null}}
+ */
+export function pickQcFrame(cut) {
+  const rs = cut.record_start;
+  if (rs == null) return { recordFrame: null, sourceFrame: cut.oracle_source_frame ?? null, offset: 0, note: null };
+  let win = null;
+  if (cut.transition) {
+    try {
+      win = typeof cut.transition === 'string' ? JSON.parse(cut.transition) : cut.transition;
+    } catch {
+      win = null;
+    }
+  }
+  let rec = rs;
+  let note = null;
+  if (win && (win.in || win.out)) {
+    const last = cut.record_end != null ? cut.record_end - 1 : null;
+    let lo = rs;
+    let hi = last;
+    if (win.in && win.in.end > lo) lo = win.in.end;
+    if (win.out && hi != null && win.out.start - 1 < hi) hi = win.out.start - 1;
+    if (hi == null || lo <= hi) {
+      rec = lo;
+      if (rec !== rs) note = `sampled at ${rec}, clear of the transition window (cut starts ${rs})`;
+    } else {
+      rec = Math.round((rs + (cut.record_end ?? rs)) / 2);
+      note = `cut lies entirely inside transition windows — sampled midpoint ${rec} (a blend; verdict is indicative)`;
+    }
+  }
+  const offset = rec - rs;
+  let src = cut.oracle_source_frame ?? null;
+  if (src != null && offset) {
+    let k = 1;
+    if (cut.speed != null && Number.isFinite(Number(cut.speed)) && Number(cut.speed) !== 0) k = Math.abs(Number(cut.speed)) / 100;
+    else if (cut.record_end != null && cut.xml_in != null && cut.xml_out != null && cut.record_end > rs) {
+      const recSpan = cut.record_end - rs;
+      const srcSpan = Math.abs(cut.xml_out - cut.xml_in);
+      if (srcSpan && srcSpan !== recSpan) k = srcSpan / recSpan;
+    }
+    src = Math.round(src + (cut.reverse ? -1 : 1) * offset * k);
+  }
+  return { recordFrame: rec, sourceFrame: src, offset, note };
+}
+
 /**
  * QC a whole snapshot against a reference. Samplers are injected:
  * opts.sampleConform(cut) -> Float64 gray | null
@@ -119,8 +173,13 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
         continue;
       }
     }
-    const conform = await opts.sampleConform(cut);
-    const reference = await opts.sampleReference(cut);
+    // E107: compare a frame CLEAR of the cut's transition windows — samplers
+    // read qc_record_frame / qc_source_frame when present.
+    const pick = pickQcFrame(cut);
+    const cutForSample = { ...cut, qc_record_frame: pick.recordFrame, qc_source_frame: pick.sourceFrame };
+    const conform = await opts.sampleConform(cutForSample);
+    const reference = await opts.sampleReference(cutForSample);
+    const refFrame = pick.recordFrame ?? cut.record_start;
     let v;
     if (!reference) {
       // can't sample the reference → can't verify → human review
@@ -128,7 +187,7 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
         snapshot_id: snapshotId,
         cut_index: cut.cut_index,
         reference_ref: ref,
-        reference_frame: cut.record_start,
+        reference_frame: refFrame,
         verdict: 'UNREADABLE',
         category: 'review',
         ran_at: opts.now ?? null,
@@ -139,7 +198,7 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
         snapshot_id: snapshotId,
         cut_index: cut.cut_index,
         reference_ref: ref,
-        reference_frame: cut.record_start,
+        reference_frame: refFrame,
         verdict: 'REF_OFFLINE',
         category: 'ref_offline',
         ran_at: opts.now ?? null,
@@ -150,7 +209,7 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
         snapshot_id: snapshotId,
         cut_index: cut.cut_index,
         reference_ref: ref,
-        reference_frame: cut.record_start,
+        reference_frame: refFrame,
         verdict: 'WRONG',
         category: 'turnover',
         ran_at: opts.now ?? null,
@@ -163,7 +222,7 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
         snapshot_id: snapshotId,
         cut_index: cut.cut_index,
         reference_ref: ref,
-        reference_frame: cut.record_start,
+        reference_frame: refFrame,
         verdict: c.verdict,
         category: mc.category,
         structure: c.structure,
@@ -175,7 +234,9 @@ export async function qcSnapshot(dbPath, snapshotId, opts = {}) {
       };
     }
     lineage.writeVerdict(dbPath, v);
-    results.push(v);
+    // The sampling note rides on the result (not the verdict row): where the
+    // frame came from is part of the evidence, not part of the verdict.
+    results.push(pick.note ? { ...v, sample_note: pick.note, sample_offset: pick.offset } : v);
     scanned += 1;
   }
   const counts = {};

package/resolve-advanced/server/qc-sampler.mjs

@@ -1,9 +1,9 @@
 /**
  * ffmpeg sampler adapter for frame-QC (Phase 9 wiring). Builds the two injected
  * samplers qcSnapshot expects, from real media:
- * sampleReference(cut) — the reference render at the cut's record position (burn-in
- * masked, brightness-robust).
- * sampleConform(cut) — the highres source at oracle_source_frame, scaled by the
+ * sampleReference(cut) — the reference render at the cut's QC record frame (the record
+ * start, or the first frame clear of a transition window — E107), burn-in masked.
+ * sampleConform(cut) — the highres source at the matching QC source frame, scaled by the
  * corrected zoom and centre-cropped to the sequence frame (the picture Resolve
  * shows). Residual pan is left to classify's findOffset → OFFSET (still flagged).
  *
@@ -42,8 +42,9 @@ export function makeSamplers(opts = {}) {
   let n = 0;
 
   const sampleReference = async (cut) => {
-    if (cut.record_start == null) return null;
-    const frame = cut.record_start + (opts.refOffset || 0);
+    const recFrame = cut.qc_record_frame ?? cut.record_start;
+    if (recFrame == null) return null;
+    const frame = recFrame + (opts.refOffset || 0);
     const p = path.join(tmp, `ref-${n}.png`);
     if (!grab(opts.referenceMovie, frame / fps, p, `scale=${DW}:${DH}`, opts.ffmpegPath)) return null;
     // classify()/referenceIsBlank() consume a raw Float64Array — unwrap the decode result.
@@ -52,13 +53,14 @@ export function makeSamplers(opts = {}) {
 
   const sampleConform = async (cut) => {
     const src = (opts.mediaMap && opts.mediaMap[cut.source_basename]) || cut.source_path;
-    if (!src || cut.oracle_source_frame == null) return null;
+    const srcFrame = cut.qc_source_frame ?? cut.oracle_source_frame;
+    if (!src || srcFrame == null) return null;
     const zoom = cut.scale_corrected != null ? cut.scale_corrected / 100 : 1;
     const H = Math.round(opts.seqH * zoom);
     const W = Math.round(H * (opts.hrW / opts.hrH));
     const vf = `scale=${W}:${H},crop=${opts.seqW}:${opts.seqH}:(iw-${opts.seqW})/2:(ih-${opts.seqH})/2,scale=${DW}:${DH}`;
     const p = path.join(tmp, `conf-${n++}.png`);
-    if (!grab(src, cut.oracle_source_frame / fps, p, vf, opts.ffmpegPath)) return null;
+    if (!grab(src, srcFrame / fps, p, vf, opts.ffmpegPath)) return null;
     // classify() consumes a raw Float64Array — unwrap the decode result.
     return (await decodeGrayNormalized(p, { width: DW, height: DH })).data;
   };

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

@@ -90,7 +90,7 @@ const reportSchema = z.object({ meta: z.object({}).passthrough().optional(), cut
 export const conformTool = {
   name: 'conform',
   description:
-    'Conform/relink QC engine (offline core). Actions: parse_geometry, oracle_derive, list_targets, repair_ladder, build_manifest, analyze_media (ffprobe target media → res/aspect/codec/bitdepth/fps + quality rank), relink_scalefix (surgical: repoint proxy→highres pathurls + fix the scale double-count per clip, preserving retimes/tracks/audio byte-for-byte; index MULTIPLE footage roots via footageDirs, PROXY excluded; returns warnings.leftOnProxyOrTest + unresolvedSources so a source stuck on its proxy cannot slip through), report; verify (gated on optional sharp); fix_reverse_clip (LIVE DB patch — restore a reversed clip dropped on import: copy a generic reverse MediaTimemapBA blob + set the mirrored "In"; SQLite or PostgreSQL; project must be CLOSED; locate→probe→calibrate K→apply); snapshot (sequence LINEAGE store — ingest_xml/ingest_live an editorial-or-conform XML or a live timeline into one content-hashed schema, then list/diff/show/rollback_plan; the diff is the incremental frame-QC worklist); qc (comprehensive per-cut frame diff vs the reference render → MATCH/OFFSET/WRONG/REF_OFFLINE/UNREADABLE cached per snapshot; conform frame is sampled at the oracle source frame AND scale-corrected to the edit framing before diffing, so reversed/scaled clips compare apples-to-apples; REF_OFFLINE = the reference is black/flat at that record position because the shot was offline upstream in editorial — inconclusive, NOT a conform error; op run [ffmpeg+sharp] / markers [red conform / yellow turnover / blue ref-offline / cyan review marker plan] / propagate [carry unchanged verdicts to a new snapshot]). Frame-math is the truth, not filename matches.',
+    'Conform/relink QC engine (offline core). Actions: parse_geometry, oracle_derive, list_targets, repair_ladder, build_manifest, analyze_media (ffprobe target media → res/aspect/codec/bitdepth/fps + quality rank), relink_scalefix (surgical: repoint proxy→highres pathurls + fix the scale double-count per clip, preserving retimes/tracks/audio byte-for-byte; index MULTIPLE footage roots via footageDirs, PROXY excluded; returns warnings.leftOnProxyOrTest + unresolvedSources so a source stuck on its proxy cannot slip through), report; verify (gated on optional sharp); fix_reverse_clip (LIVE DB patch — restore a reversed clip dropped on import: copy a generic reverse MediaTimemapBA blob + set the mirrored "In"; SQLite or PostgreSQL; project must be CLOSED; locate→probe→calibrate K→apply); snapshot (sequence LINEAGE store — ingest_xml/ingest_live an editorial-or-conform XML or a live timeline into one content-hashed schema, then list/diff/show/rollback_plan; the diff is the incremental frame-QC worklist; ingest_xml reads Resolve\'s OWN FCP7 export: `-1` clip edges resolve to the adjacent transition\'s junction in record order, each cut records the transition windows its edges sit in, and a missing pproTicksIn (Resolve writes none — measured) falls back to `<in>` for the oracle frame instead of losing it, reported as resolvedEdges/unresolvedEdges/ticksAbsent); qc (comprehensive per-cut frame diff vs the reference render → MATCH/OFFSET/WRONG/REF_OFFLINE/UNREADABLE cached per snapshot; each cut is compared at the first frame CLEAR of its transition windows — inside a window the reference is a blend, or black for a fade — with the source frame advanced at the cut\'s speed, and the result says where it sampled (sample_note); a flat/untextured frame is UNREADABLE (review), never a fake MATCH; conform frame is sampled at the oracle source frame AND scale-corrected to the edit framing before diffing, so reversed/scaled clips compare apples-to-apples; REF_OFFLINE = the reference is black/flat at that record position because the shot was offline upstream in editorial — inconclusive, NOT a conform error; op run [ffmpeg+sharp] / markers [red conform / yellow turnover / blue ref-offline / cyan review marker plan] / propagate [carry unchanged verdicts to a new snapshot]). Frame-math is the truth, not filename matches.',
   async handler({ action, args }) {
     if (action === 'parse_geometry') {
       const p = parseSchema.parse(args);

package/resolve-advanced/vendor/conform-qc/parse/xmeml-geometry.js

@@ -11,8 +11,10 @@
  *
  * Output per clip:
  *   { seqstart, seqend, xml_in, xml_out, pproTicksIn, pproTicksOut,
- *     is_subclip, subclip_startoffset, scale_premiere, fileId,
- *     source_basename, srcW, srcH }
+ *     is_subclip, subclip_startoffset, scale_premiere, speed, reverse, fileId,
+ *     source_basename, srcW, srcH, edges_resolved, transition_in, transition_out }
+ *   (-1 edges from Resolve's FCP7 writer resolve to the adjacent transition's
+ *   junction; transition_in/out are the windows the clip's edges sit in)
  *
  * Pure: takes an XML string, returns plain data. No IO.
  */
@@ -146,17 +148,24 @@ function captureTransform(clipitem) {
   };
 }
 
-/** The video-track clipitems, in order. */
-function videoClipitems(sequence) {
-  const tracks = asArray(
-    sequence && sequence.media && sequence.media.video && sequence.media.video.track,
-  );
+
+/**
+ * A track's transitionitems as junctions: the frame a `-1` clip edge resolves
+ * to (alignment-dependent) plus the span. Alignment vocabulary per Resolve's
+ * writer: start/start-black → span start, end/end-black → span end, center
+ * (or absent) → span center.
+ */
+function trackJunctions(track) {
   const out = [];
-  for (const track of tracks) {
-    for (const ci of asArray(track.clipitem)) {
-      // A real clip has a record position + a source in-point.
-      if (ci && ci.start !== undefined && ci.in !== undefined) out.push(ci);
-    }
+  for (const tr of asArray(track && track.transitionitem)) {
+    if (!tr) continue;
+    const s0 = num(tr.start);
+    const e0 = num(tr.end);
+    if (s0 == null || e0 == null) continue;
+    const al = String(tr.alignment || 'center').toLowerCase();
+    const frame = al === 'start-black' || al === 'start' ? s0 : al === 'end-black' || al === 'end' ? e0 : Math.round((s0 + e0) / 2);
+    const effect = tr.effect || {};
+    out.push({ frame, start: s0, end: e0, alignment: al, effectid: effect.effectid != null ? String(effect.effectid) : null });
   }
   return out;
 }
@@ -217,37 +226,95 @@ function parseGeometry(xml) {
   const fileDefs = {};
   collectFileDefs(doc, fileDefs);
 
-  // Pass 2 — capture per-clip geometry.
+  // Pass 2 — capture per-clip geometry, track by track so each clip can be
+  // resolved against ITS track's transitionitems.
+  //
+  // Resolve's FCP7 writer (measured, E105/E107): a clipitem edge that sits
+  // under a transitionitem is written as `-1` and means "this edge is the
+  // adjacent transition's JUNCTION" — the span center for alignment center,
+  // the span start/end for start(-black)/end(-black). `out - in` is the
+  // RECORD duration even under a retime, which anchors the missing edge. A
+  // -1 START edge's <in> is the source at the OVERLAP start (the material
+  // begins under the transition), so <in>/<out> advance by (junction -
+  // span start) to stay record-aligned. Left raw, a -1 record position poisons
+  // every consumer downstream (oracle null, reference sampled at frame 0).
   const clips = [];
-  for (const ci of videoClipitems(sequence)) {
-    const fileNode = ci.file;
-    const fileId = fileNode && fileNode['@_id'] != null ? String(fileNode['@_id']) : null;
-    const def = fileId ? fileDefs[fileId] : null;
-    const sub = ci.subclipinfo;
-    const startoffset = sub ? num(sub.startoffset) : null;
-    const endoffset = sub ? num(sub.endoffset) : null;
-    const transform = captureTransform(ci);
-    clips.push({
-      seqstart: num(ci.start),
-      seqend: num(ci.end),
-      xml_in: num(ci.in),
-      xml_out: num(ci.out),
-      pproTicksIn: num(ci.pproTicksIn),
-      pproTicksOut: num(ci.pproTicksOut),
-      is_subclip: startoffset != null,
-      subclip_startoffset: startoffset != null ? startoffset : 0,
-      subclip_endoffset: endoffset != null ? endoffset : 0,
-      scale_premiere: scalarParam(ci, 'scale'),
-      speed: captureSpeed(ci),
-      reverse: captureReverse(ci),
-      center: transform.center,
-      rotation: transform.rotation,
-      crop: transform.crop,
-      fileId,
-      source_basename: def ? def.basename : null,
-      srcW: def ? def.srcW : null,
-      srcH: def ? def.srcH : null,
-    });
+  const tracks = asArray(sequence && sequence.media && sequence.media.video && sequence.media.video.track);
+  for (const track of tracks) {
+    const junctions = trackJunctions(track);
+    const js = junctions.map((j) => j.frame).sort((a, b) => a - b);
+    // Clips are written in record order, so a clip whose BOTH edges are -1
+    // can only pair junctions at or after the previous clip's end. Without
+    // the cursor, two equal-length clips under three centered transitions
+    // both resolve to the FIRST pair (measured, E107).
+    let cursor = 0;
+    for (const ci of asArray(track.clipitem)) {
+      // A real clip has a record position + a source in-point.
+      if (!(ci && ci.start !== undefined && ci.in !== undefined)) continue;
+      const fileNode = ci.file;
+      const fileId = fileNode && fileNode['@_id'] != null ? String(fileNode['@_id']) : null;
+      const def = fileId ? fileDefs[fileId] : null;
+      const sub = ci.subclipinfo;
+      const startoffset = sub ? num(sub.startoffset) : null;
+      const endoffset = sub ? num(sub.endoffset) : null;
+      const transform = captureTransform(ci);
+      const start0 = num(ci.start);
+      const end0 = num(ci.end);
+      const inF = num(ci.in);
+      const outF = num(ci.out);
+      const dur = inF != null && outF != null ? outF - inF : null;
+      let start = start0;
+      let end = end0;
+      let inAdj = 0;
+      if (start === -1 && end !== -1 && end != null && dur != null) start = end - dur;
+      else if (end === -1 && start !== -1 && start != null && dur != null) end = start + dur;
+      else if (start === -1 && end === -1 && dur != null && js.length) {
+        const pair = js.find((a) => a >= cursor && js.includes(a + dur));
+        if (pair != null) {
+          start = pair;
+          end = pair + dur;
+        }
+      }
+      if (end != null && end >= 0) cursor = Math.max(cursor, end);
+      if (start0 === -1 && start != null && start >= 0) {
+        const j = junctions.find((jj) => jj.frame === start);
+        if (j) inAdj = start - j.start;
+      }
+      const edgesResolved = start0 === -1 || end0 === -1;
+      const unresolved = (start0 === -1 && (start == null || start < 0)) || (end0 === -1 && (end == null || end < 0));
+      // The transition windows this clip's edges sit in: the incoming window
+      // contains the record start, the outgoing window contains the record
+      // end. Downstream frame-QC must sample CLEAR of both (the reference is
+      // a blend — or black, for a fade — inside them).
+      const win = (j) => (j ? { start: j.start, end: j.end, junction: j.frame, alignment: j.alignment, effectid: j.effectid } : null);
+      const inWin = start != null && start >= 0 ? junctions.find((j) => start >= j.start && start <= j.end) : null;
+      const outWin = end != null && end >= 0 ? junctions.find((j) => end >= j.start && end <= j.end) : null;
+      clips.push({
+        seqstart: start,
+        seqend: end,
+        xml_in: inF != null ? inF + inAdj : inF,
+        xml_out: outF != null ? outF + inAdj : outF,
+        pproTicksIn: num(ci.pproTicksIn),
+        pproTicksOut: num(ci.pproTicksOut),
+        is_subclip: startoffset != null,
+        subclip_startoffset: startoffset != null ? startoffset : 0,
+        subclip_endoffset: endoffset != null ? endoffset : 0,
+        scale_premiere: scalarParam(ci, 'scale'),
+        speed: captureSpeed(ci),
+        reverse: captureReverse(ci),
+        center: transform.center,
+        rotation: transform.rotation,
+        crop: transform.crop,
+        fileId,
+        source_basename: def ? def.basename : null,
+        srcW: def ? def.srcW : null,
+        srcH: def ? def.srcH : null,
+        edges_resolved: edgesResolved,
+        edges_unresolved: unresolved,
+        transition_in: win(inWin),
+        transition_out: win(outWin),
+      });
+    }
   }
 
   return { sequence: sequenceInfo(sequence), fileDefs, clips, transitions: videoTransitions(sequence) };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.164.0"
+VERSION = "2.165.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/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.164.0"
+VERSION = "2.165.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -2794,6 +2794,41 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "missing",
         "mitigation": ["editorial.verify_roundtrip audioNotInExport", "timeline.export_timeline_checked"],
     },
+    {
+        "symbol": "Timeline.Export EXPORT_FCP_7_XML (no pproTicksIn, -1 edges under transitions)",
+        "object": "Timeline",
+        "signature": "(filePath, EXPORT_FCP_7_XML, EXPORT_NONE) -> bool",
+        "reality": "Resolve's FCP7 XML writer (measured on Studio 19.1.3.7, "
+                   "E107, verbatim export kept as a fixture) emits NO "
+                   "pproTicksIn/pproTicksOut on any clipitem — the Premiere "
+                   "tick fields a Premiere-shaped oracle treats as the "
+                   "authoritative source position are simply absent, so a "
+                   "reader that requires them derives no source frame for "
+                   "ANY cut of a Resolve export. Every clipitem edge that "
+                   "sits under a transitionitem is written as -1 and means "
+                   "the transition's junction (span center for alignment "
+                   "center; the writer emitted `center` for every dissolve "
+                   "and fade authored centered), `out - in` is the record "
+                   "duration, and a -1 START edge's <in> is the source at the "
+                   "overlap start. With three centered transitions two "
+                   "equal-length clips both carry -1/-1 edges, so a reader "
+                   "must pair junctions in record order — the first pair "
+                   "that fits places both clips at the same position. Black "
+                   "legs are Solid Color generatoritems whose -1 edge "
+                   "resolves the same way.",
+        "recommended": "Read <in> as the literal source frame (Resolve reads "
+                       "and writes it that way), record-align it by the "
+                       "junction-minus-span-start offset on a -1 start, and "
+                       "walk -1/-1 clips with a record-order cursor. "
+                       "conform.snapshot ingest_xml and "
+                       "editorial.parse_interchange both do; the frame QC "
+                       "then samples each cut CLEAR of its transition "
+                       "windows (inside one the reference is a blend, or "
+                       "black for a fade).",
+        "tags": ["timeline", "export", "xml", "fcp7", "transitions", "silent-failure"],
+        "submit": "missing",
+        "mitigation": ["conform.snapshot ingest_xml", "editorial.parse_interchange", "conform.qc"],
+    },
     {
         "symbol": "Project.SetRenderSettings ExportSubtitle/SubtitleFormat (inert on 19.x)",
         "object": "Project",