davinci-resolve-mcp 2.57.4 → 2.58.0

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

@@ -0,0 +1,270 @@
+/**
+ * Cluster D — deliverable QC / compliance. The single biggest reject-preventer for a
+ * two-deliverable-per-episode show (producer + online both ranked it #1).
+ *
+ * All MEASURE-only, report-only (gate: review — NEVER auto-`pass`-clear a deliverable; the
+ * producer/online sign off). Silent-lie discipline extends to media here: assert bytes read,
+ * skip-not-fake on unreadable, and a per-field pass/fail (an empty/green report is the lie).
+ *
+ *   deliverable_qc        — ffprobe a rendered file vs its spec → pass/fail PER FIELD
+ *   loudness_qc           — ffmpeg ebur128 integrated LUFS + true-peak dBTP + LRA vs target
+ *   reframe_blanking_check — letterbox/pillarbox + active-picture bounds + illegal edge pixels
+ *   conform_completeness  — all clips online, handles present, duration == reference (frame-exact)
+ *   re_delivery_diff      — old vs new render: frame-count Δ, duration Δ, spec drift, sampled changes
+ *
+ * Deps: ffmpeg/ffprobe (peer) for the file tools; sharp for reframe_blanking on a PNG.
+ * The comparison cores are PURE (probe → check) so they unit-test without media. No Resolve, no LLM.
+ */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { probeMedia } from './ffprobe-media.mjs';
+import { requireFfmpeg } from './capabilities.mjs';
+
+const require = createRequire(import.meta.url);
+
+// ── deliverable_qc ─────────────────────────────────────────────────────
+const eq = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+const near = (a, b, tol) => Math.abs(Number(a) - Number(b)) <= tol;
+
+/**
+ * Compare a probed media object to a deliverable spec → per-field pass/fail. PURE.
+ * @param {object} probe result of probeMedia()
+ * @param {object} spec { video:{...}, audio:{...}, container, durationSeconds, durationTolSeconds, filenameRegex }
+ * @param {{filename?:string, fpsTol?:number}} [opts]
+ */
+export function checkDeliverable(probe, spec = {}, opts = {}) {
+  const fields = [];
+  const add = (field, expected, actual, pass, note) => fields.push({ field, expected, actual, pass, ...(note ? { note } : {}) });
+  const fpsTol = opts.fpsTol ?? 0.01;
+
+  if (spec.video) {
+    const v = probe.video || {};
+    const s = spec.video;
+    if (s.codec != null) add('video.codec', s.codec, v.codec, eq(s.codec, v.codec));
+    if (s.profile != null) add('video.profile', s.profile, v.profile, eq(s.profile, v.profile));
+    if (s.width != null) add('video.width', s.width, v.width, Number(s.width) === Number(v.width));
+    if (s.height != null) add('video.height', s.height, v.height, Number(s.height) === Number(v.height));
+    if (s.fps != null) add('video.fps', s.fps, v.fps, near(s.fps, v.fps, fpsTol));
+    if (s.scan != null) add('video.scan', s.scan, v.scan, eq(s.scan, v.scan));
+    if (s.colorPrimaries != null) add('video.colorPrimaries', s.colorPrimaries, v.colorPrimaries, eq(s.colorPrimaries, v.colorPrimaries));
+    if (s.colorTransfer != null) add('video.colorTransfer', s.colorTransfer, v.colorTransfer, eq(s.colorTransfer, v.colorTransfer));
+    if (s.colorMatrix != null) add('video.colorMatrix', s.colorMatrix, v.colorMatrix, eq(s.colorMatrix, v.colorMatrix));
+    if (s.bitDepth != null) add('video.bitDepth', s.bitDepth, v.bitDepth, Number(s.bitDepth) === Number(v.bitDepth));
+    if (s.pixFmt != null) add('video.pixFmt', s.pixFmt, v.pixFmt, eq(s.pixFmt, v.pixFmt));
+  }
+  if (spec.audio) {
+    const a0 = (probe.audio && probe.audio[0]) || {};
+    const totalCh = (probe.audio || []).reduce((n, a) => n + (a.channels || 0), 0);
+    const s = spec.audio;
+    if (s.streams != null) add('audio.streams', s.streams, (probe.audio || []).length, Number(s.streams) === (probe.audio || []).length);
+    if (s.channels != null) add('audio.channels', s.channels, totalCh, Number(s.channels) === totalCh, 'total across streams');
+    if (s.channelLayout != null) add('audio.channelLayout', s.channelLayout, a0.channelLayout, eq(s.channelLayout, a0.channelLayout));
+    if (s.sampleRate != null) add('audio.sampleRate', s.sampleRate, a0.sampleRate, Number(s.sampleRate) === Number(a0.sampleRate));
+    if (s.codec != null) add('audio.codec', s.codec, a0.codec, eq(s.codec, a0.codec));
+    if (s.bitDepth != null) add('audio.bitDepth', s.bitDepth, a0.bitDepth, Number(s.bitDepth) === Number(a0.bitDepth));
+  }
+  if (spec.container != null) add('container', spec.container, probe.format.container, eq(spec.container, probe.format.container));
+  if (spec.durationSeconds != null) {
+    const tol = spec.durationTolSeconds ?? 0.5;
+    add('duration', `${spec.durationSeconds}s ±${tol}`, probe.format.duration, near(spec.durationSeconds, probe.format.duration, tol));
+  }
+  if (spec.filenameRegex != null && opts.filename != null) {
+    let re;
+    try {
+      re = new RegExp(spec.filenameRegex);
+    } catch {
+      re = null;
+    }
+    add('filename', spec.filenameRegex, opts.filename, re ? re.test(opts.filename) : false, re ? undefined : 'invalid regex');
+  }
+
+  const failed = fields.filter((f) => !f.pass);
+  return { pass: failed.length === 0, fieldCount: fields.length, failedCount: failed.length, fields, failed: failed.map((f) => f.field) };
+}
+
+/** deliverable_qc: probe a file + check it against a spec. */
+export function deliverableQc(file, spec = {}, opts = {}) {
+  const probe = probeMedia(file, opts);
+  if (!probe) throw new Error(`deliverable_qc: could not probe '${file}' (unreadable/not media — skip-not-fake)`);
+  const filename = opts.filename ?? file.split('/').pop();
+  const result = checkDeliverable(probe, spec, { filename, fpsTol: opts.fpsTol });
+  return { file, probe, ...result, gate: 'review', note: 'measurement only — the producer/online signs off; never auto-pass-clear' };
+}
+
+// ── loudness_qc ────────────────────────────────────────────────────────
+/** Parse ffmpeg ebur128 stderr Summary block → { integratedLufs, truePeakDbtp, lra, threshold }. */
+export function parseEbur128(stderr) {
+  const grab = (label) => {
+    const re = new RegExp(`${label}:\\s*(-?\\d+(?:\\.\\d+)?)`);
+    const m = re.exec(stderr);
+    return m ? Number(m[1]) : null;
+  };
+  // The Summary block prints "I:", "LRA:", "Peak:" under headers; match the trailing values.
+  const integratedLufs = grab('I') ?? grab('Integrated loudness\\s*[\\s\\S]*?I');
+  const lra = grab('LRA') ?? grab('Loudness range\\s*[\\s\\S]*?LRA');
+  const truePeakDbtp = grab('Peak');
+  return { integratedLufs, lra, truePeakDbtp };
+}
+
+/**
+ * loudness_qc: measure integrated LUFS + true-peak + LRA and check vs a per-deliverable target.
+ * @param {string} file
+ * @param {{integrated?:number, integratedTol?:number, truePeakMax?:number, lraMax?:number, ffmpeg?:string}} target
+ */
+export function loudnessQc(file, target = {}) {
+  requireFfmpeg();
+  const ffmpeg = target.ffmpeg || 'ffmpeg';
+  const r = spawnSync(ffmpeg, ['-nostats', '-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-'], {
+    encoding: 'utf8',
+    timeout: 120000,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const stderr = r.stderr || '';
+  const measured = parseEbur128(stderr);
+  if (measured.integratedLufs == null) throw new Error(`loudness_qc: could not measure loudness on '${file}' (no audio? ffmpeg ebur128 produced no summary)`);
+  const checks = [];
+  const add = (field, expected, actual, pass) => checks.push({ field, expected, actual, pass });
+  if (target.integrated != null) {
+    const tol = target.integratedTol ?? 1.0;
+    add('integratedLufs', `${target.integrated} ±${tol}`, measured.integratedLufs, Math.abs(measured.integratedLufs - target.integrated) <= tol);
+  }
+  if (target.truePeakMax != null)
+    add('truePeakDbtp', `≤ ${target.truePeakMax}`, measured.truePeakDbtp, measured.truePeakDbtp != null && measured.truePeakDbtp <= target.truePeakMax);
+  if (target.lraMax != null) add('lra', `≤ ${target.lraMax}`, measured.lra, measured.lra != null && measured.lra <= target.lraMax);
+  const failed = checks.filter((c) => !c.pass);
+  return { file, measured, pass: failed.length === 0, checks, failed: failed.map((c) => c.field), gate: 'review' };
+}
+
+// ── reframe_blanking_check ─────────────────────────────────────────────
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("reframe_blanking_check needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+
+/**
+ * reframe_blanking_check: detect letterbox/pillarbox bars + active-picture bounds + illegal
+ * edge pixels on a display-referred PNG (an extracted frame). Deterministic.
+ * @param {string} pngPath
+ * @param {{blackThreshold?:number, barFraction?:number, maxSide?:number}} opts
+ */
+export async function reframeBlankingCheck(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const maxSide = opts.maxSide ?? 480;
+  const blk = opts.blackThreshold ?? 16; // ≤ this (per channel) counts as blanking
+  const barFrac = opts.barFraction ?? 0.98; // a row/col is a bar if ≥98% of its pixels are black
+  let data, ch, W, H;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+    W = out.info.width;
+    H = out.info.height;
+  } catch {
+    return null;
+  }
+  const isBlack = (i) => data[i] <= blk && data[i + 1] <= blk && data[i + 2] <= blk;
+  const rowBlack = (y) => {
+    let n = 0;
+    for (let x = 0; x < W; x++) if (isBlack((y * W + x) * ch)) n++;
+    return n / W >= barFrac;
+  };
+  const colBlack = (x) => {
+    let n = 0;
+    for (let y = 0; y < H; y++) if (isBlack((y * W + x) * ch)) n++;
+    return n / H >= barFrac;
+  };
+  let top = 0,
+    bottom = 0,
+    left = 0,
+    right = 0;
+  while (top < H && rowBlack(top)) top++;
+  while (bottom < H - top && rowBlack(H - 1 - bottom)) bottom++;
+  while (left < W && colBlack(left)) left++;
+  while (right < W - left && colBlack(W - 1 - right)) right++;
+  const activeW = Math.max(0, W - left - right);
+  const activeH = Math.max(0, H - top - bottom);
+  const activeAspect = activeH ? +(activeW / activeH).toFixed(4) : 0;
+  // Illegal edge pixels: a frame edge that is neither fully blanked nor part of the active
+  // picture bound cleanly (a 1px bright seam in the blanking) — report the brightest edge px.
+  let edgeMax = 0;
+  const scan = (i) => {
+    edgeMax = Math.max(edgeMax, data[i], data[i + 1], data[i + 2]);
+  };
+  for (let x = 0; x < W; x++) {
+    scan((0 * W + x) * ch);
+    scan(((H - 1) * W + x) * ch);
+  }
+  for (let y = 0; y < H; y++) {
+    scan((y * W + 0) * ch);
+    scan((y * W + (W - 1)) * ch);
+  }
+  return {
+    frameSize: { w: W, h: H },
+    bars: { top: +(top / H).toFixed(4), bottom: +(bottom / H).toFixed(4), left: +(left / W).toFixed(4), right: +(right / W).toFixed(4) },
+    activeRect: { x: left, y: top, w: activeW, h: activeH },
+    activeAspect,
+    letterboxed: top + bottom > 0,
+    pillarboxed: left + right > 0,
+    edgeMaxLuma: edgeMax,
+    illegalEdge: edgeMax > blk && top === 0 && bottom === 0 && left === 0 && right === 0 ? false : edgeMax > blk && (top || bottom || left || right) > 0,
+  };
+}
+
+// ── conform_completeness ───────────────────────────────────────────────
+/**
+ * conform_completeness: assert a conformed timeline is deliver-ready. PURE over a supplied
+ * structure (the live server reports clip online-state/handles; Node judges). Frame-exact.
+ * @param {{clips:Array<{id, online?:boolean, handleIn?:number, handleOut?:number}>, timelineFrames?:number}} timeline
+ * @param {{referenceFrames?:number, minHandle?:number}} opts
+ */
+export function conformCompleteness(timeline, opts = {}) {
+  const clips = timeline.clips || [];
+  const minHandle = opts.minHandle ?? 0;
+  const offline = clips.filter((c) => c.online === false).map((c) => c.id);
+  const shortHandles = clips.filter((c) => minHandle > 0 && ((c.handleIn ?? Infinity) < minHandle || (c.handleOut ?? Infinity) < minHandle)).map((c) => c.id);
+  const checks = [];
+  checks.push({ field: 'all_online', pass: offline.length === 0, offline });
+  if (minHandle > 0) checks.push({ field: 'handles', pass: shortHandles.length === 0, minHandle, shortHandles });
+  if (opts.referenceFrames != null)
+    checks.push({
+      field: 'duration_frame_exact',
+      pass: Number(timeline.timelineFrames) === Number(opts.referenceFrames),
+      expected: opts.referenceFrames,
+      actual: timeline.timelineFrames ?? null,
+    });
+  const failed = checks.filter((c) => !c.pass);
+  return { pass: failed.length === 0, clipCount: clips.length, checks, failed: failed.map((c) => c.field), gate: 'review' };
+}
+
+// ── re_delivery_diff ───────────────────────────────────────────────────
+/**
+ * re_delivery_diff: compare an OLD render to a NEW render → frame-count Δ, duration Δ, spec
+ * drift (codec/raster/fps/color/audio), and sampled-frame change hints. PURE core over two probes.
+ */
+export function compareRenders(oldP, newP) {
+  const drift = [];
+  const cmp = (field, a, b) => {
+    if (String(a) !== String(b)) drift.push({ field, old: a, new: b });
+  };
+  const ov = oldP.video || {},
+    nv = newP.video || {};
+  for (const k of ['codec', 'profile', 'width', 'height', 'fps', 'scan', 'colorPrimaries', 'colorTransfer', 'colorMatrix', 'bitDepth', 'pixFmt'])
+    cmp(`video.${k}`, ov[k], nv[k]);
+  cmp('container', oldP.format.container, newP.format.container);
+  const oa = (oldP.audio || [])[0] || {},
+    na = (newP.audio || [])[0] || {};
+  for (const k of ['codec', 'channels', 'channelLayout', 'sampleRate']) cmp(`audio.${k}`, oa[k], na[k]);
+  const frameDelta = (nv.frameCount || 0) - (ov.frameCount || 0);
+  const durationDelta = +(newP.format.duration - oldP.format.duration).toFixed(4);
+  return { frameDelta, durationDelta, specDrift: drift, specDriftCount: drift.length, sameLength: frameDelta === 0 };
+}
+
+export function reDeliveryDiff(oldFile, newFile, opts = {}) {
+  const oldP = probeMedia(oldFile, opts);
+  const newP = probeMedia(newFile, opts);
+  if (!oldP || !newP) throw new Error('re_delivery_diff: could not probe one of the renders (skip-not-fake)');
+  return { old: oldFile, new: newFile, ...compareRenders(oldP, newP), gate: 'review' };
+}

package/resolve-advanced/server/editorial.mjs

@@ -0,0 +1,370 @@
+/**
+ * Cluster E — editorial integrity. The turnover interchange (XML/EDL/OTIO) → a normalized
+ * edit-event list → a structured CHANGELIST (what moved/retimed/replaced/appeared/vanished) and
+ * a per-event CONFORM MANIFEST assert BEFORE grading. This is the north star made real: the
+ * changelist drives the frame-QC worklist.
+ *
+ * TIMING silent-lie discipline (cross-craft review): flattened retime · dropped J/L-cut audio ·
+ * framerate/pulldown slip · reverse dropped · transition-handle starvation — THROW/FLAG,
+ * skip-not-fake. A conform that silently flattens a speed ramp or drops split-track audio is the
+ * timing analogue of a faked grade.
+ *
+ * Interchange breadth AT INGEST: EDL (CMX3600) + OTIO (JSON) parse natively here; XMEML via a
+ * light clipitem parse. AAF is binary — honest refuse (convert to OTIO/EDL upstream).
+ *
+ * PURE + deterministic. No Resolve, no LLM.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// ── timecode ───────────────────────────────────────────────────────────
+const TC_RE = /^(\d{2}):(\d{2}):(\d{2})[:;](\d{2,3})$/;
+export function tcToFrames(tc, fps) {
+  const m = TC_RE.exec(String(tc).trim());
+  if (!m || !fps) return null;
+  const [, h, mm, s, f] = m.map(Number);
+  return Math.round((h * 3600 + mm * 60 + s) * fps) + f;
+}
+const isTc = (t) => TC_RE.test(t);
+
+/**
+ * Normalized edit event. All positions in FRAMES.
+ * { index, track, source, srcIn, srcOut, recIn, recOut, speed(%), reverse, transition, fps }
+ */
+function evt(o) {
+  return {
+    index: o.index ?? null,
+    track: o.track || 'V',
+    source: o.source || 'UNKNOWN',
+    srcIn: o.srcIn ?? null,
+    srcOut: o.srcOut ?? null,
+    recIn: o.recIn ?? null,
+    recOut: o.recOut ?? null,
+    speed: o.speed ?? 100,
+    reverse: o.reverse ?? false,
+    transition: o.transition || null,
+    fps: o.fps ?? null,
+  };
+}
+
+// ── EDL (CMX3600) ──────────────────────────────────────────────────────
+/** Parse a CMX3600 EDL text into normalized events. */
+export function parseEDL(text, opts = {}) {
+  const fps = opts.fps ?? 24;
+  const events = [];
+  let pendingSpeed = null; // from an M2 motion line preceding/following the event
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Motion (speed) line: M2 <reel> <fps-signed> <srcTC>
+    const m2 = /^M2\s+(\S+)\s+(-?\d+(?:\.\d+)?)/.exec(line);
+    if (m2) {
+      const playFps = Number(m2[2]);
+      pendingSpeed = { reel: m2[1], speedPct: fps ? (playFps / fps) * 100 : 100, reverse: playFps < 0 };
+      // Attach to the last event with this reel.
+      const target = [...events].reverse().find((e) => e.source === m2[1]);
+      if (target) {
+        target.speed = +Math.abs(pendingSpeed.speedPct).toFixed(2);
+        target.reverse = pendingSpeed.reverse;
+      }
+      continue;
+    }
+    const tokens = line.split(/\s+/);
+    if (!/^\d+$/.test(tokens[0])) continue; // not an event line
+    const tcs = tokens.filter(isTc);
+    if (tcs.length < 4) continue;
+    const [srcIn, srcOut, recIn, recOut] = tcs.slice(-4);
+    const head = tokens.slice(0, tokens.indexOf(tcs[tcs.length - 4]));
+    const [eventNum, reel, channel, transition] = head;
+    const dur = transition && transition !== 'C' ? Number(head[4]) : 0;
+    const track = /A/i.test(channel || '') && !/V/i.test(channel || '') ? 'A' : 'V';
+    events.push(
+      evt({
+        index: Number(eventNum),
+        track,
+        source: reel,
+        srcIn: tcToFrames(srcIn, fps),
+        srcOut: tcToFrames(srcOut, fps),
+        recIn: tcToFrames(recIn, fps),
+        recOut: tcToFrames(recOut, fps),
+        transition: transition && transition !== 'C' ? { type: transition, duration: dur || 0 } : null,
+        fps,
+      }),
+    );
+  }
+  return events;
+}
+
+// ── OTIO (JSON) ────────────────────────────────────────────────────────
+/** Parse an OTIO timeline JSON (object or string) into normalized events. */
+export function parseOTIO(otio, opts = {}) {
+  const doc = typeof otio === 'string' ? JSON.parse(otio) : otio;
+  const tracks = (doc.tracks && doc.tracks.children) || [];
+  const events = [];
+  let idx = 1;
+  for (const track of tracks) {
+    const kind = track.kind === 'Audio' ? 'A' : 'V';
+    let rec = 0;
+    for (const child of track.children || []) {
+      const schema = child.OTIO_SCHEMA || '';
+      const dur = (child.source_range && child.source_range.duration && child.source_range.duration.value) || 0;
+      const rate = (child.source_range && child.source_range.duration && child.source_range.duration.rate) || opts.fps || 24;
+      if (schema.startsWith('Gap')) {
+        rec += dur;
+        continue;
+      }
+      if (schema.startsWith('Clip')) {
+        const startVal = (child.source_range && child.source_range.start_time && child.source_range.start_time.value) || 0;
+        // Retime via a LinearTimeWarp effect (time_scalar).
+        let speed = 100,
+          reverse = false;
+        for (const eff of child.effects || []) {
+          if (eff.time_scalar != null) {
+            speed = +(eff.time_scalar * 100).toFixed(2);
+            reverse = eff.time_scalar < 0;
+          }
+        }
+        const src = (child.media_reference && (child.media_reference.target_url || child.media_reference.name)) || child.name || 'UNKNOWN';
+        events.push(
+          evt({
+            index: idx++,
+            track: kind,
+            source: src,
+            srcIn: startVal,
+            srcOut: startVal + dur,
+            recIn: rec,
+            recOut: rec + dur,
+            speed: Math.abs(speed),
+            reverse,
+            fps: rate,
+          }),
+        );
+        rec += dur;
+      }
+    }
+  }
+  return events;
+}
+
+// ── XMEML (FCP7 XML) — light clipitem parse ────────────────────────────
+export function parseXMEMLEvents(xml, opts = {}) {
+  const { XMLParser } = require('fast-xml-parser');
+  const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' });
+  const doc = parser.parse(xml);
+  const events = [];
+  let idx = 1;
+  const seqRate = opts.fps || 24;
+  const walk = (node, track) => {
+    if (!node) return;
+    const items = Array.isArray(node) ? node : [node];
+    for (const it of items) {
+      const name = it.name || (it.file && it.file.name) || 'UNKNOWN';
+      const start = Number(it.start);
+      const end = Number(it.end);
+      const inF = Number(it.in);
+      const outF = Number(it.out);
+      let speed = 100,
+        reverse = false;
+      // speed via a timeremap/motion filter (best-effort)
+      const filters = it.filter ? (Array.isArray(it.filter) ? it.filter : [it.filter]) : [];
+      for (const fl of filters) {
+        const params = fl.effect && fl.effect.parameter ? (Array.isArray(fl.effect.parameter) ? fl.effect.parameter : [fl.effect.parameter]) : [];
+        for (const pm of params) {
+          if (/speed/i.test(pm.name || '') && pm.value != null) {
+            speed = Math.abs(Number(pm.value));
+            reverse = Number(pm.value) < 0;
+          }
+        }
+      }
+      if (Number.isFinite(start) && Number.isFinite(end)) {
+        events.push(evt({ index: idx++, track, source: name, srcIn: inF, srcOut: outF, recIn: start, recOut: end, speed, reverse, fps: seqRate }));
+      }
+    }
+  };
+  const seq = doc.xmeml && doc.xmeml.sequence;
+  const media = seq && seq.media;
+  if (media) {
+    const vtracks = media.video && media.video.track ? (Array.isArray(media.video.track) ? media.video.track : [media.video.track]) : [];
+    for (const t of vtracks) if (t.clipitem) walk(t.clipitem, 'V');
+    const atracks = media.audio && media.audio.track ? (Array.isArray(media.audio.track) ? media.audio.track : [media.audio.track]) : [];
+    for (const t of atracks) if (t.clipitem) walk(t.clipitem, 'A');
+  }
+  return events;
+}
+
+/** Dispatch by format. AAF is an honest refuse (binary — convert to OTIO/EDL upstream). */
+export function parseInterchange(format, content, opts = {}) {
+  switch (String(format).toLowerCase()) {
+    case 'edl':
+      return parseEDL(content, opts);
+    case 'otio':
+      return parseOTIO(content, opts);
+    case 'xml':
+    case 'xmeml':
+    case 'fcp7':
+      return parseXMEMLEvents(content, opts);
+    case 'aaf':
+      throw new Error('parse_interchange: AAF is binary — not parseable offline in pure JS. Convert to OTIO or EDL upstream (e.g. via OpenTimelineIO).');
+    default:
+      throw new Error(`parse_interchange: unknown format '${format}' (edl|otio|xml|aaf)`);
+  }
+}
+
+// ── turnover_changelist ────────────────────────────────────────────────
+const sig = (e) => `${e.track}:${e.source}`;
+
+/**
+ * Diff two normalized event lists → per-event {kind: moved|retimed|replaced|new|gone|unchanged}.
+ * @param {Array} oldEvents
+ * @param {Array} newEvents
+ * @param {{recTolerance?:number}} [opts]
+ */
+export function diffChangelist(oldEvents, newEvents, opts = {}) {
+  const recTol = opts.recTolerance ?? 1;
+  const oldPool = oldEvents.map((e) => ({ e, used: false }));
+  const changes = [];
+
+  for (const ne of newEvents) {
+    // Prefer a same-source match; among those, the closest record position.
+    const candidates = oldPool.filter((o) => !o.used && sig(o.e) === sig(ne));
+    let match = null;
+    if (candidates.length) {
+      candidates.sort((a, b) => Math.abs((a.e.recIn ?? 0) - (ne.recIn ?? 0)) - Math.abs((b.e.recIn ?? 0) - (ne.recIn ?? 0)));
+      match = candidates[0];
+    }
+    if (!match) {
+      changes.push({ kind: 'new', source: ne.source, track: ne.track, newRecIn: ne.recIn });
+      continue;
+    }
+    match.used = true;
+    const oe = match.e;
+    const deltas = {};
+    let kind = 'unchanged';
+    if (Math.abs((oe.speed ?? 100) - (ne.speed ?? 100)) > 0.01 || oe.reverse !== ne.reverse) {
+      kind = 'retimed';
+      deltas.speed = { old: oe.speed, new: ne.speed };
+      if (oe.reverse !== ne.reverse) deltas.reverse = { old: oe.reverse, new: ne.reverse };
+    } else if (Math.abs((oe.recIn ?? 0) - (ne.recIn ?? 0)) > recTol) {
+      kind = 'moved';
+      deltas.recIn = { old: oe.recIn, new: ne.recIn };
+    } else if ((oe.srcIn ?? null) !== (ne.srcIn ?? null) || (oe.srcOut ?? null) !== (ne.srcOut ?? null)) {
+      kind = 'trimmed';
+      deltas.src = { old: [oe.srcIn, oe.srcOut], new: [ne.srcIn, ne.srcOut] };
+    }
+    if (kind !== 'unchanged') changes.push({ kind, source: ne.source, track: ne.track, oldRecIn: oe.recIn, newRecIn: ne.recIn, deltas });
+  }
+  // Unconsumed old events → gone (unless a 'new' at the same rec position → replaced).
+  for (const o of oldPool.filter((x) => !x.used)) {
+    const replacement = changes.find((c) => c.kind === 'new' && c.track === o.e.track && Math.abs((c.newRecIn ?? 0) - (o.e.recIn ?? 0)) <= recTol);
+    if (replacement) {
+      replacement.kind = 'replaced';
+      replacement.oldSource = o.e.source;
+      replacement.oldRecIn = o.e.recIn;
+    } else {
+      changes.push({ kind: 'gone', source: o.e.source, track: o.e.track, oldRecIn: o.e.recIn });
+    }
+  }
+  const counts = {};
+  for (const c of changes) counts[c.kind] = (counts[c.kind] || 0) + 1;
+  changes.sort((a, b) => (a.newRecIn ?? a.oldRecIn ?? 0) - (b.newRecIn ?? b.oldRecIn ?? 0));
+  return { changes, counts, changedCount: changes.length, gate: 'review' };
+}
+
+// ── TIMING silent-lie guards ───────────────────────────────────────────
+/**
+ * Detect timing lies between an old (locked-cut) and new (conformed) event list.
+ * @returns {{flags:Array<{kind, source, detail}>}}
+ */
+export function timingGuards(oldEvents, newEvents) {
+  const flags = [];
+  const newBySig = new Map();
+  for (const e of newEvents) {
+    if (!newBySig.has(sig(e))) newBySig.set(sig(e), []);
+    newBySig.get(sig(e)).push(e);
+  }
+  for (const oe of oldEvents) {
+    const matches = newBySig.get(sig(oe)) || [];
+    const ne = matches[0];
+    if (!ne) {
+      // A dropped audio event where its video sibling survives → dropped J/L-cut audio.
+      if (oe.track === 'A' && newEvents.some((x) => x.track === 'V' && x.source === oe.source))
+        flags.push({ kind: 'dropped_split_audio', source: oe.source, detail: 'audio event gone but video sibling present (J/L-cut lost)' });
+      continue;
+    }
+    // Flattened retime: a speed ramp/change flattened to 100%.
+    if ((oe.speed ?? 100) !== 100 && (ne.speed ?? 100) === 100)
+      flags.push({ kind: 'flattened_retime', source: oe.source, detail: `speed ${oe.speed}% → 100% (retime lost)` });
+    // Reverse dropped.
+    if (oe.reverse && !ne.reverse) flags.push({ kind: 'reverse_dropped', source: oe.source, detail: 'reversed clip conformed forward' });
+    // Framerate/pulldown slip.
+    if (oe.fps && ne.fps && oe.fps !== ne.fps) flags.push({ kind: 'framerate_slip', source: oe.source, detail: `fps ${oe.fps} → ${ne.fps}` });
+  }
+  return { flags, flagged: flags.length > 0 };
+}
+
+// ── conform_manifest ───────────────────────────────────────────────────
+/**
+ * Per-event conform assert before grading. PURE over events + a resolution map.
+ * @param {Array} events normalized events
+ * @param {Object} resolution source → { online?, path?, handleIn?, handleOut?, tcBase?, reverse?, speed? }
+ * @param {{minHandle?:number, expectTcBase?:string}} [opts]
+ */
+export function conformManifest(events, resolution = {}, opts = {}) {
+  const minHandle = opts.minHandle ?? 0;
+  const rows = [];
+  for (const e of events) {
+    const res = resolution[e.source] || {};
+    const checks = [];
+    const add = (name, pass, detail) => checks.push({ name, pass, ...(detail ? { detail } : {}) });
+    add('source_resolved', res.online !== false && !!(res.path || res.online), res.online === false ? 'offline' : res.path ? undefined : 'no resolved path');
+    // Handles — and transition-handle starvation (a dissolve needs handle ≥ half its duration each side).
+    const needHandle = Math.max(minHandle, e.transition ? Math.ceil((e.transition.duration || 0) / 2) : 0);
+    if (needHandle > 0) {
+      const ok = (res.handleIn ?? 0) >= needHandle && (res.handleOut ?? 0) >= needHandle;
+      add(
+        'handles',
+        ok,
+        ok ? undefined : `need ≥${needHandle} (transition ${e.transition ? e.transition.duration : 0}); have ${res.handleIn ?? 0}/${res.handleOut ?? 0}`,
+      );
+    }
+    // Retime preserved (if the event carries a non-100 speed, the resolution must carry it too).
+    if ((e.speed ?? 100) !== 100)
+      add('retime_preserved', res.speed == null || Math.abs(res.speed - e.speed) < 0.5, `event ${e.speed}% vs resolved ${res.speed ?? 'n/a'}`);
+    // Reverse preserved.
+    if (e.reverse) add('reverse_preserved', res.reverse !== false, res.reverse === false ? 'resolved forward' : undefined);
+    // TC-base matched.
+    if (opts.expectTcBase != null && res.tcBase != null)
+      add('tc_base', String(res.tcBase) === String(opts.expectTcBase), `${res.tcBase} vs ${opts.expectTcBase}`);
+    const pass = checks.every((c) => c.pass);
+    rows.push({ index: e.index, source: e.source, track: e.track, pass, checks });
+  }
+  const failed = rows.filter((r) => !r.pass);
+  return { pass: failed.length === 0, eventCount: rows.length, failedCount: failed.length, rows, failed: failed.map((r) => r.source), gate: 'review' };
+}
+
+// ── marker_roundtrip ───────────────────────────────────────────────────
+/**
+ * Round-trip markers/notes with provenance tags. Normalizes a marker set, stamps provenance,
+ * and asserts the set survives encode→decode non-empty (skip-not-fake).
+ * @param {Array<{frame:number, name?:string, note?:string, color?:string, source?:string}>} markers
+ * @param {{provenanceTag?:string}} [opts]
+ */
+export function markerRoundtrip(markers, opts = {}) {
+  const tag = opts.provenanceTag || 'AUTO:marker_roundtrip';
+  const normalized = markers.map((m, i) => ({
+    frame: Number(m.frame),
+    name: m.name || `Marker ${i + 1}`,
+    note: m.note || '',
+    color: m.color || 'Blue',
+    provenance: m.source ? `${tag} ← ${m.source}` : tag,
+  }));
+  // Encode → decode (JSON is the interchange; a real EDL/marker export mirrors this shape).
+  const encoded = JSON.stringify(normalized);
+  const decoded = JSON.parse(encoded);
+  if (markers.length && decoded.length !== markers.length)
+    throw new Error(`marker_roundtrip: ${markers.length} in, ${decoded.length} out — round-trip dropped markers`);
+  const provenanceOk = decoded.every((m) => typeof m.provenance === 'string' && m.provenance.length);
+  if (markers.length && !provenanceOk) throw new Error('marker_roundtrip: a marker lost its provenance tag');
+  return { count: decoded.length, markers: decoded, provenanceOk, roundTrip: 'ok' };
+}