davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/conform-qc/repair/media-index.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * repair/media-index.js — a media index for re-resolving sources (spec §3.2 /
+ * §9 true-source search). Pure: built from a list of media descriptors; no IO.
+ *
+ * Resolves by exact basename, by reel+TC, and by naming-variant (proxy↔original,
+ * e.g. a "…4K-2K…" proxy → its "…4K…" scan) — the proxy/scan naming relationship.
+ */
+
+function normTokens(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/\.[a-z0-9]+$/, '')
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2);
+}
+
+/**
+ * A normalized basename key for proxy↔original EXACT matching, before the fuzzy
+ * IDF tier. Unlike normTokens this PRESERVES single-char discriminators (a take
+ * marker like "#1" vs "#2" — different rescans of the same shot — must not
+ * collapse), and only erases the deterministic proxy/duplicate decorations:
+ *   - the extension (proxy .mp4 ↔ original .mov),
+ *   - the proxy resolution marker "4k-2k" → "4k",
+ *   - a trailing "_<n>" Premiere duplicate-import suffix ("…0703a_1" → "…0703a").
+ * Whitespace is collapsed; the take marker (#2) and roll/clip ids survive.
+ */
+function normalizedKey(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/\.[a-z0-9]+$/, '')
+    .replace(/4k-2k/g, '4k')
+    .replace(/_\d+$/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Proxy-ish tokens that shouldn't block a proxy↔original match. */
+const VARIANT_NOISE = new Set(['2k', 'proxy', 'prores', 'h264', 'dnx']);
+
+class MediaIndex {
+  /** @param {object[]} media  [{ path, basename, reel?, startTc?, role? }] */
+  constructor(media = []) {
+    this.media = media.map((m) => ({ ...m, _tokens: new Set(normTokens(m.basename)) }));
+    this.byBasenameMap = new Map(this.media.map((m) => [m.basename, m.path]));
+    // Normalized-key map for the proxy↔original exact tier. A key with >1
+    // candidate is AMBIGUOUS — we store the list and refuse to guess (byNormalized
+    // returns null), letting the caller fall to IDF or flag it.
+    this.byNormalizedMap = new Map();
+    for (const m of this.media) {
+      const k = normalizedKey(m.basename);
+      if (!this.byNormalizedMap.has(k)) this.byNormalizedMap.set(k, []);
+      this.byNormalizedMap.get(k).push(m.path);
+    }
+    // Document frequency per token, for IDF weighting in findTrueSource: generic
+    // tokens (camera/format/resolution words common to nearly every name) weigh
+    // ~nothing; distinctive tokens (the roll/date) carry the match. This is what
+    // stops a generic-only overlap (e.g. a TEST roll vs a production scan) from
+    // scoring high on shared boilerplate.
+    this.N = this.media.length;
+    this.df = new Map();
+    for (const m of this.media) for (const t of m._tokens) this.df.set(t, (this.df.get(t) || 0) + 1);
+  }
+
+  /** Inverse document frequency (smoothed): rare/distinctive tokens weigh more. */
+  idf(token) {
+    return Math.log((this.N + 1) / ((this.df.get(token) || 0) + 1)) + 1;
+  }
+
+  byBasename(basename) {
+    return this.byBasenameMap.get(basename) || null;
+  }
+
+  /**
+   * Exact match on the normalized key (proxy↔original, take-marker preserving).
+   * Returns the path only when EXACTLY one candidate normalizes to the same key;
+   * null when none or when ambiguous (caller falls back to IDF / flags it).
+   */
+  byNormalized(basename) {
+    const hits = this.byNormalizedMap.get(normalizedKey(basename));
+    return hits && hits.length === 1 ? hits[0] : null;
+  }
+
+  byReelTc(reel, startTc) {
+    const m = this.media.find((x) => x.reel === reel && (startTc == null || x.startTc === startTc));
+    return m ? m.path : null;
+  }
+
+  /**
+   * Find the best true-source match for a name (OCR'd or proxy basename), using
+   * token overlap with proxy-noise tolerance. Returns { path, score } or null.
+   */
+  findTrueSource(name, opts = {}) {
+    const want = [...new Set(normTokens(name))].filter((t) => !VARIANT_NOISE.has(t));
+    if (!want.length) return null;
+    // IDF-weighted token overlap (§10.5): distinctive roll/date tokens carry the
+    // score; boilerplate (camera/format/resolution words in nearly every name)
+    // weighs ~nothing. This is what stops a TEST roll from false-matching a
+    // production scan on shared boilerplate alone: they share only generic tokens,
+    // so the score stays well under threshold.
+    //
+    // Origin separation (test vs production, exclude the Tests tree) is the
+    // CALLER's job: it's done by index composition — a finishing relink builds the
+    // index from the finishing trees only — not by a name heuristic here, because
+    // not every test source carries a "test" token (some test/dev rolls are named
+    // only by look). opts.excludePathContains lets a caller drop trees inline if it
+    // prefers.
+    const excludePathContains = opts.excludePathContains || [];
+    const totalIdf = want.reduce((s, t) => s + this.idf(t), 0);
+    let best = null;
+    for (const m of this.media) {
+      if (excludePathContains.length && excludePathContains.some((p) => (m.path || '').includes(p))) continue;
+      // A match must share at least one DISCRIMINATING token — one not present in
+      // every candidate (df < N). Boilerplate alone (camera/format/resolution words
+      // shared by the whole index) can never carry a match, so a TEST roll cannot
+      // resolve to a production scan on boilerplate even in a small index. (Skipped
+      // for a single-candidate index, where df==N for everything by definition.)
+      let matchedIdf = 0;
+      let discriminating = this.N <= 1;
+      for (const t of want) {
+        if (!m._tokens.has(t)) continue;
+        matchedIdf += this.idf(t);
+        if ((this.df.get(t) || 0) < this.N) discriminating = true;
+      }
+      if (!discriminating) continue;
+      const score = totalIdf ? matchedIdf / totalIdf : 0;
+      if (!best || score > best.score) best = { path: m.path, basename: m.basename, score };
+    }
+    const min = opts.minScore != null ? opts.minScore : 0.6;
+    return best && best.score >= min ? best : null;
+  }
+}
+
+module.exports = { MediaIndex, normTokens, normalizedKey };

package/resolve-advanced/vendor/conform-qc/repair/strategies.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * repair/strategies.js — the §9 failure-mode catalog as individual strategies.
+ *
+ * Each strategy is pure: { id, klass, deterministic, detect(cut,ctx)->bool,
+ * propose(cut,ctx)->{ fix, diagnosis, scope?, confidence? } }. `deterministic`
+ * strategies are auto-apply-eligible (subject to re-verify + the §15 gate);
+ * the rest are propose-only (human approves).
+ *
+ * `cut` carries the captured geometry + Oracle outputs; `ctx` carries
+ * { ticksPerFrame, sequenceWidth, mediaIndex? }.
+ */
+
+const TPF_24 = 10584000000;
+
+/** Scale double-count (§9): Premiere scale bakes in seqW/srcW; normalize per source width. */
+const scaleDoubleCount = {
+  id: 'normalize-scale-per-source-width',
+  klass: 'scale-double-count',
+  deterministic: true,
+  detect(cut, ctx) {
+    if (cut.scale_premiere == null || !cut.srcW || !ctx.sequenceWidth) return false;
+    // Signature: the raw scale is ~ the seqW/srcW fit factor (i.e. not yet normalized to ~100).
+    const fit = (ctx.sequenceWidth / cut.srcW) * 100;
+    return Math.abs(cut.scale_premiere - fit) > 0.5 || cut.scale_premiere > 110 || cut.scale_premiere < 90;
+  },
+  propose(cut, ctx) {
+    const corrected = (cut.scale_premiere * cut.srcW) / ctx.sequenceWidth;
+    return { fix: { scale: corrected }, diagnosis: `scale ${cut.scale_premiere} normalized per source width -> ${corrected.toFixed(3)}`, confidence: 1 };
+  },
+};
+
+/** Subclip offset (§9): source = startoffset + in; never rewrite <in>. */
+const subclipOffset = {
+  id: 'add-subclip-startoffset',
+  klass: 'subclip-offset',
+  deterministic: true,
+  detect(cut) {
+    return !!cut.is_subclip;
+  },
+  propose(cut) {
+    const sourceFrame = (cut.subclip_startoffset || 0) + cut.xml_in;
+    return { fix: { sourceFrame }, diagnosis: `subclip: source = startoffset ${cut.subclip_startoffset} + in ${cut.xml_in} = ${sourceFrame} (<in> unchanged)`, confidence: 1 };
+  },
+};
+
+/** Slow-mo / ticks != in (§9): derive the sample frame from ticks. */
+const ticksRetime = {
+  id: 'derive-sample-from-ticks',
+  klass: 'ticks-retime',
+  deterministic: true,
+  detect(cut, ctx) {
+    if (cut.pproTicksIn == null || cut.xml_in == null) return false;
+    const tpf = ctx.ticksPerFrame || TPF_24;
+    return Math.round(cut.pproTicksIn / tpf) !== cut.xml_in;
+  },
+  propose(cut, ctx) {
+    const tpf = ctx.ticksPerFrame || TPF_24;
+    const offset = cut.is_subclip ? cut.subclip_startoffset || 0 : 0;
+    const sampleFrame = offset + Math.round(cut.pproTicksIn / tpf);
+    return { fix: { sampleFrame }, diagnosis: `retime: sample from ticks = ${sampleFrame} (readback stays <in> ${cut.xml_in})`, confidence: 1 };
+  },
+};
+
+/** Stale relink path (§9): path not found; re-resolve by exact basename via the media index. */
+const staleRelink = {
+  id: 'relink-by-exact-basename',
+  klass: 'stale-relink',
+  deterministic: true,
+  detect(cut, ctx) {
+    return !!cut.pathMissing && !!ctx.mediaIndex && !!cut.source_basename;
+  },
+  propose(cut, ctx) {
+    const path = ctx.mediaIndex.byBasename ? ctx.mediaIndex.byBasename(cut.source_basename) : null;
+    if (!path) return { fix: null, diagnosis: `stale relink: no exact-basename match for ${cut.source_basename}`, confidence: 0 };
+    return { fix: { path }, diagnosis: `relinked ${cut.source_basename} -> ${path}`, confidence: 1 };
+  },
+};
+
+/**
+ * Per-file frame offset (§9): the matched frame differs from the derived frame
+ * by a CONSTANT across a file's clips. Detect the constant, apply to that file.
+ * Propose-only (a measured correction, not deterministic from the XML).
+ */
+const perFileOffset = {
+  id: 'apply-per-file-frame-offset',
+  klass: 'per-file-offset',
+  deterministic: false,
+  detect(cut, ctx) {
+    return ctx.fileOffsets != null && cut.fileId != null && ctx.fileOffsets[cut.fileId] != null && ctx.fileOffsets[cut.fileId] !== 0;
+  },
+  propose(cut, ctx) {
+    const k = ctx.fileOffsets[cut.fileId];
+    return { fix: { sourceFrameDelta: k }, scope: cut.fileId, diagnosis: `per-file offset ${k > 0 ? '+' : ''}${k} applied to file ${cut.fileId}`, confidence: 0.8 };
+  },
+};
+
+/** Estimate a constant per-file offset from verified (derived, matched) samples. */
+function estimatePerFileOffset(samples) {
+  if (!samples || !samples.length) return null;
+  const deltas = samples.map((s) => s.matched - s.derived);
+  const counts = {};
+  for (const d of deltas) counts[d] = (counts[d] || 0) + 1;
+  const best = Object.keys(counts).sort((a, b) => counts[b] - counts[a])[0];
+  const k = Number(best);
+  // Only a confident constant offset (majority agree) counts.
+  return counts[best] / deltas.length >= 0.6 ? k : null;
+}
+
+/** Aspect variant (§9): source aspect != reference/sequence aspect → reframe. Propose-only. */
+const aspectVariant = {
+  id: 'reframe-aspect-variant',
+  klass: 'aspect-variant',
+  deterministic: false,
+  detect(cut, ctx) {
+    if (!cut.srcW || !cut.srcH || !ctx.sequenceWidth || !ctx.sequenceHeight) return false;
+    const srcAspect = cut.srcW / cut.srcH;
+    const seqAspect = ctx.sequenceWidth / ctx.sequenceHeight;
+    // Only a LARGE aspect mismatch (e.g. 4:3 vs 16:9) needs a per-clip reframe;
+    // a minor fit difference (e.g. 1.568 source in a 5:3 sequence) is handled by scale.
+    return Math.abs(srcAspect - seqAspect) / seqAspect > 0.1;
+  },
+  propose(cut, ctx) {
+    // Fit-to-fill the differing dimension; carry a reframe scale/center.
+    const fillScale = Math.max(ctx.sequenceWidth / cut.srcW, ctx.sequenceHeight / cut.srcH) / (ctx.sequenceWidth / cut.srcW);
+    return { fix: { reframe: { scale: fillScale, center: { h: 0, v: 0 } } }, diagnosis: `aspect ${cut.srcW}x${cut.srcH} != sequence; proposed reframe scale ${fillScale.toFixed(3)}`, confidence: 0.6 };
+  },
+};
+
+/**
+ * Online/offline framing residual (§9): a measured X/Y(/scale) offset on SOME
+ * clips. Apply a per-clip position patch ONLY where measured (non-negotiable #4).
+ * Propose-only.
+ */
+const measuredResidual = {
+  id: 'per-clip-measured-position-patch',
+  klass: 'online-offline-residual',
+  deterministic: false,
+  detect(cut) {
+    return !!cut.measuredOffset && (cut.measuredOffset.dx !== 0 || cut.measuredOffset.dy !== 0 || (cut.measuredOffset.ds || 0) !== 0);
+  },
+  propose(cut) {
+    const o = cut.measuredOffset;
+    return { fix: { positionPatch: { dx: -o.dx, dy: -o.dy, ds: o.ds ? -o.ds : 0 } }, scope: cut.cutId, diagnosis: `measured residual (${o.dx},${o.dy}) -> per-clip patch (${-o.dx},${-o.dy})`, confidence: 0.7 };
+  },
+};
+
+/** Apply measured patches ONLY to the cuts that have a measurement (measured-only). */
+function applyMeasuredPatches(cuts, measurements) {
+  return cuts.map((c) => {
+    const m = measurements[c.cutId];
+    if (!m) return { cutId: c.cutId, patched: false };
+    return { cutId: c.cutId, patched: true, positionPatch: { dx: -m.dx, dy: -m.dy, ds: m.ds ? -m.ds : 0 } };
+  });
+}
+
+/** Wrong source entirely (§9): content mismatch → use burn-in identity + media index to find the true source. Propose-only. */
+const wrongSource = {
+  id: 'find-true-source-by-identity',
+  klass: 'wrong-source',
+  deterministic: false,
+  detect(cut, ctx) {
+    return cut.verdict === 'WRONG' && !!ctx.mediaIndex && (!!cut.burnInName || !!cut.source_basename);
+  },
+  propose(cut, ctx) {
+    const name = cut.burnInName || cut.source_basename;
+    const found = ctx.mediaIndex.findTrueSource(name, { minScore: 0.5 });
+    if (!found) return { fix: null, diagnosis: `wrong source: no true-source match for "${name}"`, confidence: 0 };
+    return { fix: { path: found.path, source_basename: found.basename }, diagnosis: `true source for "${name}" -> ${found.basename} (score ${found.score.toFixed(2)})`, confidence: Math.min(0.9, found.score) };
+  },
+};
+
+/** Reel-name conform (§9): EDL/AAF reel only → reel+TC match via the media index. */
+const reelNameConform = {
+  id: 'reel-tc-match',
+  klass: 'reel-name-conform',
+  deterministic: true,
+  detect(cut, ctx) {
+    return !!cut.reel && !!ctx.mediaIndex;
+  },
+  propose(cut, ctx) {
+    const path = ctx.mediaIndex.byReelTc(cut.reel, cut.sourceTc);
+    if (!path) return { fix: null, diagnosis: `reel ${cut.reel} not found`, confidence: 0 };
+    return { fix: { path }, diagnosis: `reel ${cut.reel} @ ${cut.sourceTc} -> ${path}`, confidence: 1 };
+  },
+};
+
+/** Mixed frame rates (§9): clip rate != sequence rate → rate-aware source-frame mapping. Propose-only. */
+const mixedFrameRate = {
+  id: 'rate-aware-frame-map',
+  klass: 'mixed-framerate',
+  deterministic: false,
+  detect(cut, ctx) {
+    return cut.clipRate != null && ctx.sequenceRate != null && cut.clipRate !== ctx.sequenceRate;
+  },
+  propose(cut, ctx) {
+    const mapped = Math.round((cut.sourceFrame || cut.xml_in) * (cut.clipRate / ctx.sequenceRate));
+    return { fix: { sourceFrame: mapped }, diagnosis: `rate ${cut.clipRate} != seq ${ctx.sequenceRate}; mapped source frame -> ${mapped}`, confidence: 0.7 };
+  },
+};
+
+/** Handle shortfall (§9): used range + handles near media bounds → warn + clamp. */
+const handleShortfall = {
+  id: 'clamp-handles',
+  klass: 'handle-shortfall',
+  deterministic: true,
+  detect(cut) {
+    if (cut.mediaLength == null || cut.usedOut == null) return false;
+    const want = cut.handles || 0;
+    return cut.usedOut + want > cut.mediaLength || (cut.usedIn || 0) - want < 0;
+  },
+  propose(cut) {
+    const want = cut.handles || 0;
+    const head = Math.min(want, cut.usedIn || 0);
+    const tail = Math.min(want, cut.mediaLength - cut.usedOut);
+    return { fix: { handlesHead: head, handlesTail: tail }, diagnosis: `handle shortfall: clamped to head ${head}/tail ${tail} (wanted ${want})`, confidence: 1, warn: true };
+  },
+};
+
+/** Missing/offline media (§9): no match anywhere → flag to V2 with diagnosis. */
+const missingMedia = {
+  id: 'flag-missing-media',
+  klass: 'missing-media',
+  deterministic: false,
+  detect(cut, ctx) {
+    return !!cut.pathMissing && (!ctx.mediaIndex || !ctx.mediaIndex.byBasename(cut.source_basename)) && !cut.burnInName;
+  },
+  propose(cut) {
+    return { fix: null, diagnosis: `missing/offline media: ${cut.source_basename || cut.cutId} — flag to V2`, confidence: 0 };
+  },
+};
+
+module.exports = {
+  scaleDoubleCount,
+  subclipOffset,
+  ticksRetime,
+  staleRelink,
+  perFileOffset,
+  aspectVariant,
+  measuredResidual,
+  wrongSource,
+  reelNameConform,
+  mixedFrameRate,
+  handleShortfall,
+  missingMedia,
+  estimatePerFileOffset,
+  applyMeasuredPatches,
+  TPF_24,
+};

package/resolve-advanced/vendor/conform-qc/report/index.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * report/ — the UI-agnostic QC report model (spec §11).
+ *
+ * One report per verify/conform run; one entry per cut. Serializes to the
+ * `metadata.editorial.qc` shape (§11) so the API/UI can read it without knowing
+ * the engine internals.
+ *
+ * Status vocabulary (per cut):
+ *   MATCH | OFFSET | WRONG | UNREADABLE  — content-identity verdicts (had a reference)
+ *   REVIEW                               — escalated to a human (e.g. vision dispute)
+ *   MATH-VERIFIED                        — Tier C: Oracle-consistent, no picture proof
+ *
+ * Tier (§7): A (burned ref) | B (clean ref + sidecar) | C (no reference).
+ *
+ * BADGE RULE (non-negotiable, spec §7): "no picture, no content-verified." A
+ * `content-verified` badge requires an actual frame comparison (Tier A/B with a
+ * MATCH/OFFSET). Tier C can only ever be `math-verified`.
+ */
+
+const REPORT_VERDICTS = Object.freeze(['MATCH', 'OFFSET', 'WRONG', 'UNREADABLE', 'REVIEW', 'MATH-VERIFIED']);
+
+function makeReport(meta = {}) {
+  return {
+    runAt: meta.runAt != null ? meta.runAt : null,
+    target: meta.target || 'resolve',
+    oracleVersion: meta.oracleVersion || '1',
+    tier: meta.tier || null,
+    summary: { matched: 0, offset: 0, wrong: 0, flagged: 0, review: 0, mathVerified: 0, unreadable: 0 },
+    perCut: [],
+    packageKeys: [],
+  };
+}
+
+/**
+ * The verified badge for a cut. Enforces "no picture, no content-verified":
+ *  - content-verified  ONLY when a reference frame was compared (MATCH/OFFSET).
+ *  - math-verified      when there was no reference (Tier C) and the Oracle ran.
+ *  - null               for WRONG / UNREADABLE / REVIEW (no positive claim).
+ */
+function badgeFor(cut) {
+  if (cut.hasReference) {
+    if (cut.status === 'MATCH' || cut.status === 'OFFSET') return 'content-verified';
+    return null; // a reference existed but it did NOT verify
+  }
+  // No reference frame — the strongest claim possible is math-verified.
+  if (cut.status === 'MATH-VERIFIED' || cut.status === 'MATCH' || cut.status === 'OFFSET') {
+    return 'math-verified';
+  }
+  return null;
+}
+
+function addCut(report, cut) {
+  if (!REPORT_VERDICTS.includes(cut.status)) {
+    throw new Error(`report: unknown status "${cut.status}" (one of ${REPORT_VERDICTS.join('|')})`);
+  }
+  const badge = badgeFor(cut);
+  // Guard the non-negotiable: a no-reference cut can NEVER carry content-verified.
+  if (!cut.hasReference && badge === 'content-verified') {
+    throw new Error('report: content-verified badge requires a reference frame (no picture, no content-verified)');
+  }
+  const entry = {
+    cutId: cut.cutId,
+    seqstart: cut.seqstart != null ? cut.seqstart : null,
+    status: cut.status,
+    tier: cut.tier || (cut.hasReference ? 'B' : 'C'),
+    hasReference: !!cut.hasReference,
+    derivedSourceFrame: cut.derivedSourceFrame != null ? cut.derivedSourceFrame : null,
+    derivedSampleFrame: cut.derivedSampleFrame != null ? cut.derivedSampleFrame : null,
+    scale: cut.scale != null ? cut.scale : null,
+    refScore: cut.refScore != null ? cut.refScore : null,
+    offset: cut.offset || null,
+    diagnosis: cut.diagnosis || null,
+    repair: cut.repair || null,
+    advisory: cut.advisory || null,
+    identity: cut.identity || null,
+    escalated: !!cut.escalated,
+    visionConsulted: !!cut.visionConsulted,
+    finalAction: cut.finalAction || null,
+    badge,
+  };
+  report.perCut.push(entry);
+  switch (cut.status) {
+    case 'MATCH':
+      report.summary.matched += 1;
+      break;
+    case 'OFFSET':
+      report.summary.offset += 1;
+      break;
+    case 'WRONG':
+      report.summary.wrong += 1;
+      report.summary.flagged += 1;
+      break;
+    case 'REVIEW':
+      report.summary.review += 1;
+      report.summary.flagged += 1;
+      break;
+    case 'UNREADABLE':
+      report.summary.unreadable += 1;
+      report.summary.flagged += 1;
+      break;
+    case 'MATH-VERIFIED':
+      report.summary.mathVerified += 1;
+      break;
+    default:
+      break;
+  }
+  return entry;
+}
+
+/** Serialize to the documented `metadata.editorial.qc` shape (§11). */
+function toMetadataQc(report) {
+  return {
+    runAt: report.runAt,
+    target: report.target,
+    oracleVersion: report.oracleVersion,
+    tier: report.tier,
+    summary: { ...report.summary },
+    perCut: report.perCut.map((c) => ({
+      cutId: c.cutId,
+      status: c.status,
+      derivedFrame: c.derivedSourceFrame,
+      refScore: c.refScore,
+      diagnosis: c.diagnosis,
+      repair: c.repair,
+      badge: c.badge,
+    })),
+    packageKeys: [...report.packageKeys],
+  };
+}
+
+module.exports = { REPORT_VERDICTS, makeReport, badgeFor, addCut, toMetadataQc };

package/resolve-advanced/vendor/conform-qc/roles/index.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * roles/ — finishing-media resolution (spec §10). Pure contracts + algorithms.
+ *
+ * Two mechanisms (decided): a per-version `editorialRole`, and a cross-asset
+ * `MediaRelationship` (the load-bearing proxy↔scan link with a frameOffset).
+ * The Prisma fields are thin bindings to these contracts; the resolution ORDER
+ * and ingest heuristic live here and are fully verifiable without a DB.
+ */
+
+const EDITORIAL_ROLES = Object.freeze(['offline', 'proxy', 'online', 'finishing', 'reference', 'other']);
+const MEDIA_RELATIONSHIP_KINDS = Object.freeze(['proxy_of', 'scan_of', 'vfx_of', 'upscale_of', 'regrade_of']);
+// Relationship kinds that point from a working asset TO its finishing media.
+const FINISHING_KINDS = Object.freeze(['scan_of', 'upscale_of', 'vfx_of', 'regrade_of']);
+
+function isValidRole(r) {
+  return EDITORIAL_ROLES.includes(r);
+}
+
+function makeMediaRelationship({ fromAssetId, toAssetId, kind, frameOffset = 0, notes = '' }) {
+  if (!fromAssetId || !toAssetId) throw new Error('MediaRelationship: fromAssetId + toAssetId required');
+  if (!MEDIA_RELATIONSHIP_KINDS.includes(kind)) throw new Error(`MediaRelationship: kind must be one of ${MEDIA_RELATIONSHIP_KINDS.join('|')}`);
+  return { type: 'MediaRelationship', fromAssetId, toAssetId, kind, frameOffset, notes };
+}
+
+/** In-memory store (the Prisma table is a thin binding to this). */
+class MediaRelationshipStore {
+  constructor(seed = []) {
+    this.rels = seed.map((r) => (r.type === 'MediaRelationship' ? r : makeMediaRelationship(r)));
+  }
+
+  add(rel) {
+    const r = rel.type === 'MediaRelationship' ? rel : makeMediaRelationship(rel);
+    this.rels.push(r);
+    return r;
+  }
+
+  forAsset(assetId) {
+    return this.rels.filter((r) => r.fromAssetId === assetId || r.toAssetId === assetId);
+  }
+}
+
+/**
+ * Resolution order (§10): which media does this reference conform to?
+ *   explicit MediaRelationship → project override → version editorialRole
+ *   (finishing→online) → naming convention (4K-2K→4K) → highest-resolution version.
+ * @returns { assetId?, path?, via, frameOffset? }
+ */
+function resolveMedia(ref, ctx = {}) {
+  const versions = ref.versions || [];
+
+  // 1. explicit MediaRelationship to a finishing asset.
+  if (ctx.relationships) {
+    const rel = ctx.relationships.forAsset(ref.assetId).find((r) => r.fromAssetId === ref.assetId && FINISHING_KINDS.includes(r.kind));
+    if (rel) {
+      const p = ctx.resolveAssetPath ? ctx.resolveAssetPath(rel.toAssetId) : null;
+      return { assetId: rel.toAssetId, path: p, via: 'relationship', frameOffset: rel.frameOffset };
+    }
+  }
+  // 2. project override map.
+  if (ctx.projectOverride && ctx.projectOverride[ref.assetId] != null) {
+    return { path: ctx.projectOverride[ref.assetId], via: 'project-override' };
+  }
+  // 3. version editorialRole (finishing preferred, then online).
+  const byRole = versions.find((v) => v.role === 'finishing') || versions.find((v) => v.role === 'online');
+  if (byRole) return { path: byRole.path, via: 'role', role: byRole.role };
+  // 4. naming convention: a "4K" version (not the "4K-2K" proxy).
+  const scan = versions.find((v) => /\b4k\b/i.test(v.name || '') && !/4k-2k/i.test(v.name || ''));
+  if (scan) return { path: scan.path, via: 'naming' };
+  // 5. highest-resolution version.
+  const top = versions.reduce((best, v) => (best == null || (v.width || 0) > (best.width || 0) ? v : best), null);
+  return top ? { path: top.path, via: 'highest-res' } : { path: null, via: 'none' };
+}
+
+/**
+ * Ingest heuristic (§10): seed a default role/relationship from res/codec/name.
+ * Returns { role, relationship? } suggestions (user corrects via the UI picker).
+ */
+function ingestHeuristic(asset, opts = {}) {
+  const name = (asset.name || '').toLowerCase();
+  const w = asset.width || 0;
+  let role = 'other';
+  if (/proxy|4k-2k/.test(name) || (w > 0 && w <= 1024)) role = 'proxy';
+  else if (/\b4k\b/.test(name) || w >= 3600) role = 'finishing';
+  else if (/online|finish/.test(name)) role = 'online';
+  else if (/offline/.test(name)) role = 'offline';
+  const out = { role };
+  // If a sibling finishing asset is offered, seed the proxy↔scan relationship.
+  if (role === 'proxy' && opts.finishingAssetId) {
+    out.relationship = makeMediaRelationship({ fromAssetId: asset.id, toAssetId: opts.finishingAssetId, kind: 'scan_of', frameOffset: opts.frameOffset || 0, notes: 'ingest heuristic' });
+  }
+  return out;
+}
+
+module.exports = { EDITORIAL_ROLES, MEDIA_RELATIONSHIP_KINDS, isValidRole, makeMediaRelationship, MediaRelationshipStore, resolveMedia, ingestHeuristic };