davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/server/black-balance.mjs

@@ -0,0 +1,92 @@
+/**
+ * black_balance (P1d) — neutralize a SHADOW cast specifically. Where white_balance_match
+ * balances a mid/highlight neutral patch, this operates on the p1 shadow point ONLY: it aligns
+ * each channel's black point to a common target (the lowest channel black), removing a colour
+ * cast in the shadows WITHOUT lifting or crushing them (gain=1, offset-only).
+ *
+ * Emits an offset-only affine (reuse generateAssertedAffineDRX). Skips a clip whose shadows are
+ * already neutral (nothing to do — skip-not-fake). LOCAL & deterministic; no Resolve.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { generateAssertedAffineDRX } from './contrast-normalize.mjs';
+import { provenanceLabel, gist } from './node-provenance.mjs';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("black-balance needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = clamp(Math.round((p / 100) * (sorted.length - 1)), 0, sorted.length - 1);
+  return sorted[idx];
+}
+
+/** Per-channel black point (p1, 0..1). Returns {r,g,b} or null. */
+export async function measureBlackPoint(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const lowP = opts.lowPct ?? 1,
+    maxSide = opts.maxSide ?? 480;
+  let data, ch;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+  } catch {
+    return null;
+  }
+  const R = [],
+    G = [],
+    B = [];
+  for (let i = 0; i < data.length; i += ch) {
+    R.push(data[i]);
+    G.push(data[i + 1]);
+    B.push(data[i + 2]);
+  }
+  if (!R.length) return null;
+  R.sort((a, b) => a - b);
+  G.sort((a, b) => a - b);
+  B.sort((a, b) => a - b);
+  return { r: percentile(R, lowP) / 255, g: percentile(G, lowP) / 255, b: percentile(B, lowP) / 255 };
+}
+
+/**
+ * @param {Array<{id, png, group?}>} clips
+ * @param {{outDir, castThreshold?:number, clampOffset?:[number,number]}} opts
+ */
+export async function computeBlackBalance(clips, opts = {}) {
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+  const castThreshold = opts.castThreshold ?? 0.004; // ~1/255 — below this the shadows are already neutral
+  const [olo, ohi] = opts.clampOffset || [-0.2, 0.2];
+
+  const grades = [];
+  const warnings = [];
+  const skipped = [];
+  const report = {};
+  for (const c of clips) {
+    const bp = await measureBlackPoint(c.png, opts);
+    if (!bp) {
+      skipped.push({ id: c.id, reason: 'unreadable frame' });
+      continue;
+    }
+    const target = Math.min(bp.r, bp.g, bp.b); // align to the lowest black — pull casts DOWN, don't lift
+    const spread = Math.max(bp.r, bp.g, bp.b) - target;
+    if (spread < castThreshold) {
+      skipped.push({ id: c.id, reason: 'shadows already neutral', castSpread: +spread.toFixed(4) });
+      continue;
+    }
+    const gain = { r: 1, g: 1, b: 1 };
+    const offset = { r: clamp(target - bp.r, olo, ohi), g: clamp(target - bp.g, olo, ohi), b: clamp(target - bp.b, olo, ohi) };
+    const drxPath = `${opts.outDir}/${c.id}_blackbal.drx`;
+    await generateAssertedAffineDRX(gain, offset, provenanceLabel('black_balance', { source: 'shadow-neutral', gist: gist('offset', offset) }), drxPath, warnings);
+    grades.push({ id: c.id, offset, castSpreadPct: +(100 * spread).toFixed(2), drxPath });
+    report[c.id] = { castSpreadPct: +(100 * spread).toFixed(2) };
+  }
+  return { grades, report, warnings, skipped };
+}

package/resolve-advanced/server/capabilities.mjs

@@ -0,0 +1,86 @@
+/**
+ * Optional-capability detection. The published package is pure-JS/MIT with ZERO
+ * required native modules or bundled binaries. A few tools need an external tool
+ * the user installs themselves:
+ *
+ * ffmpeg / ffprobe (on PATH) — audio ops (split/trim/convert) + conform frame ops
+ * sharp (npm i) — conform.verify brightness-robust frame compare
+ * better-sqlite3 (npm i) — fairlight live-project-DB path (the .drp-zip path needs none)
+ *
+ * We DON'T bundle ffmpeg-static (its FFmpeg binaries are GPL — incompatible with a
+ * clean MIT distribution). Resolve users already have ffmpeg, or: `brew install ffmpeg`.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cache = new Map();
+
+function onPath(bin) {
+  if (cache.has(bin)) return cache.get(bin);
+  let ok = false;
+  try {
+    const r = spawnSync(bin, ['-version'], { stdio: 'ignore', timeout: 4000 });
+    ok = !r.error && (r.status === 0 || r.status === null);
+  } catch {
+    ok = false;
+  }
+  cache.set(bin, ok);
+  return ok;
+}
+
+function nodeModuleAvailable(name) {
+  const key = `mod:${name}`;
+  if (cache.has(key)) return cache.get(key);
+  let ok = false;
+  try {
+    require.resolve(name);
+    ok = true;
+  } catch {
+    ok = false;
+  }
+  cache.set(key, ok);
+  return ok;
+}
+
+export const hasFfmpeg = () => onPath('ffmpeg');
+export const hasFfprobe = () => onPath('ffprobe');
+export const hasSharp = () => nodeModuleAvailable('sharp');
+export const hasBetterSqlite3 = () => nodeModuleAvailable('better-sqlite3');
+
+/** Throw a clear, actionable error if ffmpeg/ffprobe aren't on PATH. */
+export function requireFfmpeg() {
+  if (!hasFfmpeg() || !hasFfprobe()) {
+    throw new Error(
+      'This feature needs ffmpeg + ffprobe on your PATH (not bundled — FFmpeg binaries are GPL). ' +
+        'Install: macOS `brew install ffmpeg`, Debian/Ubuntu `apt install ffmpeg`, Windows `choco install ffmpeg`.',
+    );
+  }
+}
+
+/** Capability snapshot — what's available + how to enable what isn't. */
+export function capabilities() {
+  const ff = hasFfmpeg() && hasFfprobe();
+  return {
+    core: 'always available (pure-JS): drp, drt, drx, offline_ref, editorial, fusion, audio_plan, conform(core)',
+    optional: {
+      ffmpeg: { available: ff, enables: 'audio (split/trim/convert)', install: 'brew install ffmpeg / apt install ffmpeg' },
+      sharp: { available: hasSharp(), enables: 'conform.verify (frame compare)', install: 'npm i sharp' },
+      'better-sqlite3': { available: hasBetterSqlite3(), enables: 'fairlight live-project-DB path (zip path needs none)', install: 'npm i better-sqlite3' },
+    },
+  };
+}
+
+/** One-line startup summary to stderr (never stdout — that's the MCP channel). */
+export function logCapabilities() {
+  const c = capabilities();
+  const miss = Object.entries(c.optional)
+    .filter(([, v]) => !v.available)
+    .map(([k]) => k);
+  if (miss.length) {
+    process.stderr.write(
+      `[davinci-resolve-advanced-mcp] optional features needing setup: ${miss.join(', ')} — call the 'capabilities' tool for install hints.\n`,
+    );
+  }
+}

package/resolve-advanced/server/cdl-io.mjs

@@ -0,0 +1,76 @@
+/**
+ * ASC CDL import (C3 `cdl_io`).
+ *
+ * DITs and on-set colour ship looks as ASC CDL (.cc single,.ccc collection,.cdl) —
+ * slope/offset/power + saturation. This brings those into the grade as per-clip.drx
+ * so an on-set CDL can seed the look. The reverse (DRX → CDL) already exists as the
+ * `export_cdl` action; this is the import direction.
+ *
+ * Pure composition of the validated codec: parseCDL → cdlToDRX → generateDRX, with a
+ * round-trip non-empty assert (a non-identity CDL that decodes to an EMPTY grade is the
+ * silent-drop bug — throw, don't ship a no-op). slope→gain, offset→offset, power→gamma
+ * (model conversion, approximate by design — flagged), sat (0–2)→Resolve sat (0–100).
+ * LOCAL & deterministic; no Resolve.
+ */
+import fs from 'node:fs';
+import { drxCdl, drxGenerator, drxParser } from './libs.mjs';
+
+const isIdentityCDL = (c) => {
+  const s = c.slope || {},
+    o = c.offset || {},
+    p = c.power || {};
+  const near = (v, t) => Math.abs((v ?? t) - t) < 1e-4;
+  return (
+    near(s.r, 1) &&
+    near(s.g, 1) &&
+    near(s.b, 1) &&
+    near(o.r, 0) &&
+    near(o.g, 0) &&
+    near(o.b, 0) &&
+    near(p.r, 1) &&
+    near(p.g, 1) &&
+    near(p.b, 1) &&
+    near(c.saturation, 1)
+  );
+};
+
+async function paramCount(content) {
+  const parsed = await drxParser().parseDRXContent(content);
+  return (parsed.nodes || []).flatMap((n) => (n.correctors || []).flatMap((cor) => cor.parameters || [])).length;
+}
+
+/**
+ * @param {string} cdlContent — raw .cc/.ccc/.cdl XML
+ * @param {{outDir:string}} opts
+ * @returns {Promise<{grades:Array<{id,drxPath,identity:boolean}>, warnings:string[]}>}
+ */
+export async function importCDL(cdlContent, opts = {}) {
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  const cdl = drxCdl();
+  const corrections = cdl.parseCDL(cdlContent);
+  if (!corrections.length) throw new Error('no <ColorCorrection> found — not a CDL/CCC/CC document');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+
+  const grades = [];
+  const warnings = [];
+  let i = 0;
+  for (const c of corrections) {
+    const id = (c.id || `cc${i}`).replace(/[^\w.-]/g, '_');
+    const values = c.cdlValues || c; // parseCDL nests under cdlValues
+    const params = cdl.cdlToDRX(values);
+    const out = await drxGenerator().generateDRX(params, { label: `CDL ${id}` });
+    const content = typeof out === 'string' ? out : out?.content || out?.drxContent;
+    const identity = isIdentityCDL(values);
+    if (!identity && (await paramCount(content)) === 0) {
+      throw new Error(`round-trip assert FAILED: CDL '${id}' is non-identity but generated an EMPTY grade (${JSON.stringify(values)})`);
+    }
+    const drxPath = `${opts.outDir}/${id}.drx`;
+    fs.writeFileSync(drxPath, content);
+    grades.push({ id, drxPath, identity });
+    i++;
+  }
+  warnings.push(
+    'power→gamma is a model conversion (Resolve gamma ≠ ASC power); the look is approximate by design, not a 1:1 transfer. Validate against the on-set reference.',
+  );
+  return { grades, warnings };
+}

package/resolve-advanced/server/contrast-normalize.mjs

@@ -0,0 +1,180 @@
+/**
+ * Contrast normalize — black/white-point match (C3 `contrast_normalize`).
+ *
+ * Where exposure_level matches a MEAN (a single offset), contrast_normalize matches the
+ * tonal RANGE: each clip's robust black point and white point are mapped onto a group
+ * hero's, per channel, by an affine fit out = scale·in + shift (scale→gain, shift→
+ * offset). This lines clips up in the same tonal range BEFORE a shared look, so the look
+ * lands consistently. Robust points = 1st/99th percentile (ignores a few hot/black outliers).
+ *
+ * OFFSET SEMANTICS (live-validated 2026-07-03, DaVinci YRGB/Rec709): Resolve's wire
+ * offset shifts output by wire×0.2 normalized, wire range ±1 (→ ±0.2 norm max). The
+ * emitter converts normalized intent → wire (×5), clamps, and warns on clamp. The RGB
+ * gain wheels are luma-renormalized by Resolve (balance only) — the achromatic level
+ * rides gain.master.
+ *
+ * ACEScct (measured live 2026-07-03, synthetic project, Rec.709 IDT/ODT): the
+ * STRUCTURAL semantics hold (luma-renorm of RGB wheels; master carries level), but
+ * wheels operate in cct WORKING space before the ACES output tonescale, so the ×0.2
+ * display factor does NOT transfer — display response is level-dependent. Under
+ * ACEScct, treat emitted trims as directionally-correct starting nudges and CONVERGE
+ * by iteration (apply → re-extract → re-measure), per the pass-based review design.
+ * LOCAL & deterministic; no Resolve.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { drxTool } from './tools/drx.mjs';
+import { provenanceLabel, gist } from './node-provenance.mjs';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("contrast-normalize needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = clamp(Math.round((p / 100) * (sorted.length - 1)), 0, sorted.length - 1);
+  return sorted[idx];
+}
+
+/** Per-channel black/white points (normalized 0..1) at the given percentiles. */
+export async function measureBWPoints(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const lowP = opts.lowPct ?? 1,
+    highP = opts.highPct ?? 99,
+    maxSide = opts.maxSide ?? 480;
+  let data, ch;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+  } catch {
+    return null;
+  }
+  const R = [],
+    G = [],
+    B = [];
+  for (let i = 0; i < data.length; i += ch) {
+    R.push(data[i]);
+    G.push(data[i + 1]);
+    B.push(data[i + 2]);
+  }
+  if (!R.length) return null;
+  R.sort((a, b) => a - b);
+  G.sort((a, b) => a - b);
+  B.sort((a, b) => a - b);
+  const mk = (arr) => ({ black: percentile(arr, lowP) / 255, white: percentile(arr, highP) / 255 });
+  return { r: mk(R), g: mk(G), b: mk(B) };
+}
+
+/** Wire-offset units per NORMALIZED (0..1) shift. Live-validated 2026-07-03 (DaVinci
+ * YRGB / Rec709 render): wire offset −0.1 shifts output by exactly −0.02 normalized
+ * (−5/255), i.e. norm = wire × 0.2. Recalibrate for other color sciences (ACEScct) on
+ * real-footage validation before trusting large offsets there. */
+export const OFFSET_WIRE_PER_NORM = 5;
+
+/** Generate a gain+offset DRX and THROW if a non-identity affine decodes empty.
+ * `gain`/`offset` are INTENT in display-normalized units: out = gain·in + offset (0..1).
+ * The emitter converts to wire units (offset ×5; gain.master carries the achromatic
+ * level — Resolve luma-renormalizes the RGB gain wheels, see generateAssertedGainDRX). */
+export async function generateAssertedAffineDRX(gain, offset, label, outPath, warnings) {
+  const master = 0.2126 * gain.r + 0.7152 * gain.g + 0.0722 * gain.b;
+  // Wire offset range is ±1 (decode clamps beyond it — live-validated: wrote −1.22,
+  // read back −1.0). Clamp HERE and warn so intent and wire never silently diverge.
+  const wire = {};
+  for (const k of ['r', 'g', 'b']) {
+    const w = offset[k] * OFFSET_WIRE_PER_NORM;
+    wire[k] = Math.max(-1, Math.min(1, w));
+    if (w !== wire[k] && Array.isArray(warnings))
+      warnings.push(`${label}: offset.${k} ${offset[k].toFixed(4)} (norm) exceeds the wire range ±1 (=±0.2 norm) — clamped; the black/white point will land short. Split the move across gain/lift or grade manually.`);
+  }
+  await drxTool.handler({
+    action: 'generate',
+    // gain/offset here are computed in raw DRX-internal units → pin to space:'drx'
+    // (the tool default is 'ui', which would rescale offset by ÷25).
+    args: {
+      gradeParams: {
+        space: 'drx',
+        gain: [gain.r, gain.g, gain.b, master],
+        offset: [wire.r, wire.g, wire.b, 0.0],
+      },
+      metadata: { label },
+      outputPath: outPath,
+    },
+  });
+  const back = await drxTool.handler({ action: 'parse', args: { content: fs.readFileSync(outPath, 'utf8') } });
+  const got = (back.nodes || [])
+    .flatMap((n) => (n.correctors || []).flatMap((c) => c.parameters || []))
+    .filter((p) => /(gain|offset)\.(r|g|b)/i.test(p.name)).length;
+  const nonIdentity = ['r', 'g', 'b'].some((k) => Math.abs(gain[k] - 1) > 0.002 || Math.abs(offset[k]) > 0.002);
+  if (nonIdentity && got === 0)
+    throw new Error(`round-trip assert FAILED: ${label} affine decoded EMPTY (gain ${JSON.stringify(gain)} offset ${JSON.stringify(offset)})`);
+  return outPath;
+}
+
+/**
+ * @param {Array<{id:string|number, png:string, group:string}>} clips
+ * @param {{outDir:string, heroId?:string|number, clampGain?:[number,number],
+ * clampOffset?:[number,number], maxCorrWarn?:number}} opts
+ */
+export async function computeContrastNormalize(clips, opts = {}) {
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  const [glo, ghi] = opts.clampGain || [0.5, 2];
+  const [olo, ohi] = opts.clampOffset || [-0.5, 0.5];
+  const maxCorrWarn = opts.maxCorrWarn ?? 0.3;
+  fs.mkdirSync(opts.outDir, { recursive: true });
+
+  const byGroup = new Map();
+  for (const c of clips) {
+    if (!byGroup.has(c.group)) byGroup.set(c.group, []);
+    byGroup.get(c.group).push(c);
+  }
+
+  const grades = [];
+  const report = {};
+  const warnings = [];
+  const skipped = [];
+
+  for (const [group, gclips] of byGroup) {
+    for (const c of gclips) {
+      c.bw = await measureBWPoints(c.png, opts);
+    }
+    const usable = gclips.filter((c) => c.bw);
+    for (const c of gclips.filter((c) => !c.bw)) skipped.push({ id: c.id, group, reason: 'unreadable frame' });
+    if (!usable.length) {
+      report[group] = { error: 'no readable frames' };
+      continue;
+    }
+    const hero = (opts.heroId != null && usable.find((c) => c.id === opts.heroId)) || usable[0];
+
+    let maxCorr = 0;
+    for (const c of usable) {
+      const gain = {},
+        offset = {};
+      for (const k of ['r', 'g', 'b']) {
+        const H = hero.bw[k],
+          C = c.bw[k];
+        const span = C.white - C.black || 1e-6;
+        const scale = clamp((H.white - H.black) / span, glo, ghi);
+        const shift = clamp(H.black - scale * C.black, olo, ohi);
+        gain[k] = scale;
+        offset[k] = shift;
+      }
+      const corr = Math.max(...['r', 'g', 'b'].map((k) => Math.max(Math.abs(gain[k] - 1), Math.abs(offset[k]))));
+      maxCorr = Math.max(maxCorr, corr);
+      const drxPath = `${opts.outDir}/${group}_${c.id}_contrast.drx`;
+      await generateAssertedAffineDRX(gain, offset, provenanceLabel('contrast_normalize', { source: `hero:${hero.id}`, gist: gist('gain', gain) }), drxPath, warnings);
+      grades.push({ id: c.id, group, gain, offset, correctionPct: +(100 * corr).toFixed(2), drxPath, isHero: c === hero });
+    }
+    report[group] = { clips: usable.length, hero_id: hero.id, max_correction_pct: +(100 * maxCorr).toFixed(2) };
+    if (maxCorr > maxCorrWarn)
+      warnings.push(
+        `${group}: max contrast correction ${(100 * maxCorr).toFixed(1)}% — large; check the hero is representative and frames are display-referred.`,
+      );
+  }
+  return { grades, report, warnings, skipped };
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Shared safety framework for LIVE Project.db patches — the "beyond-the-API" tier.
+ *
+ * ⚠️ Unsanctioned territory (Blackmagic doesn't support direct DB edits). Every write
+ * goes through: project-CLOSED gate → auto-backup → schema-version guard → read-back
+ * verify. The schema map is Resolve 21 / ProjectVersion 17 (the design notes design notes);
+ * the column guard refuses rather than corrupting if the schema differs.
+ *
+ * Needs the optional native dep `better-sqlite3` (lazy).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const DISK_DB_ROOT = path.join(os.homedir(), 'Library/Application Support/Blackmagic Design/DaVinci Resolve/Resolve Disk Database/Resolve Projects');
+
+export function loadSqlite() {
+  try {
+    return require('better-sqlite3');
+  } catch {
+    throw new Error("Project.db patching needs the optional native dep 'better-sqlite3'. Install: npm i better-sqlite3");
+  }
+}
+
+/** Recursively locate <projectName>/Project.db under the Resolve Disk Database. */
+export function findProjectDb(projectName, root = DISK_DB_ROOT) {
+  const hits = [];
+  const walk = (dir, depth) => {
+    if (depth > 8) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const full = path.join(dir, e.name);
+      if (e.name === projectName && fs.existsSync(path.join(full, 'Project.db'))) hits.push(path.join(full, 'Project.db'));
+      walk(full, depth + 1);
+    }
+  };
+  if (fs.existsSync(root)) walk(root, 0);
+  return hits;
+}
+
+export function resolveDbPath({ projectDb, projectName }) {
+  if (projectDb) return projectDb;
+  if (!projectName) throw new Error('provide projectDb (path) or projectName');
+  const hits = findProjectDb(projectName);
+  if (!hits.length) throw new Error(`no Project.db found for project "${projectName}" under the Resolve Disk Database`);
+  if (hits.length > 1) throw new Error(`multiple Project.db match "${projectName}": pass projectDb explicitly`);
+  return hits[0];
+}
+
+/** Open a Project.db, refusing if a required (table, column) guard is absent (version safety). */
+export function openGuarded(dbPath, { writable = false, table, column } = {}) {
+  const Database = loadSqlite();
+  if (!fs.existsSync(dbPath)) throw new Error(`Project.db not found: ${dbPath}`);
+  const db = new Database(dbPath, { readonly: !writable });
+  if (table && column) {
+    // Quote the table identifier — Resolve tables like "ListMgt::LmVersion" contain "::" which is an
+    // illegal token unquoted (the PRAGMA would fail with "unrecognized token: :").
+    const cols = db
+      .prepare(`PRAGMA table_info("${String(table).replace(/"/g, '""')}")`)
+      .all()
+      .map((c) => c.name);
+    if (!cols.includes(column)) {
+      db.close();
+      throw new Error(`${table}.${column} not found — unsupported Project.db schema/version; refusing to patch.`);
+    }
+  }
+  return db;
+}
+
+export function backup(dbPath) {
+  const bak = `${dbPath}.bak`;
+  fs.copyFileSync(dbPath, bak);
+  return bak;
+}
+
+/** Gate every write: the project must be closed (Resolve oversaves an open project). */
+export function requireClosed(opts) {
+  if (!opts.iConfirmProjectClosed) {
+    throw new Error('Refusing to write: close the project in Resolve first (it oversaves on save), then pass iConfirmProjectClosed: true.');
+  }
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Cluster D — deliverable ENTITY modeling `[cap]`. A "deliverable" is not one file: it's a
+ * family of entities each with its own compliance rules — texted (final) + textless (clean,
+ * for localization) + stems/M&E (music & effects, audio-only) + slate + leader. Modeling them
+ * as first-class entities lets deliverable_qc run the RIGHT rules per entity (a textless master
+ * must carry NO burned-in titles; an M&E stem is audio-only with a fixed layout; a slate has a
+ * duration rule) instead of one flat spec.
+ *
+ * PURE: expands a base deliverable spec into concrete entities, each with a merged QC spec +
+ * named rules deliverable_qc / loudness_qc consume. No Resolve, no LLM. Tenant-ready: no globals.
+ */
+
+// Per-entity defaults layered onto the base master spec. `notes` are human rules a tool can't
+// fully verify offline (e.g. "no burned-in text") — surfaced so online/producer check them.
+export const ENTITY_DEFAULTS = {
+  texted: {
+    kind: 'texted',
+    describe: 'Final program master with titles/lower-thirds/graphics.',
+    specOverride: {},
+    rules: ['video_compliance', 'audio_compliance', 'duration'],
+    notes: [],
+  },
+  textless: {
+    kind: 'textless',
+    describe: 'Clean master for localization — identical picture spec, NO burned-in text.',
+    specOverride: {},
+    rules: ['video_compliance', 'audio_compliance', 'duration', 'no_burned_in_text'],
+    notes: ['no_burned_in_text is not auto-verifiable offline — online must eyeball for residual titles/lower-thirds'],
+  },
+  stems_ME: {
+    kind: 'stems_ME',
+    describe: 'Music & Effects stem — audio-only deliverable, dialogue removed.',
+    // Audio-only: drop the video spec; keep/override the audio layout.
+    dropVideo: true,
+    specOverride: {},
+    rules: ['audio_compliance', 'loudness', 'no_dialogue'],
+    notes: ['no_dialogue is not auto-verifiable offline — mix/online confirms dialogue is absent'],
+  },
+  slate: {
+    kind: 'slate',
+    describe: 'Slate/ident — fixed short duration with programme metadata.',
+    specOverride: {},
+    rules: ['duration', 'video_compliance'],
+    notes: ['slate content (title/ep/date) is a human check'],
+  },
+  leader: {
+    kind: 'leader',
+    describe: 'Countdown/black leader ahead of programme start.',
+    specOverride: {},
+    rules: ['duration'],
+    notes: [],
+  },
+};
+
+/** Shallow-merge a spec override onto a base spec (per top-level block). */
+function mergeSpec(base = {}, override = {}, dropVideo = false) {
+  const out = { ...base, ...override };
+  if (base.video || override.video) out.video = { ...(base.video || {}), ...(override.video || {}) };
+  if (base.audio || override.audio) out.audio = { ...(base.audio || {}), ...(override.audio || {}) };
+  if (dropVideo) delete out.video;
+  return out;
+}
+
+/**
+ * Expand a base deliverable into its entities.
+ * @param {{name?:string, spec:object, entities?:string[]}} deliverable
+ *   spec = the master compliance spec (video/audio/container/duration/...); entities = kinds to emit.
+ * @returns {{name:string, entities:Array<{kind, name, describe, spec, rules, notes}>}}
+ */
+export function expandDeliverable(deliverable) {
+  const name = deliverable.name || 'deliverable';
+  const kinds = deliverable.entities && deliverable.entities.length ? deliverable.entities : ['texted'];
+  const entities = kinds.map((k) => {
+    const def = ENTITY_DEFAULTS[k];
+    if (!def) throw new Error(`expandDeliverable: unknown entity kind '${k}' (known: ${Object.keys(ENTITY_DEFAULTS).join(', ')})`);
+    return {
+      kind: def.kind,
+      name: `${name}.${def.kind}`,
+      describe: def.describe,
+      spec: mergeSpec(deliverable.spec || {}, def.specOverride, def.dropVideo),
+      rules: def.rules,
+      notes: def.notes,
+    };
+  });
+  return { name, entities };
+}