npm - davinci-resolve-mcp - Versions diffs - 2.57.4 → 2.58.0 - Mend

davinci-resolve-mcp 2.57.4 → 2.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (328) hide show

package/resolve-advanced/vendor/drp-format/__tests__/diff.test.js ADDED Viewed

@@ -0,0 +1,272 @@
+/**
+ * P0.2 — diff(drpA, drpB) unit tests.
+ *
+ * Strategy: build synthetic DRPs via buildDRP with controlled deltas
+ * between them, then assert the resulting DTO captures each delta in
+ * the right bucket without false positives.
+ *
+ * Run: node --test packages/drp-format/__tests__/diff.test.js
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const JSZip = require('jszip');
+const drpFormat = require('..');
+const BODY_A = '80aaaaaaaaaaaaaaaa';
+const BODY_B = '80bbbbbbbbbbbbbbbb';
+const BODY_C = '80cccccccccccccccc';
+async function buildTwoClipDrp(outPath, clipSpecs) {
+  const buf = await drpFormat.buildDRP({
+    projectName: 'diff-test',
+    timelines: [{
+      name: 'T1',
+      frameRate: 24,
+      startTimecode: '01:00:00:00',
+      resolution: '1920x1080',
+      videoTracks: [{
+        clips: clipSpecs,
+      }],
+      audioTracks: [],
+    }],
+  });
+  await fs.writeFile(outPath, buf);
+}
+async function readClipIds(drpPath) {
+  // Use the diff module's indexer to discover the auto-generated DbIds.
+  const idx = await drpFormat.diff && (await drpFormat._diffInternals.indexDrp(drpPath));
+  return [...idx.clipsById.keys()];
+}
+// Expose internals for the tests without polluting the public API.
+drpFormat._diffInternals = require('../diff')._internals;
+test('diff: identical DRPs report no changes', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'drp-diff-'));
+  try {
+    const drpA = path.join(tmp, 'a.drp');
+    const drpB = path.join(tmp, 'b.drp');
+    const specs = [
+      { start: 0,  duration: 24, in: 0, mediaFilePath: '/m/clip1.mov', grade: { body: BODY_A, hasCorrection: true } },
+      { start: 24, duration: 24, in: 0, mediaFilePath: '/m/clip2.mov', grade: { body: BODY_B, hasCorrection: true } },
+    ];
+    await buildTwoClipDrp(drpA, specs);
+    // Build B from the same spec object (separate buildDRP run = different
+    // auto-generated UUIDs — so identical CONTENT will produce
+    // added/removed pairs). Cheat the test: copy A bytes-for-bytes to get
+    // identical DbIds. That's how a real "compare X against itself" call
+    // would look anyway.
+    await fs.copyFile(drpA, drpB);
+    const result = await drpFormat.diff(drpA, drpB);
+    assert.equal(result.summary.hasAnyChange, false);
+    assert.equal(result.addedClips.length, 0);
+    assert.equal(result.removedClips.length, 0);
+    assert.equal(result.movedClips.length, 0);
+    assert.equal(result.gradeChanges.length, 0);
+    assert.equal(result.timelineSettingDeltas.length, 0);
+    assert.equal(result.mediaPoolDeltas.added.length, 0);
+    assert.equal(result.mediaPoolDeltas.removed.length, 0);
+    assert.equal(result.summary.sameClipCount, 2);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('diff: grade change on one clip is detected, other clip unchanged', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'drp-diff-'));
+  try {
+    const drpA = path.join(tmp, 'a.drp');
+    const drpB = path.join(tmp, 'b.drp');
+    const specs = [
+      { start: 0,  duration: 24, in: 0, mediaFilePath: '/m/clip1.mov', grade: { body: BODY_A, hasCorrection: true } },
+      { start: 24, duration: 24, in: 0, mediaFilePath: '/m/clip2.mov', grade: { body: BODY_B, hasCorrection: true } },
+    ];
+    await buildTwoClipDrp(drpA, specs);
+    await fs.copyFile(drpA, drpB);
+    // Mutate clip 1 in B via injectGrades to BODY_C — preserves DbIds.
+    const idsB = await readClipIds(drpB);
+    const drxFor = (hex) => `<x><Body>${hex}</Body></x>`;
+    await drpFormat.injectGrades(drpB, [
+      { clipId: idsB[0], drxContent: drxFor(BODY_C) },
+    ]);
+    const result = await drpFormat.diff(drpA, drpB);
+    assert.equal(result.summary.hasAnyChange, true);
+    assert.equal(result.addedClips.length, 0);
+    assert.equal(result.removedClips.length, 0);
+    assert.equal(result.movedClips.length, 0);
+    assert.equal(result.gradeChanges.length, 1);
+    const g = result.gradeChanges[0];
+    assert.equal(g.clipId, idsB[0]);
+    assert.equal(g.hadGrade, true);
+    assert.equal(g.hasGrade, true);
+    assert.notEqual(g.beforeBodyHash, g.afterBodyHash);
+    assert.ok(g.beforeBodyHash && /^[0-9a-f]{64}$/.test(g.beforeBodyHash));
+    assert.ok(g.afterBodyHash && /^[0-9a-f]{64}$/.test(g.afterBodyHash));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('diff: clip added in B surfaces in addedClips with no grade-change false positive', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'drp-diff-'));
+  try {
+    const drpA = path.join(tmp, 'a.drp');
+    const drpB = path.join(tmp, 'b.drp');
+    await buildTwoClipDrp(drpA, [
+      { start: 0, duration: 24, in: 0, mediaFilePath: '/m/clip1.mov', grade: { body: BODY_A, hasCorrection: true } },
+    ]);
+    await buildTwoClipDrp(drpB, [
+      { start: 0,  duration: 24, in: 0, mediaFilePath: '/m/clip1.mov', grade: { body: BODY_A, hasCorrection: true } },
+      { start: 24, duration: 24, in: 0, mediaFilePath: '/m/clip2.mov', grade: { body: BODY_B, hasCorrection: true } },
+    ]);
+    const result = await drpFormat.diff(drpA, drpB);
+    // Because A and B were built independently, every DbId differs — A's
+    // clip 1 is "removed", B's both clips are "added". That's correct per
+    // the schema: identity is DbId, not media path. A more sophisticated
+    // similarity layer is future work.
+    assert.equal(result.summary.hasAnyChange, true);
+    assert.equal(result.removedClips.length, 1);
+    assert.equal(result.addedClips.length, 2);
+    assert.equal(result.gradeChanges.length, 0);
+    // Media-pool diff catches the new file.
+    assert.ok(result.mediaPoolDeltas.added.includes('/m/clip2.mov'));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('diff: same DbIds, clip 1 moved in B → movedClips, gradeChanges empty', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'drp-diff-'));
+  try {
+    const drpA = path.join(tmp, 'a.drp');
+    const drpB = path.join(tmp, 'b.drp');
+    const specs = [
+      { start: 0,  duration: 24, in: 0, mediaFilePath: '/m/clip1.mov', grade: { body: BODY_A, hasCorrection: true } },
+      { start: 24, duration: 24, in: 0, mediaFilePath: '/m/clip2.mov', grade: { body: BODY_B, hasCorrection: true } },
+    ];
+    await buildTwoClipDrp(drpA, specs);
+    await fs.copyFile(drpA, drpB);
+    // Mutate the START frame of clip 1 in B's SeqContainer XML directly
+    // (the only way to simulate "moved" while preserving DbIds —
+    // injectGrades only touches <Body>).
+    await mutateClipStart(drpB, /* clipIndex */ 0, /* newStart */ 100);
+    const result = await drpFormat.diff(drpA, drpB);
+    assert.equal(result.movedClips.length, 1);
+    const move = result.movedClips[0];
+    assert.equal(move.before.start, 0);
+    assert.equal(move.after.start, 100);
+    assert.equal(result.gradeChanges.length, 0,
+      'a pure move should not falsely report a grade change');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('diff: timeline settings delta surfaces project-level differences', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'drp-diff-'));
+  try {
+    const drpA = path.join(tmp, 'a.drp');
+    const drpB = path.join(tmp, 'b.drp');
+    await buildTwoClipDrp(drpA, [
+      { start: 0, duration: 24, in: 0, mediaFilePath: '/m/c.mov', grade: { body: BODY_A } },
+    ]);
+    // Mutate B's project.xml to change ProjectName.
+    await fs.copyFile(drpA, drpB);
+    await mutateProjectName(drpB, 'diff-test-renamed');
+    const result = await drpFormat.diff(drpA, drpB);
+    const nameDelta = result.timelineSettingDeltas.find((d) => d.key === 'projectName');
+    assert.ok(nameDelta, 'projectName delta should be reported');
+    assert.equal(nameDelta.before, 'diff-test');
+    assert.equal(nameDelta.after, 'diff-test-renamed');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('diff: internals.extractClips finds clips even when body absent', () => {
+  const xml = `
+    <Sm2TiVideoTrack DbId="t">
+      <Sm2TiVideoClip DbId="clip-1">
+        <Start>0</Start>
+        <Duration>24</Duration>
+        <MediaFilePath>/m/a.mov</MediaFilePath>
+      </Sm2TiVideoClip>
+      <Sm2TiVideoClip DbId="clip-2">
+        <Start>24</Start>
+        <Duration>24</Duration>
+        <MediaFilePath>/m/b.mov</MediaFilePath>
+        <Body>80aabb</Body>
+      </Sm2TiVideoClip>
+    </Sm2TiVideoTrack>
+  `;
+  const clips = drpFormat._diffInternals.extractClips(xml);
+  assert.equal(clips.length, 2);
+  assert.equal(clips[0].clipId, 'clip-1');
+  assert.equal(clips[0].bodyHex, null);
+  assert.equal(clips[0].start, 0);
+  assert.equal(clips[1].clipId, 'clip-2');
+  assert.equal(clips[1].bodyHex, '80aabb');
+});
+test('diff: rejects non-string arguments', async () => {
+  await assert.rejects(() => drpFormat.diff(123, '/tmp/x'), /must be strings/);
+  await assert.rejects(() => drpFormat.diff('/tmp/x', null), /must be strings/);
+});
+// ─── helpers that mutate a DRP zip in-place ─────────────────────────────
+async function mutateClipStart(drpPath, clipIndex, newStart) {
+  const buf = await fs.readFile(drpPath);
+  const zip = await JSZip.loadAsync(buf);
+  let seqEntry = null;
+  zip.forEach((p, e) => { if (!e.dir && /(^|\/)SeqContainer\d*\.xml$/.test(p)) seqEntry = p; });
+  let xml = await zip.file(seqEntry).async('string');
+  // Replace the Nth Sm2TiVideoClip's <Start> value.
+  const clipRe = /<Sm2TiVideoClip\b([\s\S]*?)<\/Sm2TiVideoClip>/g;
+  let m, i = 0, replaced = false;
+  while ((m = clipRe.exec(xml)) !== null) {
+    if (i === clipIndex) {
+      const clipBlock = m[0];
+      const newClipBlock = clipBlock.replace(/<Start>[^<]*<\/Start>/, `<Start>${newStart}</Start>`);
+      xml = xml.slice(0, m.index) + newClipBlock + xml.slice(m.index + clipBlock.length);
+      replaced = true;
+      break;
+    }
+    i += 1;
+  }
+  if (!replaced) throw new Error('mutateClipStart: no matching clip');
+  zip.file(seqEntry, xml);
+  const outBuf = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  await fs.writeFile(drpPath, outBuf);
+}
+async function mutateProjectName(drpPath, newName) {
+  const buf = await fs.readFile(drpPath);
+  const zip = await JSZip.loadAsync(buf);
+  let projEntry = null;
+  zip.forEach((p, e) => { if (!e.dir && /(^|\/)project\.xml$/.test(p)) projEntry = p; });
+  let xml = await zip.file(projEntry).async('string');
+  // tool-authored DRPs use <Name>; Resolve-exported variants may
+  // use <ProjectName>. Match either.
+  const before = xml;
+  xml = xml
+    .replace(/<ProjectName>[^<]*<\/ProjectName>/, `<ProjectName>${newName}</ProjectName>`)
+    .replace(/<Name>[^<]*<\/Name>/, `<Name>${newName}</Name>`);
+  if (xml === before) throw new Error('mutateProjectName: no project-name tag found to mutate');
+  zip.file(projEntry, xml);
+  const outBuf = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  await fs.writeFile(drpPath, outBuf);
+}

package/resolve-advanced/vendor/drp-format/__tests__/effect-filters-compressed.test.js ADDED Viewed

@@ -0,0 +1,143 @@
+/**
+ * P0.3 — Compressed EffectFiltersBA decoder.
+ *
+ * Resolve 21 finding (Session 30): Resolve 21's DRP export writes
+ * `<EffectFiltersBA/>` empty self-closing even when cached ResolveFX
+ * are present. The compressed (0x81) payload path is therefore
+ * **not exercised by any Resolve 21 fixture** in our capture set;
+ * the decoder is implemented for backward compatibility with older
+ * Resolve exports and for any future Resolve version that
+ * re-enables DRP-side caching.
+ *
+ * Synthetic round-trip: take an existing 0x80 (uncompressed) payload
+ * the encoder already produces, zlib-compress it, prefix with 0x81,
+ * wrap with the standard header, and assert the decoder unwinds it
+ * to the same transform parameters. This proves the decoder is
+ * symmetrical with the encoder side, without needing a Resolve
+ * fixture (which doesn't exist today).
+ *
+ * Real-fixture safety check: parse the Session 30 captured DRP
+ * (`<EffectFiltersBA/>` empty) via the project-level path and assert
+ * no throw — the codec must handle the Resolve-21-empty case gracefully.
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const {
+  encodeEffectFiltersBA,
+  decodeEffectFiltersBA,
+} = require('../effect-encoder');
+const FIXTURES = path.join(__dirname, 'fixtures');
+function compressedHexFromUncompressed(uncompressedHex) {
+  const original = Buffer.from(uncompressedHex, 'hex');
+  // The header is 8 bytes (version + payloadSize), payloadType is at
+  // offset 8, payload follows at offset 9.
+  const header = original.slice(0, 8);
+  const payload = original.slice(9);
+  const compressedPayload = zlib.deflateSync(payload);
+  // Rebuild: header + 0x81 + compressed payload
+  // (the payloadSize field in the header technically should reflect
+  // the new compressed size; the decoder doesn't read it strictly so
+  // we leave the original size for now — equivalent of how Resolve's
+  // own files keep the *decompressed* size there).
+  return Buffer.concat([header, Buffer.from([0x81]), compressedPayload]).toString('hex');
+}
+test('decodeEffectFiltersBA: 0x81 compressed payload round-trips a zoom transform', () => {
+  const input = { zoomX: 1.25, zoomY: 1.25 };
+  const uncompressed = encodeEffectFiltersBA(input);
+  const compressed = compressedHexFromUncompressed(uncompressed);
+  // Verify the compressed form actually starts with 0x81 at offset 8.
+  const compressedBuf = Buffer.from(compressed, 'hex');
+  assert.equal(compressedBuf[8], 0x81, 'payload-type byte is 0x81');
+  const decoded = decodeEffectFiltersBA(compressed);
+  assert.ok(Math.abs(decoded.zoomX - 1.25) < 1e-9);
+  assert.ok(Math.abs(decoded.zoomY - 1.25) < 1e-9);
+});
+test('decodeEffectFiltersBA: 0x81 compressed payload round-trips rotation + pan', () => {
+  const input = { rotation: 12.5, panX: 50, panY: -30 };
+  const uncompressed = encodeEffectFiltersBA(input);
+  const compressed = compressedHexFromUncompressed(uncompressed);
+  const decoded = decodeEffectFiltersBA(compressed);
+  assert.ok(Math.abs(decoded.rotation - 12.5) < 1e-9);
+  assert.ok(Math.abs(decoded.panX - 50) < 1e-9);
+  assert.ok(Math.abs(decoded.panY - (-30)) < 1e-9);
+});
+test('decodeEffectFiltersBA: 0x80 uncompressed path still works (regression)', () => {
+  const input = { zoomX: 1.1, rotation: 7 };
+  const encoded = encodeEffectFiltersBA(input);
+  const buf = Buffer.from(encoded, 'hex');
+  assert.equal(buf[8], 0x80, 'encoder default produces 0x80');
+  const decoded = decodeEffectFiltersBA(encoded);
+  assert.ok(Math.abs(decoded.zoomX - 1.1) < 1e-9);
+  assert.ok(Math.abs(decoded.rotation - 7) < 1e-9);
+});
+test('decodeEffectFiltersBA: 0x81 with raw DEFLATE (no zlib header) also works', () => {
+  // Some Resolve versions may use raw DEFLATE instead of zlib-wrapped.
+  // Build a payload prefixed with 0x81 + raw-deflate'd protobuf and
+  // assert the decoder falls back correctly.
+  const input = { zoomX: 1.5 };
+  const uncompressed = Buffer.from(encodeEffectFiltersBA(input), 'hex');
+  const header = uncompressed.slice(0, 8);
+  const payload = uncompressed.slice(9);
+  const rawDeflate = zlib.deflateRawSync(payload);
+  // Raw DEFLATE doesn't start with 0x78 — confirm.
+  assert.notEqual(rawDeflate[0], 0x78,
+    'raw deflate output should not have zlib header byte 0x78');
+  const compressed = Buffer.concat([header, Buffer.from([0x81]), rawDeflate]);
+  const decoded = decodeEffectFiltersBA(compressed.toString('hex'));
+  assert.ok(Math.abs(decoded.zoomX - 1.5) < 1e-9);
+});
+test('decodeEffectFiltersBA: 0x81 with malformed payload surfaces a clear error', () => {
+  // Non-zlib, non-deflate garbage at the 0x81 payload — must throw.
+  const input = { zoomX: 1.0 };
+  const uncompressed = Buffer.from(encodeEffectFiltersBA(input), 'hex');
+  const header = uncompressed.slice(0, 8);
+  const garbage = Buffer.from([0xFF, 0xFE, 0xFD, 0xFC, 0xFB]);
+  const malformed = Buffer.concat([header, Buffer.from([0x81]), garbage]);
+  assert.throws(
+    () => decodeEffectFiltersBA(malformed.toString('hex')),
+    /Failed to decompress EffectFiltersBA/,
+  );
+});
+// ─── Resolve 21 reality check ────────────────────────────────────────────
+test('Session 30 captured DRP carries empty <EffectFiltersBA/> (Resolve 21 finding)', () => {
+  const drpPath = path.join(FIXTURES, 'p0-3-session30-empty-effectfilters.drp');
+  // The fixture is the actual Session 30 capture — confirm the
+  // EffectFiltersBA XML field is empty self-closing, validating the
+  // P0.3 finding that Resolve 21 doesn't write this blob anymore.
+  if (!fs.existsSync(drpPath)) {
+    // Fixture not present in checkout — that's fine; the synthetic
+    // round-trip tests above prove the decoder works. Skip without
+    // failing.
+    return;
+  }
+  const JSZip = require('jszip');
+  return JSZip.loadAsync(fs.readFileSync(drpPath)).then(async (zip) => {
+    const seqEntries = [];
+    zip.forEach((p) => {
+      if (p.startsWith('SeqContainer/') && p.endsWith('.xml')) seqEntries.push(p);
+    });
+    assert.ok(seqEntries.length > 0, 'fixture has a SeqContainer XML');
+    const xml = await zip.file(seqEntries[0]).async('string');
+    // Look for the EffectFiltersBA tag — must be self-closing in
+    // Resolve 21 exports.
+    assert.match(xml, /<EffectFiltersBA\/>/,
+      'Resolve 21 exports EffectFiltersBA as empty self-closing');
+    assert.doesNotMatch(xml, /<EffectFiltersBA>[0-9a-f]/i,
+      'Resolve 21 does NOT inline a hex blob in EffectFiltersBA');
+  });
+});

package/resolve-advanced/vendor/drp-format/__tests__/fixtures/p0-3-session30-empty-effectfilters.drp ADDED Viewed

Binary file

package/resolve-advanced/vendor/drp-format/__tests__/fixtures/retimed-timemap-50pct.hex ADDED Viewed

@@ -0,0 +1 @@

+ 0000000100000007000000080059004d0069006e0000000600bff0000000000000000000080059004d006100780000000600bff0000000000000000000080058004d00610078000000060040731547f3fc2d54000000100055006e0069007100750065004900640000000a000000004800330034003600360032003500610063002d0062003000650033002d0034003700360038002d0038003400310038002d00320037003600340038003300380036003000370030003900000020004c00610073007400560061006c006900640059004f006600660073006500740000000600406314e147ae147b00000016004b00650079006600720061006d00650073004200410000000c0000000017800a000a1209542dfcf34715734011542dfcf3471563400000000c0044006200540079007000650000000a00000000140053006d003200540069006d0065004d00610070

package/resolve-advanced/vendor/drp-format/__tests__/fixtures/retimed-timemap-dynamic.hex ADDED Viewed

@@ -0,0 +1 @@

+ 0000000100000007000000080059004d0069006e0000000600bff0000000000000000000080059004d006100780000000600bff0000000000000000000080058004d00610078000000060040546547f3fc2d54000000100055006e0069007100750065004900640000000a000000004800380064006600360062003300320031002d0064006500660039002d0034006500360033002d0039003400630035002d00640065003900660034006100310034006100300039006400000020004c00610073007400560061006c006900640059004f006600660073006500740000000600406314e147ae147b00000016004b00650079006600720061006d00650073004200410000000c000000002b800a000a1209abaaaaaaaa2a1c4011abaaaaaaaa2a0c400a1209542dfcf34765544011542dfcf3471363400000000c0044006200540079007000650000000a00000000140053006d003200540069006d0065004d00610070

package/resolve-advanced/vendor/drp-format/__tests__/inject-grades.test.js ADDED Viewed

@@ -0,0 +1,238 @@
+/**
+ * P0.1 — injectGrades unit tests.
+ *
+ * Strategy: build a synthetic DRP with two pre-graded clips, scrape their
+ * auto-generated DbIds out of the SeqContainer XML, inject a new <Body>
+ * blob into one of them, and verify (a) the targeted clip's Body changed
+ * to the injected value, (b) the other clip's Body didn't change,
+ * (c) the surrounding XML is otherwise byte-identical.
+ *
+ * Run: node --test packages/drp-format/__tests__/inject-grades.test.js
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const JSZip = require('jszip');
+const drpFormat = require('..');
+const { resolveVerifyTest } = require('./_resolve-verify');
+// A plausible-shaped synthetic body. The injector does not parse the bytes,
+// only substitutes them. Hex characters only.
+const BASELINE_BODY = '80aaaaaaaaaaaaaaaa';
+const ORIGINAL_BODY_CLIP_2 = '80bbbbbbbbbbbbbbbb';
+const INJECTED_BODY = '81cafebabe0102030405060708090a0b0c0d0e0f';
+function makeSyntheticDrx(bodyHex) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<Resolve_Color_Exchange>\n  <Body>${bodyHex}</Body>\n</Resolve_Color_Exchange>\n`;
+}
+async function buildSyntheticDrp(outPath) {
+  const buf = await drpFormat.buildDRP({
+    projectName: 'inject-grades-test',
+    timelines: [{
+      name: 'T1',
+      frameRate: 24,
+      startTimecode: '01:00:00:00',
+      resolution: '1920x1080',
+      videoTracks: [{
+        clips: [
+          {
+            start: 0, duration: 24, in: 0,
+            mediaFilePath: '/synthetic/clip1.mov',
+            grade: { body: BASELINE_BODY, hasCorrection: true, versionName: 'V1' },
+          },
+          {
+            start: 24, duration: 24, in: 0,
+            mediaFilePath: '/synthetic/clip2.mov',
+            grade: { body: ORIGINAL_BODY_CLIP_2, hasCorrection: true, versionName: 'V1' },
+          },
+        ],
+      }],
+      audioTracks: [],
+    }],
+  });
+  await fs.writeFile(outPath, buf);
+  return buf;
+}
+async function readSeqContainer(drpPath) {
+  const buf = await fs.readFile(drpPath);
+  const zip = await JSZip.loadAsync(buf);
+  const seqEntries = [];
+  zip.forEach((p, e) => {
+    if (!e.dir && /(^|\/)SeqContainer\d*\.xml$/.test(p)) seqEntries.push(p);
+  });
+  assert(seqEntries.length > 0, 'synthetic DRP should have at least one SeqContainer');
+  return zip.file(seqEntries[0]).async('string');
+}
+/**
+ * Scrape (DbId, Body) pairs from a built SeqContainer XML. Pulls them in
+ * document order so callers can pick clip 1 / clip 2 deterministically.
+ */
+function scrapeClipBodies(xml) {
+  const pairs = [];
+  const clipRe = /<Sm2TiVideoClip\b[^>]*?DbId="([^"]+)"[\s\S]*?<Body>([0-9a-fA-F]+)<\/Body>[\s\S]*?<\/Sm2TiVideoClip>/g;
+  let m;
+  while ((m = clipRe.exec(xml)) !== null) {
+    pairs.push({ dbId: m[1], body: m[2] });
+  }
+  return pairs;
+}
+test('injectGrades: replaces body of the targeted clip only', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-grades-'));
+  try {
+    const srcDrp = path.join(tmp, 'src.drp');
+    const outDrp = path.join(tmp, 'out.drp');
+    await buildSyntheticDrp(srcDrp);
+    // 1. Discover the auto-generated DbIds + baseline bodies.
+    const beforeXml = await readSeqContainer(srcDrp);
+    const before = scrapeClipBodies(beforeXml);
+    assert.equal(before.length, 2, 'expected exactly two video clips with bodies');
+    assert.equal(before[0].body, BASELINE_BODY);
+    assert.equal(before[1].body, ORIGINAL_BODY_CLIP_2);
+    // 2. Inject into clip 1.
+    const result = await drpFormat.injectGrades(srcDrp, [
+      { clipId: before[0].dbId, drxContent: makeSyntheticDrx(INJECTED_BODY) },
+    ], { outputPath: outDrp });
+    assert.equal(result.clipsInjected, 1);
+    assert.deepEqual(result.misses, []);
+    assert.ok(result.bytes > 0);
+    // 3. Verify the injection landed only on clip 1.
+    const afterXml = await readSeqContainer(outDrp);
+    const after = scrapeClipBodies(afterXml);
+    assert.equal(after.length, 2);
+    assert.equal(after[0].dbId, before[0].dbId);
+    assert.equal(after[1].dbId, before[1].dbId);
+    assert.equal(after[0].body, INJECTED_BODY, 'clip 1 body should be replaced');
+    assert.equal(after[1].body, ORIGINAL_BODY_CLIP_2, 'clip 2 body must be untouched');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('injectGrades: misses report unmatched DbIds', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-grades-'));
+  try {
+    const srcDrp = path.join(tmp, 'src.drp');
+    const outDrp = path.join(tmp, 'out.drp');
+    await buildSyntheticDrp(srcDrp);
+    const result = await drpFormat.injectGrades(srcDrp, [
+      { clipId: 'definitely-not-a-real-dbid', drxContent: makeSyntheticDrx(INJECTED_BODY) },
+    ], { outputPath: outDrp });
+    assert.equal(result.clipsInjected, 0);
+    assert.deepEqual(result.misses, ['definitely-not-a-real-dbid']);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('injectGrades: rejects malformed DRX content', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-grades-'));
+  try {
+    const srcDrp = path.join(tmp, 'src.drp');
+    await buildSyntheticDrp(srcDrp);
+    const beforeXml = await readSeqContainer(srcDrp);
+    const before = scrapeClipBodies(beforeXml);
+    await assert.rejects(
+      () => drpFormat.injectGrades(srcDrp, [
+        { clipId: before[0].dbId, drxContent: '<not-a-drx>nothing here</not-a-drx>' },
+      ], { outputPath: path.join(tmp, 'out.drp') }),
+      /no <Body>HEX<\/Body> block/i,
+    );
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('injectGrades: resolveId alias works the same as clipId', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-grades-'));
+  try {
+    const srcDrp = path.join(tmp, 'src.drp');
+    const outDrp = path.join(tmp, 'out.drp');
+    await buildSyntheticDrp(srcDrp);
+    const beforeXml = await readSeqContainer(srcDrp);
+    const before = scrapeClipBodies(beforeXml);
+    const result = await drpFormat.injectGrades(srcDrp, [
+      { resolveId: before[1].dbId, drxContent: makeSyntheticDrx(INJECTED_BODY) },
+    ], { outputPath: outDrp });
+    assert.equal(result.clipsInjected, 1);
+    const afterXml = await readSeqContainer(outDrp);
+    const after = scrapeClipBodies(afterXml);
+    assert.equal(after[1].body, INJECTED_BODY);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('injectGrades: in-place overwrite atomically replaces the source file', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'inject-grades-'));
+  try {
+    const drpPath = path.join(tmp, 'inplace.drp');
+    await buildSyntheticDrp(drpPath);
+    const originalBytes = (await fs.stat(drpPath)).size;
+    const beforeXml = await readSeqContainer(drpPath);
+    const before = scrapeClipBodies(beforeXml);
+    // No outputPath → in-place.
+    await drpFormat.injectGrades(drpPath, [
+      { clipId: before[0].dbId, drxContent: makeSyntheticDrx(INJECTED_BODY) },
+    ]);
+    const afterBytes = (await fs.stat(drpPath)).size;
+    assert.ok(Math.abs(afterBytes - originalBytes) < originalBytes * 0.25,
+      'in-place output size should be in the ballpark of original');
+    const afterXml = await readSeqContainer(drpPath);
+    const after = scrapeClipBodies(afterXml);
+    assert.equal(after[0].body, INJECTED_BODY);
+    // No leftover tmp file.
+    const tmpLeftover = await fs.stat(`${drpPath}.injecting`).catch(() => null);
+    assert.equal(tmpLeftover, null);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+test('injectGrades: internals — extractDrxBodyHex strips non-hex chars', () => {
+  const { _internals } = require('../inject-grades');
+  const xml = '<x><Body>  81 ca\nfe ba be  </Body></x>';
+  assert.equal(_internals.extractDrxBodyHex(xml), '81cafebabe');
+});
+test('injectGrades: internals — extractDrxBodyHex throws on missing Body', () => {
+  const { _internals } = require('../inject-grades');
+  assert.throws(() => _internals.extractDrxBodyHex('<x>nope</x>'),
+    /no <Body>HEX<\/Body> block/i);
+});
+// ─── Resolve-in-loop verification (RESOLVE_VERIFY=1) ───────────
+//
+// Per P0.1 step 5 (logged deferred in knowledge/resolve-verifications.md),
+// the byte-identical-render check requires Resolve. When the env flag is
+// unset the test skips with a clear marker.
+resolveVerifyTest('injectGrades: rendered frame matches direct DRX apply', async () => {
+  // The harness's resolve-verifications.md has the full recipe. The actual
+  // implementation will live here once a captured fixture + a Resolve session
+  // is in flight. Until then it's a placeholder that exists to demonstrate
+  // the resolveVerifyTest gate and to surface in the skip list as a TODO.
+  throw new Error('TODO — implement once fixtures/inject-target.drp + Resolve session land');
+});