davinci-resolve-mcp 2.66.0 → 2.67.1

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.67.1
+
+Documentation correction. No code changes — v2.67.0 already ships the correct
+behavior.
+
+### Changed
+
+- **`docs/kernels/render-deliver-kernel.md` no longer quotes a format/codec count
+  as portable.** It presented "23 formats and 99 format/codec pairs" as the
+  expected probe result; a live probe on Studio 19.1.3.7 found 20 formats and 271
+  pairs. Both mentions now carry the build they came from and point at probing
+  the machine in hand (`probe_render_matrix`, or `list_delivery_targets` with
+  `check_availability`) instead of comparing against a fixed number.
+- The kernel's boundary list now records the two traps the delivery-target work
+  verified live: codec **descriptions are not codec ids** (`H.264` vs `H264`, not
+  only the ProRes family), and some formats expose **no codecs at all** (`Wave`,
+  `GIF` on 19.1.3.7) and cannot be selected through this API.
+
+## What's New in v2.67.0
+
+Adds **delivery targets** — named render intents that carry their own QC spec —
+and fixes a silent render-codec bug found while designing them.
+
+### Fixed
+
+- **Render codec display names were rejected.** `GetRenderCodecs` returns
+  `{description: id}`, but the codec was passed to
+  `SetCurrentRenderFormatAndCodec`, `GetRenderResolutions`, and
+  `prepare_render_job` **raw** while the format was normalized. Verified live on
+  Studio 19.1.3.7: `('mov', 'Apple ProRes 422 HQ')` returns False while
+  `('mov', 'ProRes422HQ')` returns True — and the same holds for
+  `('mp4', 'H.264')` vs `('mp4', 'H264')`. Any render set by the codec name shown
+  in the Deliver page failed, across every codec family. This is the codec half
+  of the format-id fix (issue #59).
+- **A rejected format/codec no longer queues a job anyway.**
+  `prepare_render_job` previously applied settings and called `AddRenderJob()`
+  even when `SetCurrentRenderFormatAndCodec` returned False, reporting
+  `success: True` with `format_success: False` buried in the payload — a queued
+  job that would render in the *previously set* codec. It now returns
+  `RENDER_FORMAT_CODEC_REJECTED` with the machine's available codecs and queues
+  nothing. `set_format_and_codec` returns the same structured error instead of a
+  bare `success: False`.
+- **The granular server never received the issue #59 fix.**
+  `get_render_codecs` passed a raw display name, and
+  `set_current_render_format_and_codec` passed both format and codec raw. The
+  resolvers now live in `src/utils/render_ids.py` and are shared by both servers,
+  so the two cannot drift apart again.
+
+### Added
+
+- **Delivery targets** (`src/utils/delivery_targets.py`) — 28 named render
+  intents across master / web / sequence / broadcast / package tiers, every one
+  resolved live against Resolve Studio 19.1.3.7 (20 formats / 271 pairs). One
+  definition projects onto both Resolve `SetRenderSettings` keys and the
+  ffprobe-shaped spec `deliverable_qc` consumes, so a render and the check that
+  verifies it come from the same source. New `render` actions:
+  `list_delivery_targets`, `resolve_delivery_target`, `prepare_delivery_job`.
+  - Ids describe the deliverable (`prores422hq_master`, `h264_1080p_web`);
+    platform names (`youtube`, `tiktok`, `avid`, `stems`) are **aliases**, so a
+    platform changing its guidance repoints an alias instead of rewriting a target.
+  - Format and codec are ordered **candidate lists** resolved against the live
+    matrix, because codec descriptions vary by Resolve version, license, and
+    installed IO plugins. An unavailable target fails with the machine's actual
+    available lists; `list_delivery_targets` with `check_availability` reports
+    what this install can render.
+  - User-defined targets load from `logs/delivery-targets.json` (override with
+    `DAVINCI_RESOLVE_MCP_DELIVERY_TARGETS`); a malformed entry is skipped with a
+    warning rather than taking out the shipped set.
+- **`deliverable(action="spec_from_authored")`** on the advanced server —
+  projects the authored deliverable vocabulary (codec display names,
+  `"1920x1080"`, `"-16 LUFS"`, `<SHOW>_<EP>_<YYYYMMDD>.mov` naming templates)
+  onto a `deliverable_qc` spec plus a `loudness_qc` target. Anything it cannot
+  map is reported in `unmapped[]` rather than dropped.
+- **The `deliver` apply contract now carries QC specs.**
+  `APPLY_CONTRACT.deliver` emits `qc[]` alongside each deliverable, so a render
+  job travels with the spec that will verify it. Previously a stub.
+- **`tests.test_duplicate_definitions`** — static guard against a module-level
+  name being defined twice under `src/`. pyflakes does not catch this (it only
+  reports redefinition of an *unused* name), and the dangerous case is exactly
+  the one it misses. Added to the release validation set.
+
+### Notes
+
+- Bitrate is deliberately not encoded in delivery targets: Resolve exposes no
+  bitrate render-setting key, only `VideoQuality`, whose type varies per codec.
+- Image-sequence and package (IMF/DCP) targets return no QC spec —
+  `deliverable_qc` probes a single file, and those render many files or a
+  directory. Every such target carries an explicit `qc_skip_reason`, so a missing
+  check is always explained rather than silent.
+- **There is no audio-only WAV target.** The `Wave` format exposes zero codecs
+  and `SetCurrentRenderFormatAndCodec('wav', …)` rejects every value tried,
+  including the empty string. Recorded in `src/utils/api_truth.py` and the
+  generated `docs/reference/api-limitations.md`.
+- The live pass corrected candidate spellings that were wrong: plain
+  `"DNxHR HQX"` / `"DNxHR 444"` do not exist (live labels carry a bit depth),
+  DPX/TIFF codecs are `"RGB 10 bits"` not `"RGB 10-bit"`, and PNG is not a
+  Resolve render format.
+- `container` is `"mov"` for both `.mov` and `.mp4`: ffprobe reports
+  `format_name=mov,mp4,m4a,3gp,3g2,mj2` for each and only the first token is
+  kept, so `video.codec` is what discriminates them.
+
 ## What's New in v2.66.0
 
 Generalizes the HTTP transcription backend introduced in v2.65.0 into a

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.66.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.67.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -1363,6 +1363,16 @@ Render / Deliver kernel actions (v2.9.0+) add planning and safety layers:
 `export_render_boundary_report`. See `docs/kernels/render-deliver-kernel.md` for the
 live-tested format/codec, settings, job, and Quick Export boundary map.
 
+Delivery targets (v2.67.0+) are named render intents — `list_delivery_targets`,
+`resolve_delivery_target(target)`, `prepare_delivery_job(target, target_dir)`.
+Ask for `prores422hq_master`, `dnxhr_hqx_master`, `h264_1080p_web`, or a platform
+alias like `youtube` / `tiktok`, and one definition supplies both the Resolve
+render settings and the ffprobe QC spec the advanced server checks the output
+against. Format/codec resolve against the live matrix, so a target this machine
+or license cannot render fails with the available lists rather than silently
+rendering something else. `list_delivery_targets` with `check_availability: true`
+reports what this install can actually deliver.
+
 ---
 
 ## Common Workflows

package/docs/kernels/render-deliver-kernel.md

@@ -24,6 +24,38 @@ All actions are under `render(action=...)`.
 | `quick_export_capabilities` | Supported | Lists Quick Export presets and enforced safety guards. |
 | `safe_quick_export` | Supported dry-run | Validates temp target, forces `EnableUpload=False`, and requires `allow_render=True` before actual Quick Export execution. |
 | `export_render_boundary_report` | Supported | Combines capabilities, settings snapshot, format matrix, and Quick Export capabilities. |
+| `list_delivery_targets` | Supported | Lists named render intents, optionally filtered by tier and checked against the live format/codec matrix. |
+| `resolve_delivery_target` | Supported | Resolves a named target to live format/codec ids plus its render settings and QC spec. |
+| `prepare_delivery_job` | Supported | Resolves a named target and queues a render job for it, returning the QC spec that verifies the output. |
+
+## Delivery Targets
+
+A delivery target is a **named render intent** (`prores422hq_master`,
+`h264_1080p_web`, `dnxhr_hqx_master`, ...) defined once in
+`src/utils/delivery_targets.py` and projected two ways: onto Resolve
+`SetRenderSettings` keys, and onto the ffprobe-shaped spec the advanced server's
+`deliverable_qc` consumes. The render and the check that verifies it therefore
+come from one definition.
+
+- **Ids describe the deliverable; platform names are aliases.** `youtube`,
+  `tiktok`, `reels` and friends point at spec-descriptive ids. When a platform
+  changes its guidance you repoint an alias rather than rewrite a target, so no
+  committed id can become a lie about what it produces.
+- **Format and codec are candidate lists**, resolved against the live matrix at
+  call time. Codec description strings vary by Resolve version, license, and
+  installed IO plugins, so a target names the spellings it knows and the first
+  available one wins.
+- **Unavailable targets fail loudly** with `DELIVERY_TARGET_FORMAT_UNAVAILABLE` /
+  `DELIVERY_TARGET_CODEC_UNAVAILABLE` and the machine's actual available lists.
+  Use `list_delivery_targets` with `check_availability` to see what this install
+  can render before planning around it.
+- **The QC spec asserts only what the render settings pin.** Bitrate is not
+  encoded (Resolve exposes no bitrate key — only `VideoQuality`, whose type
+  varies per codec), and image-sequence targets carry no QC spec at all because
+  `deliverable_qc` probes a single file.
+- Users can add targets in `logs/delivery-targets.json` (override the path with
+  `DAVINCI_RESOLVE_MCP_DELIVERY_TARGETS`). A malformed entry is skipped with a
+  warning rather than taking out the shipped set.
 
 ## Supported Boundaries
 
@@ -47,7 +79,17 @@ All actions are under `render(action=...)`.
   readback as version/page dependent and still validates and applies settings
   through `SetRenderSettings`.
 - Render format and codec availability is machine, OS, license, and plugin
-  dependent. The final live probe found 23 formats and 99 format/codec pairs.
+  dependent, and it varies a lot: a live probe found 23 formats / 99 pairs on one
+  build, and 20 formats / 271 pairs on Studio 19.1.3.7. Treat neither figure as
+  the expected count — probe the machine you are on
+  (`probe_render_matrix`, or `list_delivery_targets` with `check_availability`).
+- Codec **descriptions are not codec ids**. `GetRenderCodecs` returns
+  `{description: id}` and every setter wants the id, so the name shown in the
+  Deliver page is rejected — for `H.264` (`H264`) just as much as for
+  `Apple ProRes 422 HQ` (`ProRes422HQ`). `src/utils/render_ids.py` normalizes
+  either form; see `docs/reference/api-limitations.md`.
+- Some formats expose **no codecs at all** (`Wave`, `GIF` on 19.1.3.7) and then
+  reject every codec value, so they cannot be selected through this API.
 - Some settings may be accepted but not readable for coercion checks on builds
   where `GetRenderSettings` is unavailable.
 - Quick Export actual execution is intentionally gated behind
@@ -119,6 +161,8 @@ Result:
 
 The live harness created and deleted a disposable project named
 `_mcp_render_deliver_probe_1778342107`, generated synthetic media, probed 23
-formats and 99 format/codec pairs, rendered one tiny synthetic output, wrote
+formats and 99 format/codec pairs **on that build** (a later probe on Studio
+19.1.3.7 saw 20 formats / 271 pairs — the counts are not portable), rendered one
+tiny synthetic output, wrote
 JSON and Markdown reports, and removed the generated media and render output
 directories after the report was written.

package/docs/process/release-process.md

@@ -59,13 +59,20 @@ venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
 node scripts/agent-rules/generate.mjs --check
-venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
+venv/bin/python -m unittest tests.test_static_undefined_names tests.test_duplicate_definitions tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
 npm pack --dry-run
 git diff --check
 ```
 
+`test_duplicate_definitions` asserts no module-level name is defined twice under
+`src/`. A second `def foo` silently replaces the first, and in a module the size
+of `src/server.py` the two can be thousands of lines apart with different
+signatures. pyflakes does **not** catch this — it only reports redefinition of an
+*unused* name, so the dangerous case (first definition used, then shadowed)
+passes clean.
+
 The drift guards (undefined names in `src/`, tool action lists vs dispatch,
 control-panel guide vs panel navigation/screenshots, api-limitations vs the
 api_truth ledger, and **tool counts across the docs vs reality** —

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 19 missing capabilities, 12 bugs / unreliable behaviors.
+**Totals:** 20 missing capabilities, 13 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -177,6 +177,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
 - **Tags:** missing-method, media-pool, folder
 
+### Project.SetCurrentRenderFormatAndCodec
+
+- **Object:** `Project`
+- **Signature:** `(format, codec) -> bool`
+- **Behavior:** Some render formats expose NO codecs at all — GetRenderCodecs('wav') and GetRenderCodecs('gif') both return {} on Studio 19.1.3.7 — and the call then rejects every codec value, including the empty string, the format id itself, and any plausible name ('Linear PCM'). There is no documented way to select such a format through this API, so an audio-only WAV deliverable is not expressible in scripting.
+- **Workaround / current handling:** Check GetRenderCodecs(format) first; when it is empty, treat the format as unreachable through this API rather than guessing a codec value. Render audio-only via ExportVideo=False on a format that does expose codecs, or drive it from a saved render preset.
+- **Tags:** render, deliver, audio, unsupported
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -274,3 +282,12 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** On a False return, locate the LUT, copy it into a namespaced subfolder of the master LUT dir (MCP/, so it does not clobber stock LUTs by basename), call RefreshLUTList(), and retry with the master-relative path. graph.set_lut and the granular graph_set_lut now do this automatically via src.utils.lut_paths.ensure_lut_in_master.
 - **Reference:** [issue #90](https://github.com/samuelgursky/davinci-resolve-mcp/issues/90)
 - **Tags:** color, lut, path-resolution, silent-failure
+
+### Project.GetRenderCodecs
+
+- **Object:** `Project`
+- **Signature:** `(renderFormat) -> {codec description: codec name}`
+- **Behavior:** Returns {description: id} — the human-readable description is the KEY and the id Resolve actually accepts is the VALUE. SetCurrentRenderFormatAndCodec, GetRenderCodecs and GetRenderResolutions all require the id, so passing the description a user sees in the Deliver page is rejected. Verified live on Studio 19.1.3.7: ('mov', 'Apple ProRes 422 HQ') -> False while ('mov', 'ProRes422HQ') -> True, and ('mp4', 'H.264') -> False while ('mp4', 'H264') -> True. It affects every family, not only the ones whose id differs obviously. Mirrors the same trap in GetRenderFormats, which returns {format: extension}.
+- **Workaround / current handling:** Normalize both arguments through the live maps before calling: src.utils.render_ids.render_format_id_from_formats and render_codec_id_from_codecs accept a description or an id and return the id.
+- **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
+- **Tags:** render, deliver, silent-failure, id-vs-label

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.66.0"
+VERSION = "2.67.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.66.0",
+  "version": "2.67.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/README.md

@@ -87,7 +87,10 @@ Each dispatches on an `action`. Highlights:
 - **`deliverable`** — deliverable QC / compliance: `deliverable_qc` (ffprobe a render vs its spec →
   pass/fail per field), `loudness_qc` (ebur128 LUFS/true-peak/LRA), `reframe_blanking_check`,
   `conform_completeness`, `re_delivery_diff`, `render_manifest` (build/reconcile), `expand_deliverable`
-  (texted/textless/stems/slate/leader entities). Report-only (`gate: review` — never auto-pass-clear).
+  (texted/textless/stems/slate/leader entities), `spec_from_authored` (authored deliverable vocabulary —
+  codec display names, `"1920x1080"`, `"-16 LUFS"`, naming templates — into a `deliverable_qc` spec plus a
+  `loudness_qc` target, reporting anything it could not map). Report-only (`gate: review` — never
+  auto-pass-clear).
 - **`media`** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes-by-hash), `media_inventory`
   (fps/codec/colorspace/TC + card gaps), `sync` (TC picture↔sound + drift/MOS), `relink_manifest`,
   `rename_plan` (refuses camera originals) / `reel_normalize`, `turnover_package`, `project_hygiene`.

package/resolve-advanced/server/deliverable-spec-bridge.mjs

@@ -0,0 +1,310 @@
+/**
+ * deliverable spec BRIDGE — authored deliverable vocabulary → ffprobe-shaped QC spec.
+ *
+ * The two vocabularies in this repo do not match, and that mismatch is why the
+ * `deliver` stage has never actually QC'd anything:
+ *
+ *   authored (spec-compile / YAML)     ffprobe (checkDeliverable / deliverable-qc)
+ *   ------------------------------     ------------------------------------------
+ *   video.codec "ProRes 422 HQ"        video.codec "prores"
+ *   video.res   "1920x1080"            video.width 1920 + video.height 1080
+ *   video.color "Rec.709 Gamma 2.4"    video.colorPrimaries/colorMatrix "bt709"
+ *   audio.config "stereo"              audio.channels 2
+ *   audio.loudness "-16 LUFS"          (not a QC-spec field — a loudnessQc target)
+ *   naming "<SHOW>_<EP>_M_<YYYYMMDD>"  filenameRegex "^..._\\d{8}\\.mov$"
+ *   (implied by the naming extension)  container "mov"
+ *
+ * PURE — no I/O, no Resolve, no ffprobe. Mirrors the live Python server's
+ * `src/utils/delivery_targets.py`, which performs the same projection for named
+ * render intents; this side handles the *authored* vocabulary, which only exists
+ * here. Neither table is duplicated.
+ *
+ * Two rules carried over from the Python side, for the same reason:
+ *
+ *   1. Assert only what is actually known. A QC field the spec never pinned
+ *      produces a failure that says nothing about the deliverable.
+ *   2. Never drop silently. Anything that cannot be mapped is reported in
+ *      `unmapped[]` so an unrecognized codec name surfaces instead of quietly
+ *      producing a spec with no codec check in it.
+ *
+ * ffprobe gotcha: `format_name` is "mov,mp4,m4a,3gp,3g2,mj2" for BOTH .mov and
+ * .mp4, and ffprobe-media.mjs takes the first token — so `container` is "mov"
+ * for both and cannot discriminate them. `video.codec` is the discriminator.
+ */
+
+/** Authored codec display name → ffprobe codec_name. Matched case-insensitively by prefix family. */
+const CODEC_FAMILIES = [
+  { test: /prores/i, codec: 'prores' },
+  { test: /dnx(hr|hd)/i, codec: 'dnxhd' },
+  { test: /^h\.?264|avc(?!.*intra)|x264|xavc/i, codec: 'h264' },
+  { test: /^h\.?265|hevc|x265/i, codec: 'hevc' },
+  { test: /avc.?intra/i, codec: 'h264' },
+  { test: /jpe?g.?2000|j2k/i, codec: 'jpeg2000' },
+  { test: /cineform/i, codec: 'cfhd' },
+  { test: /^dv|dvcpro/i, codec: 'dvvideo' },
+  { test: /mpeg.?2|xdcam/i, codec: 'mpeg2video' },
+  { test: /uncompressed|v210/i, codec: 'v210' },
+];
+
+/** Named rasters that appear in authored specs instead of an explicit WxH. */
+const NAMED_RASTERS = {
+  hd: [1920, 1080],
+  '1080p': [1920, 1080],
+  fhd: [1920, 1080],
+  '720p': [1280, 720],
+  uhd: [3840, 2160],
+  '2160p': [3840, 2160],
+  '4k': [4096, 2160],
+  '4kdci': [4096, 2160],
+  '2k': [2048, 1080],
+};
+
+/** Authored audio layout word → channel count. */
+const AUDIO_LAYOUTS = {
+  mono: 1,
+  stereo: 2,
+  '2.0': 2,
+  lcr: 3,
+  quad: 4,
+  '5.1': 6,
+  '7.1': 8,
+};
+
+/** Container inferred from a filename/naming extension. */
+const EXT_CONTAINERS = {
+  mov: 'mov',
+  mp4: 'mov', // ffprobe first token is "mov" for mp4 too
+  m4v: 'mov',
+  mxf: 'mxf',
+  wav: 'wav',
+  mka: 'matroska',
+  mkv: 'matroska',
+};
+
+/** Date-ish naming tokens with a known shape; everything else is permissive. */
+const TOKEN_PATTERNS = {
+  YYYYMMDD: '\\d{8}',
+  YYYY_MM_DD: '\\d{4}_\\d{2}_\\d{2}',
+  'YYYY-MM-DD': '\\d{4}-\\d{2}-\\d{2}',
+  YYYY: '\\d{4}',
+  YY: '\\d{2}',
+  MM: '\\d{2}',
+  DD: '\\d{2}',
+  VER: 'v?\\d+',
+  V: 'v?\\d+',
+};
+
+const DEFAULT_TOKEN = '[A-Za-z0-9.-]+';
+
+/** Map an authored codec name to an ffprobe codec_name, or null if unrecognized. */
+export function codecToFfprobe(name) {
+  if (typeof name !== 'string' || !name.trim()) return null;
+  for (const { test, codec } of CODEC_FAMILIES) {
+    if (test.test(name)) return codec;
+  }
+  return null;
+}
+
+/** Parse "1920x1080" / "1920 X 1080" / "UHD" / "HD" → {width, height}, or null. */
+export function parseRaster(res) {
+  if (res == null) return null;
+  if (typeof res === 'object' && res.width && res.height) {
+    return { width: Number(res.width), height: Number(res.height) };
+  }
+  if (typeof res !== 'string') return null;
+  const explicit = res.trim().match(/^(\d{2,5})\s*[x×]\s*(\d{2,5})$/i);
+  if (explicit) return { width: Number(explicit[1]), height: Number(explicit[2]) };
+  const named = NAMED_RASTERS[res.trim().toLowerCase().replace(/[\s_]/g, '')];
+  return named ? { width: named[0], height: named[1] } : null;
+}
+
+/** Parse an authored fps ("23.976", 23.98, "24000/1001") → number, or null. */
+export function parseFps(fps) {
+  if (typeof fps === 'number' && Number.isFinite(fps)) return fps;
+  if (typeof fps !== 'string' || !fps.trim()) return null;
+  const ratio = fps.trim().match(/^(\d+)\s*\/\s*(\d+)$/);
+  if (ratio) return Number(ratio[1]) / Number(ratio[2]);
+  const n = Number(fps);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Parse "-16 LUFS" / -16 / "-16LUFS" → number, or null. */
+export function parseLoudness(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string') return null;
+  const m = value.trim().match(/^(-?\d+(?:\.\d+)?)\s*(?:lufs)?$/i);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Map an authored color description to the ffprobe tags that are UNAMBIGUOUS.
+ *
+ * Primaries and matrix follow from the colorimetry name. The transfer does NOT:
+ * "Rec.709 Gamma 2.4" names a display gamma, which is not the same thing as the
+ * BT.709 OETF that ffprobe would report as color_transfer=bt709. Asserting one
+ * for the other produces a QC failure that is about vocabulary, not the file, so
+ * the transfer is deliberately left unmapped and reported.
+ *
+ * @returns {{tags: object, unmapped: string[]}}
+ */
+export function parseColor(color) {
+  if (typeof color !== 'string' || !color.trim()) return { tags: {}, unmapped: [] };
+  const text = color.toLowerCase();
+  const tags = {};
+  const unmapped = [];
+
+  if (/rec\.?\s*709|bt\.?\s*709/.test(text)) {
+    tags.colorPrimaries = 'bt709';
+    tags.colorMatrix = 'bt709';
+  } else if (/rec\.?\s*2020|bt\.?\s*2020/.test(text)) {
+    tags.colorPrimaries = 'bt2020';
+    tags.colorMatrix = /ncl/.test(text) ? 'bt2020nc' : 'bt2020nc';
+  } else if (/p3/.test(text)) {
+    tags.colorPrimaries = 'smpte432';
+  } else if (/rec\.?\s*601|bt\.?\s*601/.test(text)) {
+    tags.colorPrimaries = 'bt470bg';
+    tags.colorMatrix = 'bt470bg';
+  } else if (text.trim()) {
+    unmapped.push(`color '${color}': unrecognized colorimetry`);
+  }
+
+  if (/pq|st\.?\s*2084/.test(text)) tags.colorTransfer = 'smpte2084';
+  else if (/hlg|arib/.test(text)) tags.colorTransfer = 'arib-std-b67';
+  else if (/gamma/.test(text)) {
+    unmapped.push(
+      `color '${color}': display gamma is not an ffprobe color_transfer value; transfer left unasserted`,
+    );
+  }
+
+  return { tags, unmapped };
+}
+
+/**
+ * Turn a naming template into an anchored filename regex.
+ * `<SHOW>_<EP>_MASTER_<YYYYMMDD>.mov` → `^[A-Za-z0-9.-]+_[A-Za-z0-9.-]+_MASTER_\d{8}\.mov$`
+ */
+export function namingToRegex(naming) {
+  if (typeof naming !== 'string' || !naming.trim()) return null;
+  let out = '';
+  let rest = naming.trim();
+  const tokenRe = /<([^<>]+)>/;
+  for (;;) {
+    const m = rest.match(tokenRe);
+    if (!m) {
+      out += escapeRegex(rest);
+      break;
+    }
+    out += escapeRegex(rest.slice(0, m.index));
+    const key = m[1].trim().toUpperCase().replace(/[\s]/g, '');
+    out += TOKEN_PATTERNS[key] ?? DEFAULT_TOKEN;
+    rest = rest.slice(m.index + m[0].length);
+  }
+  return `^${out}$`;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Container from an explicit value, else inferred from a naming/filename extension. */
+export function inferContainer(explicit, naming) {
+  if (typeof explicit === 'string' && explicit.trim()) {
+    const key = explicit.trim().toLowerCase().replace(/^\./, '');
+    return EXT_CONTAINERS[key] ?? key;
+  }
+  if (typeof naming !== 'string') return null;
+  const m = naming.trim().match(/\.([A-Za-z0-9]+)\s*$/);
+  if (!m) return null;
+  return EXT_CONTAINERS[m[1].toLowerCase()] ?? m[1].toLowerCase();
+}
+
+/**
+ * Project ONE authored deliverable onto a checkDeliverable spec + a loudness target.
+ *
+ * @param {object} deliverable Authored shape: { id?, video:{codec,res,fps,color,scan?},
+ *   audio:{config,loudness,sampleRate?,bitDepth?}, container?, naming?, durationSeconds? }
+ * @returns {{id, spec, loudnessTarget, unmapped, note}}
+ *   `spec` feeds deliverable_qc; `loudnessTarget` feeds loudness_qc (null when not authored).
+ */
+export function deliverableSpecFromAuthored(deliverable) {
+  const d = deliverable || {};
+  const v = d.video || {};
+  const a = d.audio || {};
+  const unmapped = [];
+
+  const video = {};
+  const ffCodec = codecToFfprobe(v.codec);
+  if (ffCodec) video.codec = ffCodec;
+  else if (v.codec) unmapped.push(`video.codec '${v.codec}': no known ffprobe codec_name`);
+
+  const raster = parseRaster(v.res ?? v.resolution);
+  if (raster) {
+    video.width = raster.width;
+    video.height = raster.height;
+  } else if (v.res ?? v.resolution) {
+    unmapped.push(`video.res '${v.res ?? v.resolution}': unparseable raster`);
+  }
+
+  const fps = parseFps(v.fps);
+  if (fps != null) video.fps = fps;
+  else if (v.fps != null) unmapped.push(`video.fps '${v.fps}': unparseable frame rate`);
+
+  if (typeof v.scan === 'string' && v.scan.trim()) video.scan = v.scan.trim().toLowerCase();
+  if (v.bitDepth != null) video.bitDepth = Number(v.bitDepth);
+
+  const color = parseColor(v.color);
+  Object.assign(video, color.tags);
+  unmapped.push(...color.unmapped);
+
+  const audio = {};
+  if (a.channels != null) audio.channels = Number(a.channels);
+  else if (typeof a.config === 'string') {
+    const channels = AUDIO_LAYOUTS[a.config.trim().toLowerCase()];
+    if (channels) audio.channels = channels;
+    else unmapped.push(`audio.config '${a.config}': unknown layout`);
+  }
+  if (a.sampleRate != null) audio.sampleRate = Number(a.sampleRate);
+  if (a.bitDepth != null) audio.bitDepth = Number(a.bitDepth);
+  if (typeof a.channelLayout === 'string') audio.channelLayout = a.channelLayout;
+
+  const spec = {};
+  if (Object.keys(video).length) spec.video = video;
+  if (Object.keys(audio).length) spec.audio = audio;
+
+  const container = inferContainer(d.container, d.naming);
+  if (container) spec.container = container;
+
+  const filenameRegex = namingToRegex(d.naming);
+  if (filenameRegex) spec.filenameRegex = filenameRegex;
+
+  if (d.durationSeconds != null) spec.durationSeconds = Number(d.durationSeconds);
+  if (d.durationTolSeconds != null) spec.durationTolSeconds = Number(d.durationTolSeconds);
+
+  const integrated = parseLoudness(a.loudness);
+  const loudnessTarget = integrated == null ? null : { integrated };
+  if (a.loudness != null && integrated == null) {
+    unmapped.push(`audio.loudness '${a.loudness}': unparseable target`);
+  }
+  if (a.truePeakMax != null && loudnessTarget) loudnessTarget.truePeakMax = Number(a.truePeakMax);
+  if (a.lraMax != null && loudnessTarget) loudnessTarget.lraMax = Number(a.lraMax);
+  if (a.loudnessTol != null && loudnessTarget) loudnessTarget.integratedTol = Number(a.loudnessTol);
+
+  return {
+    id: d.id ?? null,
+    spec,
+    loudnessTarget,
+    unmapped,
+    note:
+      'Loudness is NOT part of the deliverable_qc spec — run loudness_qc separately with loudnessTarget.',
+  };
+}
+
+/** Project an authored `deliverables:` list. Non-object entries are reported, not dropped. */
+export function deliverableSpecsFromAuthored(deliverables) {
+  if (!Array.isArray(deliverables)) return [];
+  return deliverables.map((d, i) =>
+    d && typeof d === 'object'
+      ? deliverableSpecFromAuthored(d)
+      : { id: null, spec: {}, loudnessTarget: null, unmapped: [`deliverables[${i}] is not an object`], note: null },
+  );
+}

package/resolve-advanced/server/runner-apply-contract.mjs

@@ -10,6 +10,7 @@
  *
  * VERIFY against the live server's real action names/args before finalizing (first real-footage session).
  */
+import { deliverableSpecsFromAuthored } from './deliverable-spec-bridge.mjs';
 
 // stage → the Python action(s) + how each action's args derive from the resolved config.
 export const APPLY_CONTRACT = {
@@ -43,8 +44,22 @@ export const APPLY_CONTRACT = {
   qc: [{ action: 'noop', argsFrom: () => ({ note: 'qc is deterministic in Node (gamut_legal/deliverable_qc/verify_grade) — no live apply' }) }],
   deliver: [
     {
+      // The emitted job carries the QC spec that will later verify it, so the
+      // render and its check come from one authored definition instead of being
+      // re-derived by hand after the fact. Loudness is deliberately separate —
+      // it is not a deliverable_qc field (see deliverable-spec-bridge.mjs).
       action: 'render.add_job',
-      argsFrom: (c) => ({ deliverables: c?.deliverables ?? c ?? null, note: 'expand deliverable entities → render preset + naming' }),
+      argsFrom: (c) => {
+        const deliverables = c?.deliverables ?? (Array.isArray(c) ? c : null);
+        const projected = deliverableSpecsFromAuthored(deliverables ?? []);
+        const unmapped = projected.flatMap((p) => (p.unmapped || []).map((u) => (p.id ? `${p.id}: ${u}` : u)));
+        return {
+          deliverables: deliverables ?? c ?? null,
+          qc: projected.map((p) => ({ id: p.id, spec: p.spec, loudnessTarget: p.loudnessTarget })),
+          ...(unmapped.length ? { unmapped } : {}),
+          note: 'render per deliverable, then deliverable_qc each output against its qc[].spec (and loudness_qc against qc[].loudnessTarget)',
+        };
+      },
     },
   ],
 };