davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/conform-qc/synthetic/generate.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * synthetic/generate.js — build a tiny, fully-synthetic, ANONYMIZED portable
+ * fixture with KNOWN golden answers (spec/harness: P0-synthetic-fixture).
+ *
+ * A real turnover.xml + frames are git-ignored client material, so on a
+ * fresh clone the parser/comparator tests skip. This generator emits a small
+ * crafted XMEML + test-pattern PNGs whose answers we compute by construction, so
+ * the WHOLE suite runs client-free. The output is committed under
+ * __fixtures__/synthetic/ (it contains no client data), and this generator makes
+ * it reproducible. No fabricated "expected" numbers — every golden here is
+ * derived from the same math the Oracle implements, encoded once.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const sharp = require('sharp');
+
+const TPF = 10584000000; // ticks/frame @24
+const SEQ_W = 1920;
+const SEQ_H = 1080;
+const SRC_W = 960; // so seqW/srcW = 2.0 (fit = 200%)
+const SRC_H = 540;
+
+// ── Clip definitions (inputs) + the answers they imply by construction ────────
+// expected_source_start = startoffset + in ; ticks encode in (or 2*in for 50%).
+// expected_scale_corrected = scale * srcW / seqW.
+const CLIPS = [
+  { key: 'normal', start: 0, end: 48, in: 1000, suboff: null, scale: 200, speed: 100,
+    center: { h: 0, v: 0 }, rotation: 0, crop: { left: 0, top: 0, right: 0, bottom: 0 } },
+  { key: 'subclip', start: 48, end: 96, in: 500, suboff: 2000, scale: 200, speed: 100,
+    center: { h: 0, v: 0 }, rotation: 0, crop: { left: 0, top: 0, right: 0, bottom: 0 } },
+  { key: 'slowmo', start: 96, end: 144, in: 3000, suboff: null, scale: 200, speed: 200, slow: true,
+    center: { h: 0, v: 0 }, rotation: 0, crop: { left: 0, top: 0, right: 0, bottom: 0 } },
+  { key: 'reframe', start: 144, end: 192, in: 4000, suboff: null, scale: 250, speed: 100,
+    center: { h: 120, v: -60 }, rotation: 5, crop: { left: 10, top: 4, right: 8, bottom: 2 } },
+];
+
+function ticksFor(clip) {
+  // 50% slow-mo: ticks/tpf = 2*in (the Oracle detects retime here); else ticks/tpf = in.
+  const frames = clip.slow ? clip.in * 2 : clip.in;
+  return frames * TPF;
+}
+
+function expectedSourceStart(clip) {
+  return (clip.suboff || 0) + clip.in;
+}
+
+function expectedScaleCorrected(clip) {
+  return (clip.scale * SRC_W) / SEQ_W;
+}
+
+// ── XMEML emission ────────────────────────────────────────────────────────────
+function fileDef(id, basename, full) {
+  if (!full) return `<file id="${id}"/>`;
+  return `<file id="${id}">
+  <name>${basename}</name>
+  <pathurl>file://localhost/SYNTH/${encodeURIComponent(basename)}</pathurl>
+  <media><video><samplecharacteristics>
+    <width>${SRC_W}</width><height>${SRC_H}</height>
+  </samplecharacteristics></video></media>
+</file>`;
+}
+
+function clipXml(clip, idx) {
+  const fileId = `file-${idx + 1}`;
+  const basename = `SYNTH_${clip.key}.mov`;
+  // Exercise file-id resolution: the 'normal' clip defines file-1 fully; later
+  // clips define their own; we ALSO make 'subclip' reference normal's file by id
+  // only when keys match — here each clip has its own file for clarity, but the
+  // 'reframe' clip references file-1 self-closing to prove resolution.
+  const usesSharedFile = clip.key === 'reframe';
+  const effectiveId = usesSharedFile ? 'file-1' : fileId;
+  const file = usesSharedFile ? fileDef('file-1', 'SYNTH_normal.mov', false) : fileDef(fileId, basename, true);
+  const sub = clip.suboff != null ? `<subclipinfo><startoffset>${clip.suboff}</startoffset></subclipinfo>` : '';
+  const timeRemap = clip.speed !== 100
+    ? `<filter><effect><name>Time Remap</name><effectid>timeremap</effectid>
+        <parameter><parameterid>speed</parameterid><value>${clip.speed}</value></parameter>
+        <parameter><parameterid>variablespeed</parameterid><value>0</value></parameter>
+      </effect></filter>`
+    : '';
+  return `<clipitem id="clipitem-${idx + 1}">
+  <name>${clip.key}</name>
+  <start>${clip.start}</start>
+  <end>${clip.end}</end>
+  <in>${clip.in}</in>
+  <out>${clip.in + (clip.end - clip.start)}</out>
+  <pproTicksIn>${ticksFor(clip)}</pproTicksIn>
+  <pproTicksOut>${ticksFor(clip) + (clip.end - clip.start) * TPF}</pproTicksOut>
+  ${effectiveId === 'file-1' ? file : file}
+  ${sub}
+  <filter><effect><name>Basic Motion</name><effectid>basic</effectid>
+    <parameter><parameterid>scale</parameterid><value>${clip.scale}</value></parameter>
+    <parameter><parameterid>rotation</parameterid><value>${clip.rotation}</value></parameter>
+    <parameter><parameterid>center</parameterid><value><horiz>${clip.center.h}</horiz><vert>${clip.center.v}</vert></value></parameter>
+    <parameter><parameterid>leftcrop</parameterid><value>${clip.crop.left}</value></parameter>
+    <parameter><parameterid>topcrop</parameterid><value>${clip.crop.top}</value></parameter>
+    <parameter><parameterid>rightcrop</parameterid><value>${clip.crop.right}</value></parameter>
+    <parameter><parameterid>bottomcrop</parameterid><value>${clip.crop.bottom}</value></parameter>
+  </effect></filter>
+  ${timeRemap}
+</clipitem>`;
+}
+
+function buildXml() {
+  const clipitems = CLIPS.map(clipXml).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<xmeml version="4">
+<sequence id="seq-synth">
+  <name>SYNTH_REEL</name>
+  <media><video>
+    <format><samplecharacteristics>
+      <rate><timebase>24</timebase><ntsc>FALSE</ntsc></rate>
+      <width>${SEQ_W}</width><height>${SEQ_H}</height>
+    </samplecharacteristics></format>
+    <track>
+${clipitems}
+    </track>
+  </video></media>
+</sequence>
+</xmeml>`;
+}
+
+// ── Frame (PNG) emission ──────────────────────────────────────────────────────
+const FW = 384;
+const FH = 216;
+
+function patternBase(x, y) {
+  // A structured "scene": gradients + edges + sinusoids. 0..1.
+  const g = 0.4 + 0.3 * (x / FW);
+  const s = 0.15 * Math.sin(x * 0.10) * Math.cos(y * 0.08);
+  const block = x > FW * 0.55 && x < FW * 0.8 && y > FH * 0.3 && y < FH * 0.75 ? 0.2 : 0;
+  return Math.max(0, Math.min(1, g + s + block));
+}
+
+function patternOther(x, y) {
+  // A clearly different scene (for the WRONG case).
+  const r = Math.hypot(x - FW * 0.5, y - FH * 0.5) / (FW * 0.5);
+  return Math.max(0, Math.min(1, 0.7 - 0.5 * r + 0.2 * Math.sin(y * 0.2)));
+}
+
+function withBurnIn(val, x, y) {
+  // Simulated burn-ins: bright top-center TC box + bottom strip.
+  const fx = x / FW;
+  const fy = y / FH;
+  if (fy >= 0.92) return 0.95;
+  if (fy >= 0.07 && fy <= 0.17 && fx >= 0.36 && fx <= 0.64) return 0.95;
+  return val;
+}
+
+function renderRaw(fn) {
+  const buf = Buffer.alloc(FW * FH);
+  for (let y = 0; y < FH; y++) {
+    for (let x = 0; x < FW; x++) {
+      buf[y * FW + x] = Math.round(fn(x, y) * 255);
+    }
+  }
+  return buf;
+}
+
+async function writePng(buf, file) {
+  await sharp(buf, { raw: { width: FW, height: FH, channels: 1 } }).png().toFile(file);
+}
+
+async function generateAll(outDir) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const framesDir = path.join(outDir, 'frames');
+  fs.mkdirSync(framesDir, { recursive: true });
+
+  // XML + oracle golden
+  fs.writeFileSync(path.join(outDir, 'turnover.synth.xml'), buildXml());
+  const oracle = {
+    sequence: { name: 'SYNTH_REEL', width: SEQ_W, height: SEQ_H, fps: 24 },
+    ticksPerFrame: TPF,
+    clipCount: CLIPS.length,
+    clips: CLIPS.map((c) => ({
+      key: c.key,
+      seqstart: c.start,
+      xml_in: c.in,
+      is_subclip: c.suboff != null,
+      subclip_startoffset: c.suboff || 0,
+      pproTicksIn: ticksFor(c),
+      scale_premiere: c.scale,
+      speed: c.speed,
+      center: c.center,
+      rotation: c.rotation,
+      crop: c.crop,
+      srcW: SRC_W,
+      srcH: SRC_H,
+      expected_source_start: expectedSourceStart(c),
+      expected_sample_frame: (c.suboff || 0) + (c.slow ? c.in * 2 : c.in),
+      expected_scale_corrected: expectedScaleCorrected(c),
+    })),
+  };
+  fs.writeFileSync(path.join(outDir, 'golden_oracle.synth.json'), JSON.stringify(oracle, null, 1));
+
+  // Frames: match (same), dark-trap (ref darkened), wrong (different)
+  const base = renderRaw(patternBase);
+  const baseBurn = renderRaw((x, y) => withBurnIn(patternBase(x, y), x, y));
+  const baseDarkBurn = renderRaw((x, y) => withBurnIn(patternBase(x, y) * 0.22, x, y));
+  const other = renderRaw(patternOther);
+  const otherBurn = renderRaw((x, y) => withBurnIn(patternOther(x, y), x, y));
+
+  await writePng(baseBurn, path.join(framesDir, 'match__reference.png'));
+  await writePng(base, path.join(framesDir, 'match__derived.png'));
+  await writePng(baseDarkBurn, path.join(framesDir, 'darktrap__reference.png'));
+  await writePng(base, path.join(framesDir, 'darktrap__derived.png'));
+  await writePng(otherBurn, path.join(framesDir, 'wrong__reference.png'));
+  await writePng(base, path.join(framesDir, 'wrong__derived.png'));
+
+  const compare = {
+    note: 'Synthetic, client-free. darktrap reference is darkened 0.22x — brightness-robust metric must still MATCH.',
+    cases: [
+      { label: 'match', expected_verdict: 'MATCH', reference: 'frames/match__reference.png', derived: 'frames/match__derived.png' },
+      { label: 'darktrap', expected_verdict: 'MATCH', reference: 'frames/darktrap__reference.png', derived: 'frames/darktrap__derived.png' },
+      { label: 'wrong', expected_verdict: 'WRONG', reference: 'frames/wrong__reference.png', derived: 'frames/wrong__derived.png' },
+    ],
+  };
+  fs.writeFileSync(path.join(outDir, 'golden_compare.synth.json'), JSON.stringify(compare, null, 1));
+
+  return { outDir, clips: CLIPS.length };
+}
+
+module.exports = { generateAll, buildXml, CLIPS, TPF, SEQ_W, SRC_W };
+
+if (require.main === module) {
+  const out = path.join(__dirname, '..', '__fixtures__', 'synthetic');
+  generateAll(out).then((r) => {
+    // eslint-disable-next-line no-console
+    console.log(`synthetic fixture written to ${r.outDir} (${r.clips} clips + frames)`);
+  });
+}

package/resolve-advanced/vendor/conform-qc/test/advisory.test.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Advisory escalation policy tests — client-free. These encode the SAMPLE
+ * non-negotiable: vision may raise a flag but can NEVER override the math.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { shouldConsultVision, reconcile, actionFor } = require('../compare/advisory');
+const { FakeVisionValidator } = require('../adapters/vision-validator');
+
+test('advisory: cost gate — borderline / alignment / propose-only are consulted; clear MATCH is not', () => {
+  // Clear MATCH (above band): do NOT consult.
+  assert.equal(shouldConsultVision({ verdict: 'MATCH', structure: 0.99 }, { mode: 'content-identity' }), false);
+  // Clear WRONG (below band): do NOT consult.
+  assert.equal(shouldConsultVision({ verdict: 'WRONG', structure: 0.40 }, { mode: 'content-identity' }), false);
+  // Borderline: consult.
+  assert.equal(shouldConsultVision({ verdict: 'MATCH', structure: 0.90 }, { mode: 'content-identity' }), true);
+  // Alignment mode: always consult (metric doesn't apply).
+  assert.equal(shouldConsultVision({ verdict: 'MATCH', structure: 0.99 }, { mode: 'alignment' }), true);
+  // Stubborn propose-only repair: consult.
+  assert.equal(shouldConsultVision({ verdict: 'WRONG', structure: 0.40 }, { proposeOnlyRepair: true }), true);
+});
+
+test('advisory: corroboration does NOT change the deterministic verdict or force auto-apply', () => {
+  const det = { verdict: 'MATCH', structure: 0.90 };
+  const adv = { verdict: 'MATCH', confidence: 0.8, advisory: true, provenance: { model: 'fake' } };
+  const out = reconcile(det, adv);
+  assert.equal(out.verdict, 'MATCH');
+  assert.equal(out.finalAction, 'auto-apply-eligible'); // eligibility from the metric, not from vision
+  assert.equal(out.reason, 'corroborated');
+  assert.equal(out.escalated, false);
+});
+
+test('advisory: vision can NEVER flip a deterministic WRONG to MATCH — it escalates to human', () => {
+  const det = { verdict: 'WRONG', structure: 0.40 };
+  const adv = { verdict: 'MATCH', confidence: 0.9, advisory: true, provenance: { model: 'fake' } };
+  const out = reconcile(det, adv);
+  assert.notEqual(out.verdict, 'MATCH', 'must NOT become MATCH on vision say-so');
+  assert.equal(out.verdict, 'REVIEW');
+  assert.equal(out.finalAction, 'human-review');
+  assert.equal(out.escalated, true);
+});
+
+test('advisory: vision RAISES a flag on a deterministic MATCH it disputes → human REVIEW', () => {
+  const det = { verdict: 'MATCH', structure: 0.91 };
+  const adv = { verdict: 'WRONG', confidence: 0.7, advisory: true, provenance: { model: 'fake' } };
+  const out = reconcile(det, adv);
+  assert.equal(out.verdict, 'REVIEW');
+  assert.equal(out.escalated, true);
+});
+
+test('advisory: with no validator injected, the deterministic verdict stands unchanged', () => {
+  const det = { verdict: 'MATCH', structure: 0.99 };
+  const out = reconcile(det, null);
+  assert.equal(out.verdict, 'MATCH');
+  assert.equal(out.advisory, null);
+  assert.equal(out.finalAction, 'auto-apply-eligible');
+});
+
+test('advisory: reconcile rejects a non-advisory result (cannot smuggle authority)', () => {
+  const det = { verdict: 'MATCH', structure: 0.90 };
+  assert.throws(() => reconcile(det, { verdict: 'WRONG', advisory: false }), /must be marked advisory/);
+});
+
+test('advisory: end-to-end with FakeVisionValidator on a borderline dark-grade-style cut', async () => {
+  const det = { verdict: 'MATCH', structure: 0.90 }; // borderline
+  const fake = new FakeVisionValidator({ dark_grade: { verdict: 'MATCH', confidence: 0.85, rationale: 'same scene' } });
+  // Only consult because it's borderline.
+  assert.equal(shouldConsultVision(det, { mode: 'content-identity' }), true);
+  const adv = await fake.validate({}, {}, { label: 'dark_grade' });
+  const out = reconcile(det, adv);
+  assert.equal(out.verdict, 'MATCH');
+  assert.equal(out.reason, 'corroborated');
+  assert.equal(fake.calls.length, 1);
+});
+
+test('advisory: actionFor maps verdicts to the §15 policy', () => {
+  assert.equal(actionFor('MATCH'), 'auto-apply-eligible');
+  assert.equal(actionFor('OFFSET'), 'propose');
+  assert.equal(actionFor('WRONG'), 'flag-v2');
+  assert.equal(actionFor('REVIEW'), 'human-review');
+});

package/resolve-advanced/vendor/conform-qc/test/cli.test.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/** CLI entry tests — runCli programmatically + a real subprocess invocation. */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { runCli } = require('../cli');
+
+const SYNTH_MODEL = path.join(__dirname, '..', '__fixtures__', 'synthetic', 'golden_oracle.synth.json');
+const CLI = path.join(__dirname, '..', 'cli.js');
+
+test('cli: verify on the synthetic model returns a Tier-C report (exit 0)', async () => {
+  const r = await runCli(['verify', SYNTH_MODEL]);
+  assert.equal(r.code, 0);
+  assert.equal(r.report.summary.mathVerified, r.report.perCut.length);
+  assert.match(r.output, /conform-qc verify/);
+  assert.match(r.output, /math-verified=/);
+});
+
+test('cli: bad usage and unreadable model exit non-zero', async () => {
+  assert.equal((await runCli([])).code, 2);
+  assert.equal((await runCli(['verify', '/no/such/model.json'])).code, 1);
+});
+
+test('cli: --json emits the per-cut report', async () => {
+  const r = await runCli(['verify', SYNTH_MODEL, '--json']);
+  const parsed = JSON.parse(r.output);
+  assert.ok(parsed.summary && Array.isArray(parsed.perCut));
+  assert.equal(parsed.perCut.length, 4);
+});
+
+test('cli: runs as a real subprocess and exits 0', () => {
+  const out = execFileSync('node', [CLI, 'verify', SYNTH_MODEL], { encoding: 'utf8' });
+  assert.match(out, /conform-qc verify/);
+  assert.match(out, /cuts: 4/);
+});

package/resolve-advanced/vendor/conform-qc/test/compare.test.js

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * Comparator tests — verified END-TO-END against the 4 committed golden verdicts
+ * (golden_compare.json) and their reference/derived PNG pairs.
+ *
+ * The PNG pairs live under frames/ which is git-ignored raw material, so the
+ * frame-dependent tests SKIP-IF-ABSENT. golden_compare.json itself is committed.
+ * The dark_grade_match case is THE TRAP: raw PSNR ~9 but it MUST classify MATCH.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const pkg = require('../index');
+const compare = require('../compare');
+
+const DIR = pkg.reelFixtureDir();
+const FRAMES = path.join(DIR, 'frames');
+const HAVE_FRAMES = fs.existsSync(FRAMES) && fs.readdirSync(FRAMES).some((f) => f.endsWith('.png'));
+const SKIP = HAVE_FRAMES ? false : 'frames/ absent (git-ignored raw material) — skipping';
+
+const COMPARE = JSON.parse(fs.readFileSync(path.join(DIR, 'golden_compare.json'), 'utf8'));
+
+test('comparator: alignment mode is a distinct entry point (stub), content-identity is default', async () => {
+  // The alignment stub throws clearly (full impl is P4.5).
+  assert.throws(() => compare.alignmentVerify(), /alignment verification mode not implemented/);
+  // compareFrames routes by mode without needing to decode for the stub path.
+  await assert.rejects(
+    () => compare.compareFrames('ref', 'der', { mode: 'alignment' }),
+    /alignment verification mode not implemented/,
+  );
+  // An unknown mode errors clearly.
+  await assert.rejects(() => compare.compareFrames('ref', 'der', { mode: 'bogus' }), /unknown mode "bogus"/);
+  // eslint-disable-next-line no-console
+  console.log('[compare] alignment mode: distinct stub entry point, content-identity is default');
+});
+
+test('comparator: cross-correlation reports a correctable OFFSET, not WRONG (synthetic, client-free)', () => {
+  // A structured pattern with high-frequency detail so a shift decorrelates at
+  // zero offset but realigns at the true shift. Deterministic (no RNG).
+  const W = 96;
+  const H = 64;
+  const a = new Float64Array(W * H);
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      a[y * W + x] = 0.5 + 0.25 * Math.sin(x * 0.7) * Math.cos(y * 0.5) + 0.2 * Math.sin((x + y) * 1.3);
+    }
+  }
+  // Displace content by (sx,sy); the correction offset is the inverse (-sx,-sy).
+  const sx = 5;
+  const sy = -3;
+  const b = new Float64Array(W * H);
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const srcx = x - sx;
+      const srcy = y - sy;
+      b[y * W + x] = srcx >= 0 && srcx < W && srcy >= 0 && srcy < H ? a[srcy * W + srcx] : 0;
+    }
+  }
+  const out = compare.classify(a, b, { width: W, height: H });
+  assert.equal(out.verdict, 'OFFSET', `expected OFFSET, got ${out.verdict} (zero-shift structure ${out.structure?.toFixed(3)})`);
+  assert.equal(out.offset.dx, -sx, `dx ${out.offset.dx} should be ${-sx}`);
+  assert.equal(out.offset.dy, -sy, `dy ${out.offset.dy} should be ${-sy}`);
+  // eslint-disable-next-line no-console
+  console.log(`[compare] cross-corr offset: applied (${sx},${sy}) -> correction (${out.offset.dx},${out.offset.dy}), verdict OFFSET`);
+});
+
+test('comparator: classifies all 4 golden verdicts (dark-grade trap = MATCH)', { skip: SKIP }, async () => {
+  const results = [];
+  for (const c of COMPARE.cases) {
+    const refPath = path.join(DIR, c.reference);
+    const derPath = path.join(DIR, c.derived);
+    const out = await compare.compareFrames(refPath, derPath);
+    results.push({ label: c.label, got: out.verdict, want: c.expected_verdict, structure: out.structure });
+    assert.equal(
+      out.verdict,
+      c.expected_verdict,
+      `${c.label}: got ${out.verdict} (structure ${out.structure?.toFixed(4)}), want ${c.expected_verdict}`,
+    );
+  }
+  // Explicit trap assertion — the dark grade must MATCH despite the brightness gap.
+  const dark = results.find((r) => r.label === 'dark_grade_match');
+  assert.equal(dark.got, 'MATCH', 'dark_grade_match MUST classify MATCH (brightness trap)');
+  // eslint-disable-next-line no-console
+  console.log('[compare] 4/4 golden verdicts: ' + results.map((r) => `${r.label}=${r.got}`).join(', '));
+});
+
+test('comparator: brightness-robust — structure MATCHes the dark grade where full SSIM fails', { skip: SKIP }, async () => {
+  const c = COMPARE.cases.find((x) => x.label === 'dark_grade_match');
+  const size = compare.DEFAULT_SIZE;
+  const ref = await compare.decodeGrayNormalized(path.join(DIR, c.reference), size);
+  const der = await compare.decodeGrayNormalized(path.join(DIR, c.derived), size);
+  const mask = compare.buildBurnInMask(size.width, size.height);
+  const structure = compare.ssimStructure(ref.data, der.data, mask);
+  const full = compare.ssimFull(ref.data, der.data, mask);
+  // The brightness-robust structure score accepts the dark grade...
+  assert.ok(structure >= 0.9, `structure ${structure.toFixed(4)} should be >= 0.90`);
+  // ...while naive full SSIM (with the luminance term) FALSE-REJECTS it — the trap.
+  assert.ok(full < 0.9, `full SSIM ${full.toFixed(4)} should be < 0.90 (proves the trap)`);
+  // eslint-disable-next-line no-console
+  console.log(`[compare] brightness trap: structure=${structure.toFixed(3)} (MATCH) vs full SSIM=${full.toFixed(3)} (would false-flag)`);
+});
+
+test('comparator: burn-in masking is applied and configurable, and raises the match score', { skip: SKIP }, async () => {
+  const c = COMPARE.cases.find((x) => x.label === 'clean_match_hermes');
+  const size = compare.DEFAULT_SIZE;
+  const ref = await compare.decodeGrayNormalized(path.join(DIR, c.reference), size);
+  const der = await compare.decodeGrayNormalized(path.join(DIR, c.derived), size);
+  const noMask = new Uint8Array(size.width * size.height);
+  const burnMask = compare.buildBurnInMask(size.width, size.height);
+  // The default mask covers some pixels (the burn-in regions exist).
+  let masked = 0;
+  for (let i = 0; i < burnMask.length; i++) masked += burnMask[i];
+  assert.ok(masked > 0, 'default burn-in mask must cover the TC/filename regions');
+  const sMasked = compare.ssimStructure(ref.data, der.data, burnMask);
+  const sUnmasked = compare.ssimStructure(ref.data, der.data, noMask);
+  // Masking the burn-in (present in ref, absent in derived) improves the score.
+  assert.ok(sMasked > sUnmasked, `masked ${sMasked.toFixed(4)} should beat unmasked ${sUnmasked.toFixed(4)}`);
+  // Regions are configurable: a different region set changes the masked count.
+  const custom = compare.buildBurnInMask(size.width, size.height, [{ x0: 0, y0: 0, x1: 1, y1: 0.1 }]);
+  let customCount = 0;
+  for (let i = 0; i < custom.length; i++) customCount += custom[i];
+  assert.notEqual(customCount, masked, 'custom regions should change the mask coverage');
+  // eslint-disable-next-line no-console
+  console.log(`[compare] burn-in mask: ${masked} px masked; masked struct ${sMasked.toFixed(4)} > unmasked ${sUnmasked.toFixed(4)}`);
+});
+
+test('comparator: SSIM>=0.90 / PSNR>=25 thresholds separate clean from wrong', { skip: SKIP }, async () => {
+  const size = compare.DEFAULT_SIZE;
+  const mask = compare.buildBurnInMask(size.width, size.height);
+  const t = compare.DEFAULT_THRESHOLDS;
+  assert.equal(t.structure, 0.9);
+  assert.equal(t.psnrNorm, 25);
+  const score = async (label) => {
+    const c = COMPARE.cases.find((x) => x.label === label);
+    const ref = await compare.decodeGrayNormalized(path.join(DIR, c.reference), size);
+    const der = await compare.decodeGrayNormalized(path.join(DIR, c.derived), size);
+    return {
+      structure: compare.ssimStructure(ref.data, der.data, mask),
+      psnr: compare.psnrNormalized(ref.data, der.data, mask),
+    };
+  };
+  const clean = await score('clean_match_hermes');
+  const wrong = await score('genuine_wrong');
+  assert.ok(clean.structure >= t.structure && clean.psnr >= t.psnrNorm, `clean above thresholds: ${JSON.stringify(clean)}`);
+  assert.ok(wrong.structure < t.structure && wrong.psnr < t.psnrNorm, `wrong below thresholds: ${JSON.stringify(wrong)}`);
+  // eslint-disable-next-line no-console
+  console.log(`[compare] thresholds: clean struct ${clean.structure.toFixed(3)}/psnr ${clean.psnr.toFixed(1)} vs wrong ${wrong.structure.toFixed(3)}/${wrong.psnr.toFixed(1)}`);
+});

package/resolve-advanced/vendor/conform-qc/test/conform-diff.test.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { diffConform } = require('../ops/conform-diff');
+
+function truthClip(seqstart, zoom, sourceFrame, dur, { retimed = false, conf = 'high', mismatch = false } = {}) {
+  return {
+    seqstart, seqend: seqstart + dur,
+    timing: { duration: dur }, sourceFrame,
+    source: { basename: 'x.mov' },
+    retime: { retimed },
+    transform: { zoomX: zoom, zoomY: zoom },
+    flags: { scaleConfidence: conf, aspectMismatch: mismatch },
+  };
+}
+
+const TRUTH = {
+  clips: [
+    truthClip(0, 1.06282, 100, 96),
+    truthClip(96, 1.11856, 200, 48),
+    truthClip(200, 1.06283, 300, 60, { conf: 'low', mismatch: true }), // LoCon
+    truthClip(300, 1.0, 400, 24), // generator-ish, dropped on import
+  ],
+  transitions: [{}, {}],
+};
+
+test('diffConform: clean clips pass; LoCon scaling mismatch + dropped clip surface', () => {
+  const db = {
+    startOffset: 86400,
+    clips: [
+      { start: 86400, duration: 96, mediaStart: 100, name: 'x.mov', zoomX: 1.06282, retimePresent: false },
+      { start: 86496, duration: 48, mediaStart: 200, name: 'x.mov', zoomX: 1.11856, retimePresent: false },
+      { start: 86600, duration: 60, mediaStart: 300, name: 'x.mov', zoomX: 1.26671, retimePresent: false }, // wrong scale in DB
+      // seq300 clip absent (dropped on import)
+    ],
+    transitions: [{}, {}],
+  };
+  const r = diffConform(TRUTH, db);
+  assert.equal(r.offset, 86400);
+  assert.equal(r.summary.matched, 3);
+  assert.equal(r.summary.clean, 2);
+  assert.equal(r.summary.withIssues, 1);
+  assert.equal(r.summary.missing, 1); // the seq300 clip
+  assert.equal(r.summary.byAttr.scaling, 1);
+  const loconIssue = r.issues[0].issues.find((i) => i.attr === 'scaling');
+  assert.equal(loconIssue.confidence, 'low');
+  assert.equal(loconIssue.aspectMismatch, true);
+  assert.equal(loconIssue.db, 1.26671);
+  assert.equal(r.summary.transitions.match, true);
+});
+
+test('diffConform: catches dropped retime + extra DB clip + transition count mismatch', () => {
+  const db = {
+    startOffset: 0,
+    clips: [
+      { start: 0, duration: 96, mediaStart: 100, name: 'x.mov', zoomX: 1.06282, retimePresent: false },
+      { start: 96, duration: 48, mediaStart: 200, name: 'x.mov', zoomX: 1.11856, retimePresent: false },
+      { start: 200, duration: 60, mediaStart: 300, name: 'x.mov', zoomX: 1.06283, retimePresent: false },
+      { start: 999, duration: 10, mediaStart: 5, name: 'extra.mov', zoomX: 1, retimePresent: false }, // extra
+    ],
+    transitions: [{}], // only 1 vs truth 2
+  };
+  const t2 = { ...TRUTH, clips: [truthClip(0, 1.06282, 100, 96), truthClip(96, 1.11856, 200, 48, { retimed: true }), truthClip(200, 1.06283, 300, 60, { conf: 'low', mismatch: true })] };
+  const r = diffConform(t2, db);
+  assert.equal(r.summary.byAttr.retime, 1); // clip2 truth retimed but DB has none
+  assert.equal(r.summary.extra, 1);
+  assert.equal(r.summary.transitions.match, false);
+});

package/resolve-advanced/vendor/conform-qc/test/emulate.test.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { emulateClip, fitFactor, MODE } = require('../oracle/emulate');
+
+const TPF = 254016000000 / 24;
+const CTX = { ticksPerFrame: TPF, seqW: 3600, seqH: 2160, mode: MODE.FIT };
+// an un-retimed clip at scale S with proxy dims; ticks consistent with in
+const clip = (S, pw, ph, inF = 100) => ({
+  seqstart: 0, seqend: 96, xml_in: inF, pproTicksIn: inF * TPF, is_subclip: false,
+  scale_premiere: S, srcW: pw, srcH: ph, source_basename: 'x.mov', speed: 100,
+});
+const HR_1568 = { ok: true, width: 4096, height: 2612, codec: 'prores', bitDepth: 12 };
+
+test('emulate: same-aspect clip -> proxy-aspect zoom 1.06282, high confidence', () => {
+  const t = emulateClip(clip(175.781, 2048, 1306), CTX, HR_1568);
+  assert.equal(t.transform.zoomX, 1.06282); // 175.781*1306/2160
+  assert.equal(t.transform.basis, 'proxy');
+  assert.equal(t.flags.aspectMismatch, false);
+  assert.equal(t.flags.scaleConfidence, 'high');
+  assert.equal(t.sourceFrame, 100);
+});
+
+test('emulate: proxy/highres ASPECT MISMATCH keeps the proxy zoom but flags for reference review (LoCon)', () => {
+  const t = emulateClip(clip(253.343, 1421, 1080), CTX, HR_1568);
+  assert.equal(t.flags.aspectMismatch, true);
+  assert.equal(t.flags.scaleConfidence, 'review');
+  // the proxy is what the editor framed + what the reference renders: 253.343*1080/2160
+  assert.ok(Math.abs(t.transform.zoomX - 1.26671) < 0.001, `got ${t.transform.zoomX}`);
+});
+
+test('emulate: zoom is the proxy-aspect correction with or without highres analysis', () => {
+  const withHr = emulateClip(clip(180, 2048, 1306), CTX, HR_1568).transform.zoomX;
+  const noHr = emulateClip(clip(180, 2048, 1306), CTX, null).transform.zoomX;
+  assert.equal(withHr, 1.08833); // 180*1306/2160
+  assert.equal(noHr, 1.08833);
+});
+
+test('emulate: without highres analysis, basis is proxy and confidence stays high', () => {
+  const t = emulateClip(clip(175.781, 2048, 1306), CTX, null);
+  assert.equal(t.transform.basis, 'proxy');
+  assert.equal(t.flags.scaleConfidence, 'high');
+  assert.equal(t.transform.zoomX, 1.06282);
+});
+
+test('fitFactor: fit vs fill pick the binding dimension', () => {
+  // narrower-than-timeline source: fit binds on height, fill binds on width
+  assert.ok(fitFactor(4096, 2612, 3600, 2160, MODE.FIT) < fitFactor(4096, 2612, 3600, 2160, MODE.FILL));
+});

package/resolve-advanced/vendor/conform-qc/test/frame-sampler.test.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/** FrameSampler interface tests — client-free. */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { FrameSampler, FakeFrameSampler, isFrameSampler } = require('../adapters/frame-sampler');
+
+test('FrameSampler: base interface throws until implemented', async () => {
+  const base = new FrameSampler();
+  assert.equal(isFrameSampler(base), true);
+  await assert.rejects(() => base.sample('media', 0, { width: 4, height: 4 }), /must be implemented/);
+});
+
+test('FrameSampler: fake conforms — right dims, deterministic, content varies by frame', async () => {
+  const s = new FakeFrameSampler();
+  assert.equal(isFrameSampler(s), true);
+  const size = { width: 8, height: 6 };
+  const a = await s.sample('clipA.mov', 100, size);
+  assert.equal(a.width, 8);
+  assert.equal(a.height, 6);
+  assert.equal(a.data.length, 48);
+  const aAgain = await s.sample('clipA.mov', 100, size);
+  assert.deepEqual(Array.from(a.data), Array.from(aAgain.data), 'same request => same pixels');
+  const b = await s.sample('clipA.mov', 101, size);
+  assert.notDeepEqual(Array.from(a.data), Array.from(b.data), 'different frame => different pixels');
+  // A non-conforming object is rejected by the duck-typed check.
+  assert.equal(isFrameSampler({}), false);
+});