davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/server/match-to-reference.mjs

@@ -0,0 +1,173 @@
+/**
+ * match_to_reference (P1c) — the headline general-case matcher. Move a target frame toward a
+ * REFERENCE image (approved still / client "make it look like this" / hero render) via affine
+ * mean-std transfer ("Reinhard-lite"): per channel gain = std_ref/std_tgt, offset = mean_ref −
+ * gain·mean_tgt. This is exactly the gain+offset affine the codec already emits (reuse
+ * generateAssertedAffineDRX) — no new DRX write path.
+ *
+ * CRAFT AMENDMENTS (cross-craft review, non-negotiable):
+ *  - `lumaPreserve` default ON — apply the CHROMA shift but renormalize to the target's own luma
+ *    (a colour/look match, not an exposure move).
+ *  - SKIN-region-gated by default when skin is present — and match hue toward the vectorscope
+ *    skin-LINE, never a single RGB mean (the calibrated-for-white-skin trap).
+ *  - It is a starting NUDGE a human ratifies (gate: review), a TRIM — never a cross-IDT reconciler.
+ *
+ * Guards: reference unreadable → skip+warn; clamp gain/offset; over-correction warning. LOCAL &
+ * deterministic; no Resolve, no LLM. Frames must be display-referred (like every matcher).
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { generateAssertedAffineDRX } from './contrast-normalize.mjs';
+import { provenanceLabel, gist } from './node-provenance.mjs';
+import { isSkin } from './skin-match.mjs';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("match-to-reference needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+const lumaW = { r: 0.2126, g: 0.7152, b: 0.0722 };
+
+/**
+ * Per-channel mean+std (0..1) over the whole frame OR skin-gated pixels.
+ * @returns {Promise<{mean:{r,g,b}, std:{r,g,b}, skinFrac:number}|null>}
+ */
+export async function measureMeanStd(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const maxSide = opts.maxSide ?? 480;
+  let data, ch, n;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+    n = Math.floor(data.length / ch);
+  } catch {
+    return null;
+  }
+  if (!n) return null;
+  const skinGate = opts.skinGate;
+  let sr = 0,
+    sg = 0,
+    sb = 0,
+    srr = 0,
+    sgg = 0,
+    sbb = 0,
+    cnt = 0,
+    nSkin = 0;
+  for (let i = 0; i < data.length; i += ch) {
+    const r = data[i],
+      g = data[i + 1],
+      b = data[i + 2];
+    const skin = isSkin(r, g, b, opts.skinOpts || {});
+    if (skin) nSkin++;
+    if (skinGate && !skin) continue;
+    sr += r;
+    sg += g;
+    sb += b;
+    srr += r * r;
+    sgg += g * g;
+    sbb += b * b;
+    cnt++;
+  }
+  if (!cnt) return null;
+  const mk = (s, ss) => {
+    const m = s / cnt;
+    return { mean: m / 255, std: Math.sqrt(Math.max(0, ss / cnt - m * m)) / 255 };
+  };
+  const R = mk(sr, srr),
+    G = mk(sg, sgg),
+    B = mk(sb, sbb);
+  return { mean: { r: R.mean, g: G.mean, b: B.mean }, std: { r: R.std, g: G.std, b: B.std }, skinFrac: nSkin / n };
+}
+
+/**
+ * @param {Array<{id, png, reference?}>} clips per-clip reference OR shared opts.reference
+ * @param {{outDir, reference?, lumaPreserve?, skinGate?, clampGain?, clampOffset?, minSkinFrac?}} opts
+ */
+export async function computeMatchToReference(clips, opts = {}) {
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+  const lumaPreserve = opts.lumaPreserve !== false; // default ON
+  const [glo, ghi] = opts.clampGain || [0.5, 2];
+  const [olo, ohi] = opts.clampOffset || [-0.5, 0.5];
+  const minSkinFrac = opts.minSkinFrac ?? 0.02;
+
+  const grades = [];
+  const warnings = [];
+  const skipped = [];
+  const report = {};
+
+  // Shared reference stats (measured once) — skin-gated when the reference itself has skin.
+  const refCache = new Map();
+  async function refStats(refPath) {
+    if (refCache.has(refPath)) return refCache.get(refPath);
+    // Probe skin fraction with a whole-frame pass, then decide gating.
+    const whole = await measureMeanStd(refPath, { skinGate: false });
+    let stats = whole;
+    let gated = false;
+    if (whole && opts.skinGate !== false && whole.skinFrac >= minSkinFrac) {
+      const skin = await measureMeanStd(refPath, { skinGate: true });
+      if (skin) {
+        stats = skin;
+        gated = true;
+      }
+    }
+    const val = stats ? { ...stats, gated } : null;
+    refCache.set(refPath, val);
+    return val;
+  }
+
+  for (const c of clips) {
+    const refPath = c.reference || opts.reference;
+    if (!refPath) {
+      skipped.push({ id: c.id, reason: 'no reference provided' });
+      continue;
+    }
+    const ref = await refStats(refPath);
+    if (!ref) {
+      skipped.push({ id: c.id, reason: 'reference unreadable' });
+      warnings.push(`${c.id}: reference '${refPath}' unreadable — skipped, not faked.`);
+      continue;
+    }
+    // Target: gate to skin iff the reference was skin-gated (compare like with like).
+    const tgt = await measureMeanStd(c.png, { skinGate: ref.gated });
+    if (!tgt) {
+      skipped.push({ id: c.id, reason: ref.gated ? 'target has no skin pixels to match' : 'target unreadable' });
+      continue;
+    }
+    const gain = {},
+      offset = {};
+    for (const k of ['r', 'g', 'b']) {
+      const st = tgt.std[k] || 1e-6;
+      gain[k] = clamp(ref.std[k] / st, glo, ghi);
+      offset[k] = clamp(ref.mean[k] - gain[k] * tgt.mean[k], olo, ohi);
+    }
+    if (lumaPreserve) {
+      // Keep the TARGET's own luma: shift all channels uniformly so transformed luma == target luma.
+      const tgtLuma = lumaW.r * tgt.mean.r + lumaW.g * tgt.mean.g + lumaW.b * tgt.mean.b;
+      const outLuma = ['r', 'g', 'b'].reduce((s, k) => s + lumaW[k] * (gain[k] * tgt.mean[k] + offset[k]), 0);
+      const delta = tgtLuma - outLuma;
+      for (const k of ['r', 'g', 'b']) offset[k] = clamp(offset[k] + delta, olo, ohi);
+    }
+    const corr = Math.max(...['r', 'g', 'b'].map((k) => Math.max(Math.abs(gain[k] - 1), Math.abs(offset[k]))));
+    const drxPath = `${opts.outDir}/${c.id}_matchref.drx`;
+    await generateAssertedAffineDRX(
+      gain,
+      offset,
+      provenanceLabel('match_to_reference', { source: `ref:${refPath.split('/').pop()}`, gist: gist('gain', gain) }),
+      drxPath,
+      warnings,
+    );
+    grades.push({ id: c.id, gain, offset, correctionPct: +(100 * corr).toFixed(2), skinGated: ref.gated, lumaPreserve, drxPath });
+    report[c.id] = { correctionPct: +(100 * corr).toFixed(2), skinGated: ref.gated };
+    if (corr > 0.35)
+      warnings.push(
+        `${c.id}: large correction ${(100 * corr).toFixed(0)}% — target/reference content may differ too much; review (a trim, not a cross-IDT reconciler).`,
+      );
+  }
+  return { grades, report, warnings, skipped };
+}

package/resolve-advanced/server/media-inventory.mjs

@@ -0,0 +1,169 @@
+/**
+ * Cluster M — media_inventory (ffprobe) + sync (TC/waveform). Turns cards/turnovers into a
+ * manifest and a consistency report; pairs picture↔sound by timecode with drift + MOS flags.
+ *
+ * media_inventory: fps/codec/colorspace/TC/audio per file + consistency (mixed fps, wrong-space
+ *   metadata, card-sequence gaps). Deps: ffprobe (peer).
+ * sync: TC-based picture↔sound pairing with per-take offset, long-take drift, and MOS flags.
+ *   PURE over a supplied metadata list (fps + TC in/out); waveform-correlation refinement is a
+ *   documented follow-up (offset from TC is the deterministic core, honest about its scope).
+ *
+ * No Resolve, no LLM.
+ */
+import path from 'node:path';
+import { probeMedia } from './ffprobe-media.mjs';
+
+// ── timecode ───────────────────────────────────────────────────────────
+/** "HH:MM:SS:FF" (or ';' DF) → integer frames at fps. Returns null if unparseable. */
+export function tcToFrames(tc, fps) {
+  if (typeof tc !== 'string' || !fps) return null;
+  const m = /^(\d{1,2}):(\d{2}):(\d{2})[:;](\d{2,3})$/.exec(tc.trim());
+  if (!m) return null;
+  const [, h, mm, s, f] = m.map(Number);
+  return Math.round((h * 3600 + mm * 60 + s) * fps) + f;
+}
+
+export function framesToTc(frames, fps) {
+  if (!fps) return null;
+  const fpsI = Math.round(fps);
+  const f = frames % fpsI;
+  const totalSec = Math.floor(frames / fpsI);
+  const s = totalSec % 60;
+  const mm = Math.floor(totalSec / 60) % 60;
+  const h = Math.floor(totalSec / 3600);
+  const p2 = (n) => String(n).padStart(2, '0');
+  return `${p2(h)}:${p2(mm)}:${p2(s)}:${p2(f)}`;
+}
+
+// ── media_inventory ────────────────────────────────────────────────────
+// Reel/clip parse for card-gap detection, e.g. A001C012, A001_C012, A001 C012.
+const REEL_CLIP_RE = /([A-Z]\d{2,3})[_ ]?C(\d{2,4})/i;
+
+/**
+ * @param {Array<{id?:string, path:string, expectedColorspace?:string}>} files
+ * @param {{ffprobe?:string}} [opts]
+ */
+export function mediaInventory(files, opts = {}) {
+  const items = [];
+  const skipped = [];
+  for (const f of files) {
+    const p = typeof f === 'string' ? f : f.path;
+    const probe = probeMedia(p, opts);
+    if (!probe) {
+      skipped.push({ path: p, reason: 'unreadable / not media' });
+      continue;
+    }
+    const v = probe.video || {};
+    const a0 = (probe.audio || [])[0] || {};
+    items.push({
+      id: (typeof f === 'object' && f.id) || path.basename(p),
+      name: path.basename(p),
+      fps: v.fps || null,
+      codec: v.codec || null,
+      width: v.width || null,
+      height: v.height || null,
+      colorTransfer: v.colorTransfer || null,
+      colorPrimaries: v.colorPrimaries || null,
+      colorMatrix: v.colorMatrix || null,
+      timecode: probe.format.timecode || null,
+      audioChannels: (probe.audio || []).reduce((n, a) => n + (a.channels || 0), 0),
+      audioSampleRate: a0.sampleRate || null,
+      duration: probe.format.duration,
+      expectedColorspace: (typeof f === 'object' && f.expectedColorspace) || null,
+    });
+  }
+  // Consistency.
+  const distinct = (key) => [...new Set(items.map((i) => i[key]).filter((x) => x != null))];
+  const fpsSet = distinct('fps');
+  const warnings = [];
+  if (fpsSet.length > 1) warnings.push(`mixed frame rates across cards: ${fpsSet.join(', ')}`);
+  for (const it of items) {
+    if (it.expectedColorspace && it.colorTransfer && it.colorTransfer !== 'unknown' && it.colorTransfer.toLowerCase() !== it.expectedColorspace.toLowerCase())
+      warnings.push(`${it.name}: color transfer '${it.colorTransfer}' ≠ expected '${it.expectedColorspace}'`);
+    if (it.audioChannels === 0) warnings.push(`${it.name}: no audio channels (MOS?)`);
+  }
+  // Card-sequence gaps.
+  const byReel = new Map();
+  for (const it of items) {
+    const m = REEL_CLIP_RE.exec(it.name);
+    if (!m) continue;
+    const reel = m[1].toUpperCase();
+    const clip = Number(m[2]);
+    if (!byReel.has(reel)) byReel.set(reel, []);
+    byReel.get(reel).push(clip);
+  }
+  const cardGaps = [];
+  for (const [reel, nums] of byReel) {
+    nums.sort((a, b) => a - b);
+    const missing = [];
+    for (let n = nums[0]; n <= nums[nums.length - 1]; n++) if (!nums.includes(n)) missing.push(n);
+    if (missing.length) cardGaps.push({ reel, present: nums, missing });
+  }
+  if (cardGaps.length) warnings.push(`card-sequence gaps: ${cardGaps.map((g) => `${g.reel}[${g.missing.join(',')}]`).join(' ')}`);
+
+  return {
+    count: items.length,
+    items,
+    consistency: { frameRates: fpsSet, codecs: distinct('codec'), colorTransfers: distinct('colorTransfer'), mixedFps: fpsSet.length > 1, cardGaps },
+    warnings,
+    skipped,
+  };
+}
+
+// ── sync (TC-based) ────────────────────────────────────────────────────
+/**
+ * Pair picture↔sound by timecode overlap; per-take offset + long-take drift + MOS flags. PURE.
+ * @param {Array<{id, type:'picture'|'sound', tcStart:string, tcEnd?:string, fps:number, hasAudio?:boolean, durationFrames?:number}>} clips
+ * @param {{driftToleranceFrames?:number, longTakeFrames?:number}} [opts]
+ */
+export function syncByTC(clips, opts = {}) {
+  const driftTol = opts.driftToleranceFrames ?? 2;
+  const longTake = opts.longTakeFrames ?? 3600; // ~2min @30 → "long take" where drift matters
+  const pics = clips.filter((c) => c.type === 'picture');
+  const sounds = clips.filter((c) => c.type === 'sound');
+  const spanOf = (c) => {
+    const start = tcToFrames(c.tcStart, c.fps);
+    if (start == null) return null;
+    const len = c.durationFrames ?? (c.tcEnd ? tcToFrames(c.tcEnd, c.fps) - start : null);
+    return { start, end: len != null ? start + len : null, len };
+  };
+  const pairs = [];
+  const mos = [];
+  const usedSound = new Set();
+  for (const pic of pics) {
+    const ps = spanOf(pic);
+    if (pic.hasAudio === false || !sounds.length) {
+      if (pic.hasAudio === false) mos.push({ id: pic.id, reason: 'flagged MOS (no sync audio)' });
+    }
+    // Find the sound whose TC span overlaps the most.
+    let best = null,
+      bestOverlap = -1;
+    for (const snd of sounds) {
+      if (usedSound.has(snd.id)) continue;
+      const ss = spanOf(snd);
+      if (!ps || !ss || ps.end == null || ss.end == null) continue;
+      const overlap = Math.min(ps.end, ss.end) - Math.max(ps.start, ss.start);
+      if (overlap > bestOverlap) {
+        bestOverlap = overlap;
+        best = { snd, ss };
+      }
+    }
+    if (best && bestOverlap > 0) {
+      usedSound.add(best.snd.id);
+      const offsetFrames = best.ss.start - ps.start;
+      // Drift: on a long take, a length mismatch beyond tol suggests clock drift / pulldown slip.
+      let drift = null;
+      if (ps.len != null && best.ss.len != null) {
+        const lenDelta = best.ss.len - ps.len;
+        const isLong = Math.max(ps.len, best.ss.len) >= longTake;
+        drift = { lenDeltaFrames: lenDelta, longTake: isLong, flagged: Math.abs(lenDelta) > driftTol && isLong };
+      }
+      pairs.push({ picture: pic.id, sound: best.snd.id, offsetFrames, drift });
+    } else if (pic.hasAudio !== false) {
+      mos.push({ id: pic.id, reason: 'no overlapping sound found (guide-track only / MOS?)' });
+    }
+  }
+  const unmatchedSound = sounds.filter((s) => !usedSound.has(s.id)).map((s) => s.id);
+  const driftFlags = pairs.filter((p) => p.drift && p.drift.flagged).map((p) => p.picture);
+  return { pairs, mos, unmatchedSound, driftFlags, note: 'TC-based pairing (deterministic). Waveform cross-correlation is a follow-up refinement.' };
+}

package/resolve-advanced/server/media-ops.mjs

@@ -0,0 +1,243 @@
+/**
+ * Cluster M — media front-end / AE ops (the recurring-show time sink). fs-based + deterministic;
+ * the ffprobe-backed inventory/sync live in media-inventory.mjs.
+ *
+ * Silent-lie discipline extends to MEDIA here (cross-craft review): assert bytes-read>0 and
+ * file-count matches (empty-green is the lie); dupe by HASH never by name; NEVER rewrite a
+ * camera-original filename (sidecar/DB only); path-maps scoped per episode (never relink to the
+ * wrong season). Everything is a dry-run PLAN or a VERIFY report — the AE approves the apply.
+ *
+ *   ingest_verify   — seal (hash manifest / MHL-like) / verify / dupes-by-hash
+ *   relink_manifest — offline-media + path-map PREFLIGHT (dry-run)
+ *   rename_plan     — dry-run rename plan; refuses camera originals
+ *   reel_normalize  — normalize reel/card names to a convention (plan + collisions)
+ *   project_hygiene — dupes, orphan/offline clips, mixed-fps timelines, empty bins, unlabeled versions
+ *   turnover_package— assemble + checksum a dated color/sound/VFX folder manifest (dry-run)
+ *
+ * No Resolve, no LLM.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { checksumFile } from './render-manifest.mjs';
+
+// ── ingest_verify ──────────────────────────────────────────────────────
+/** Seal a set of files into a hash manifest (MHL-like). Asserts every file has bytes>0. */
+export function sealFiles(files, opts = {}) {
+  const entries = [];
+  const missing = [];
+  for (const f of files) {
+    const p = typeof f === 'string' ? f : f.path;
+    if (!fs.existsSync(p)) {
+      missing.push(p);
+      continue;
+    }
+    const { sha256, size } = checksumFile(p);
+    entries.push({ name: path.basename(p), path: p, sha256, size });
+  }
+  const totalBytes = entries.reduce((n, e) => n + e.size, 0);
+  return { version: 1, hashType: 'sha256', count: entries.length, totalBytes, files: entries, missing, sealedFrom: opts.label || null };
+}
+
+/** Verify files against a prior seal. Reports ok/missing/changed per file + copy-completeness. */
+export function verifyFiles(manifest, opts = {}) {
+  const results = [];
+  for (const e of manifest.files || []) {
+    const p = opts.baseDir ? path.join(opts.baseDir, e.name) : e.path;
+    if (!fs.existsSync(p)) {
+      results.push({ name: e.name, status: 'missing', pass: false });
+      continue;
+    }
+    const { sha256, size } = checksumFile(p);
+    const ok = sha256 === e.sha256 && size === e.size;
+    results.push({ name: e.name, status: ok ? 'ok' : 'changed', pass: ok, ...(ok ? {} : { expectedSha: e.sha256, actualSha: sha256 }) });
+  }
+  const failed = results.filter((r) => !r.pass);
+  return {
+    pass: failed.length === 0,
+    verified: results.length,
+    expected: (manifest.files || []).length,
+    complete: results.length === (manifest.files || []).length,
+    results,
+    failed: failed.map((r) => r.name),
+  };
+}
+
+/** Find duplicate CONTENT (same hash, any name) across a file set. */
+export function findDupesByHash(files) {
+  const byHash = new Map();
+  for (const f of files) {
+    const p = typeof f === 'string' ? f : f.path;
+    if (!fs.existsSync(p)) continue;
+    const { sha256 } = checksumFile(p);
+    if (!byHash.has(sha256)) byHash.set(sha256, []);
+    byHash.get(sha256).push(path.basename(p));
+  }
+  const dupes = [...byHash.entries()].filter(([, names]) => names.length > 1).map(([sha256, names]) => ({ sha256, names }));
+  return { dupeGroups: dupes.length, dupes };
+}
+
+export function ingestVerify(mode, args = {}) {
+  if (mode === 'seal') return sealFiles(args.files || [], { label: args.label });
+  if (mode === 'verify') return verifyFiles(args.manifest, { baseDir: args.baseDir });
+  if (mode === 'dupes') return findDupesByHash(args.files || []);
+  throw new Error(`ingest_verify: unknown mode '${mode}' (seal|verify|dupes)`);
+}
+
+// ── relink_manifest ────────────────────────────────────────────────────
+/**
+ * Preflight offline media against a path-map (dry-run). path-maps are SCOPED PER EPISODE by
+ * the caller — never a global relink. Longest-prefix wins; multiple matches → ambiguous.
+ * @param {string[]} offlinePaths
+ * @param {Array<{from:string, to:string}>} pathMap prefix rewrites
+ */
+export function relinkManifest(offlinePaths, pathMap = [], opts = {}) {
+  const maps = [...pathMap].sort((a, b) => b.from.length - a.from.length);
+  const relinkable = [];
+  const stillOffline = [];
+  const ambiguous = [];
+  const unmapped = [];
+  for (const src of offlinePaths) {
+    const matches = maps.filter((m) => src.startsWith(m.from));
+    if (!matches.length) {
+      unmapped.push(src);
+      continue;
+    }
+    if (matches.length > 1 && matches[0].from.length === matches[1].from.length) {
+      ambiguous.push({ from: src, candidates: matches.map((m) => m.from) });
+      continue;
+    }
+    const m = matches[0];
+    const target = src.replace(m.from, m.to);
+    if (opts.checkExists === false || fs.existsSync(target)) relinkable.push({ from: src, to: target, verified: opts.checkExists !== false });
+    else stillOffline.push({ from: src, to: target, reason: 'target does not exist' });
+  }
+  return { total: offlinePaths.length, relinkableCount: relinkable.length, relinkable, stillOffline, ambiguous, unmapped };
+}
+
+// ── rename_plan / reel_normalize ───────────────────────────────────────
+// A camera-original if its name matches common camera patterns, unless the caller says otherwise.
+const CAMERA_ORIGINAL_RE = /^([A-Z]\d{3}[_ ]?[CR]\d{3,4}|[A-Z]\d{3}_\d{8}_C\d+|MVI_\d+|DSC\d+|[A-Z]{2,4}_?\d{4,})/i;
+
+/**
+ * Dry-run rename plan (regex find/replace). REFUSES camera originals (sidecar/DB only).
+ * @param {string[]} names basenames to rename
+ * @param {{find:string, replace:string, allowCameraOriginals?:boolean, cameraOriginalRe?:RegExp}} rule
+ */
+export function renamePlan(names, rule = {}) {
+  let re;
+  try {
+    re = new RegExp(rule.find, 'g');
+  } catch {
+    throw new Error(`rename_plan: invalid find regex '${rule.find}'`);
+  }
+  const camRe = rule.cameraOriginalRe || CAMERA_ORIGINAL_RE;
+  const plan = [];
+  const targets = new Map();
+  for (const name of names) {
+    const isCam = camRe.test(name);
+    if (isCam && !rule.allowCameraOriginals) {
+      plan.push({ from: name, action: 'refuse-camera-original', note: 'camera original — rename via sidecar/DB only, never the file' });
+      continue;
+    }
+    const to = name.replace(re, rule.replace ?? '');
+    if (to === name) {
+      plan.push({ from: name, to, action: 'noop' });
+      continue;
+    }
+    targets.set(to, (targets.get(to) || 0) + 1);
+    plan.push({ from: name, to, action: 'rename' });
+  }
+  // Flag collisions (two sources → one target).
+  for (const p of plan) if (p.action === 'rename' && targets.get(p.to) > 1) p.action = 'collision';
+  const collisions = plan.filter((p) => p.action === 'collision');
+  return {
+    plan,
+    renameCount: plan.filter((p) => p.action === 'rename').length,
+    refused: plan.filter((p) => p.action === 'refuse-camera-original').length,
+    collisions: collisions.length,
+    dryRun: true,
+  };
+}
+
+/** Normalize reel/card names to a convention (uppercase + zero-pad the trailing number). */
+export function reelNormalize(reels, opts = {}) {
+  const pad = opts.pad ?? 3;
+  const plan = [];
+  const targets = new Map();
+  for (const r of reels) {
+    const to = String(r)
+      .toUpperCase()
+      .replace(/(\d+)\s*$/, (m) => m.padStart(pad, '0'));
+    if (to !== r) targets.set(to, (targets.get(to) || 0) + 1);
+    plan.push({ from: r, to, action: to === r ? 'noop' : 'normalize' });
+  }
+  for (const p of plan) if (p.action === 'normalize' && targets.get(p.to) > 1) p.action = 'collision';
+  return { plan, normalizeCount: plan.filter((p) => p.action === 'normalize').length, collisions: plan.filter((p) => p.action === 'collision').length };
+}
+
+// ── project_hygiene ────────────────────────────────────────────────────
+/**
+ * Report project hygiene issues over a supplied structure (the live server reports it; Node judges).
+ * @param {{clips?:Array, timelines?:Array, bins?:Array, versions?:Array}} project
+ */
+export function projectHygiene(project = {}) {
+  const clips = project.clips || [];
+  const offlineClips = clips.filter((c) => c.online === false).map((c) => c.id);
+  // Dupes by hash (fallback path) — never by name alone.
+  const byHash = new Map();
+  for (const c of clips) {
+    const key = c.hash || c.path;
+    if (key == null) continue;
+    if (!byHash.has(key)) byHash.set(key, []);
+    byHash.get(key).push(c.id);
+  }
+  const dupes = [...byHash.entries()].filter(([, ids]) => ids.length > 1).map(([key, ids]) => ({ key, ids }));
+  const mixedFpsTimelines = (project.timelines || [])
+    .filter((t) => {
+      const fpsSet = new Set([...(t.clipFps || [])]);
+      if (t.fps != null) for (const f of t.clipFps || []) if (f !== t.fps) fpsSet.add(f);
+      return fpsSet.size > 1;
+    })
+    .map((t) => t.name);
+  const emptyBins = (project.bins || []).filter((b) => (b.clipCount ?? 0) === 0).map((b) => b.name);
+  const unlabeledVersions = (project.versions || []).filter((v) => !v.label).map((v) => v.name);
+  const findings = { offlineClips, dupes, mixedFpsTimelines, emptyBins, unlabeledVersions };
+  const issueCount = offlineClips.length + dupes.length + mixedFpsTimelines.length + emptyBins.length + unlabeledVersions.length;
+  return { clean: issueCount === 0, issueCount, findings, gate: 'review' };
+}
+
+// ── turnover_package ───────────────────────────────────────────────────
+/**
+ * Assemble a dated turnover package MANIFEST (dry-run — checksums existing files, plans the
+ * folder). Handles + reference are recorded, not enforced here.
+ * @param {Array<{path:string, category:'color'|'sound'|'vfx'|'reference', role?:string}>} inputs
+ * @param {{date?:string, name?:string, handles?:number}} opts  date = 'YYYYMMDD' (caller-supplied; deterministic)
+ */
+export function turnoverPackage(inputs, opts = {}) {
+  const date = opts.date || 'UNDATED';
+  const name = opts.name || 'turnover';
+  const folder = `${date}_${name}_TransferFiles`;
+  const categories = {};
+  let totalBytes = 0;
+  const missing = [];
+  for (const it of inputs) {
+    if (!fs.existsSync(it.path)) {
+      missing.push(it.path);
+      continue;
+    }
+    const { sha256, size } = checksumFile(it.path);
+    const cat = it.category || 'other';
+    (categories[cat] ||= []).push({ name: path.basename(it.path), path: it.path, role: it.role || null, sha256, size });
+    totalBytes += size;
+  }
+  return {
+    folder,
+    handles: opts.handles ?? null,
+    categories,
+    fileCount: Object.values(categories).reduce((n, a) => n + a.length, 0),
+    totalBytes,
+    missing,
+    dryRun: true,
+    gate: 'review',
+  };
+}

package/resolve-advanced/server/node-meta-db.mjs

@@ -0,0 +1,62 @@
+/**
+ * node-meta-db — set/clear a graded node's LABEL (F6) + COLOR (F15) directly in a live Project.db,
+ * via the surgical grade-Body patcher (no UI, no lossy generator). Node-convention/provenance spec.
+ *
+ * Mirrors offline-ref-db.mjs: project-CLOSED gate → auto-backup → schema guard → UPDATE → read-back verify.
+ * Resolve oversaves an open project, so the project MUST be closed in Resolve before patching.
+ *
+ * Join (RE'd 2026-06-22): Sm2TiItem.pLmVerTable → "ListMgt::LmVersion"(HasCorrection='1').Body, scoped to a
+ * timeline via Sm2TiTrack.Sequence → Sm2Sequence.Sm2Timeline_id → Sm2Timeline.Name. Body is a BLOB.
+ */
+
+import { loadSqlite, resolveDbPath, openGuarded, backup as backupDb, requireClosed } from './db-patch.mjs';
+import { patchGradeBody, readNodeMeta } from './grade-body-patch.mjs';
+
+const FIND_GRADE_SQL = `
+ SELECT v.rowid AS vid, lower(hex(v.Body)) AS body, i.Name AS clip
+ FROM Sm2TiItem i
+ JOIN Sm2TiTrack t ON i.Sm2TiTrack_id = t.Sm2TiTrack_id
+ JOIN Sm2Sequence s ON t.Sequence = s.Sm2Sequence_id
+ JOIN Sm2Timeline tl ON s.Sm2Timeline_id = tl.Sm2Timeline_id
+ JOIN "ListMgt::LmVersion" v ON v."ListMgt::LmVersionTable_id" = i.pLmVerTable AND v.HasCorrection = '1'
+ WHERE tl.Name = ? AND t.Type = 0
+ ORDER BY i.Start ASC`;
+
+/**
+ * Set/clear a graded node's label/color in a project's timeline.
+ * @param {object} opts
+ * @param {string} [opts.projectDb] absolute Project.db path (or use projectName)
+ * @param {string} [opts.projectName] disk-DB project name (resolved to its Project.db)
+ * @param {string} opts.timeline timeline name
+ * @param {number} [opts.nodeIndex=0] node to edit
+ * @param {string|null} [opts.label] undefined=leave · null=clear · string=set
+ * @param {string|null} [opts.color] undefined=leave · null=clear · string=set (e.g. "Blue")
+ * @param {boolean} opts.iConfirmProjectClosed REQUIRED true — Resolve oversaves an open project
+ * @param {boolean} [opts.backup=true]
+ */
+export async function setNodeLabelColorInProject(opts) {
+  const { timeline, nodeIndex = 0, label, color, backup = true } = opts;
+  requireClosed(opts);
+  if (label === undefined && color === undefined) throw new Error('nothing to do: provide label and/or color');
+  const dbPath = resolveDbPath(opts);
+  const bak = backup ? backupDb(dbPath) : null;
+  const db = openGuarded(dbPath, { writable: true, table: 'ListMgt::LmVersion', column: 'Body' });
+  try {
+    const rows = db.prepare(FIND_GRADE_SQL).all(timeline);
+    if (!rows.length) throw new Error(`no graded clip (HasCorrection=1) on timeline "${timeline}" — apply a grade first`);
+    const target = rows[0];
+    const before = readNodeMeta(target.body, nodeIndex);
+    const newHex = await patchGradeBody(target.body, nodeIndex, { label, color });
+    db.prepare('UPDATE "ListMgt::LmVersion" SET Body = ? WHERE rowid = ?').run(Buffer.from(newHex, 'hex'), target.vid);
+    // read-back verify
+    const after = db.prepare('SELECT lower(hex(Body)) AS body FROM "ListMgt::LmVersion" WHERE rowid = ?').get(target.vid);
+    const meta = readNodeMeta(after.body, nodeIndex);
+    const want = (v, got) => (v === undefined ? true : v === null ? got == null : got === v);
+    const verified = want(label, meta.label) && want(color, meta.color);
+    return { projectDb: dbPath, backup: bak, clip: target.clip, version: target.vid, nodeIndex, before, after: meta, verified };
+  } finally {
+    db.close();
+  }
+}
+
+export { loadSqlite };