davinci-resolve-mcp 2.100.0 → 2.101.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 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.101.0
+
+**A grade can now reject itself.** `assess_grade` has measured grade damage since
+v2.68.0 — banding in a sky, highlight levels collapsing, shadow grain amplified into
+noise — and every flag it raises carries a remedy. Nothing consumed that report. The
+measurement existed; the loop did not, so the remedy "reduce the strength" was advice an
+agent had no way to act on.
+
+### Added
+
+- **`media_analysis grade_loop`** — the retry ladder. Applies a look LUT, measures the
+  real decoded frame, and on any flag retries with the same look attenuated toward
+  identity (strength x 0.8 per rung, floored at 0.5, three tries by default). The first
+  strength that clears every sampled frame wins.
+  - **A flagged result is never reported acceptable.** An exhausted ladder returns
+    `needs_human` with the best attempt and its remaining flags — never a quiet success
+    at a strength that still bands.
+  - **Every sampled frame must pass.** `times=[...]` samples several timestamps and the
+    report names the one that failed; a grade clean on the frame you happened to check
+    is not a grade that passed.
+  - **The best attempt is the gentlest.** When nothing converges, attempts rank by flag
+    count with ties broken by the smallest colour shift — equal damage means taking the
+    one a human has less to undo.
+  - **It does not touch the project.** The result is an apply manifest with
+    `safe_to_apply`, and a flagged result carries the reason it is blocked.
+  - `dry_run` defaults to true and reports the ffmpeg decode budget before anyone
+    commits to it. `cost_tier` defaults to `numeric`, because escalating every rung to
+    vision would spend host turns on attempts that exist to be rejected.
+- **`media_analysis grade_loop_capabilities`** — dependency state, ladder constants, and
+  an explicit statement of which modes exist.
+- **`src/utils/cube_lut.py`** — read, write, and attenuate 3D `.cube` LUTs. Attenuation
+  is a blend toward identity, the same operation a LUT mix control performs. Exact at
+  both endpoints: strength 1.0 returns the table unchanged and 0.0 returns true
+  identity. 1D LUTs are refused by name, and attenuation on a non-unit
+  `DOMAIN_MIN`/`DOMAIN_MAX` is refused because identity is only identity on 0..1.
+
+### Not built, and said so
+
+The in-loop **live** mode — apply in Resolve, render a frame, assess, repeat — is not
+implemented. It needs a single-frame render per rung, and shipping it unvalidated would
+put a "verified live" claim behind something no runnable command has produced.
+`grade_loop_capabilities()` says this in the response rather than only in the docs. The
+offline LUT ladder is complete and validated.
+
+### Documentation
+
+- `docs/guides/color-decision-guide.md` — a new "Rejecting Your Own Grade" section on
+  when measurement beats eyeballing a compressed preview.
+- `docs/kernels/color-grade-kernel.md` — the numeric grade-QC actions and their
+  display-referred-only contract.
+
+### Validation
+
+- Offline suite: 2889 passed, 1 skipped, 711 subtests, 0 failures.
+- End-to-end through real ffmpeg on generated media: a look that converges only after
+  backing off, and one that never converges and says so.
+- Two deliberate mutations — `acceptable` hard-coded true, and a rung passing on its
+  first clean frame — were each caught by the new tests.
+- No Resolve behavior changed; live test not required. A test asserts no Resolve
+  connection is attempted.
+
 ## What's New in v2.100.0
 
 **The craft guidance is now readable by any MCP client.** This repository carries a

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.100.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.101.0-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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.100.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.101.0-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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.100.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.101.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/guides/color-decision-guide.md

@@ -211,6 +211,36 @@ If untreated/current/after comparison is not available through the API in the
 moment, say which part is unavailable and whether the user wants a blind/global
 pass. Do not imply that a grade was reviewed if no rendered frames were checked.
 
+## Rejecting Your Own Grade
+
+Looking at frames tells you whether a grade reads right. It does not reliably tell you
+whether it *damaged* the picture — banding in a sky, highlight levels collapsing, shadow
+grain amplified into visible noise. Those are measurable, and measuring them is cheaper
+and steadier than eyeballing a compressed preview.
+
+`media_analysis assess_grade` measures one graded frame against its source and returns
+flags with remedies. `media_analysis grade_loop` closes the loop: it applies a look LUT,
+measures the real decoded result, and on any flag retries with the same look attenuated
+toward identity (strength × 0.8 per rung, floored at 0.5, three tries by default). The
+first strength that clears every sampled frame wins.
+
+Three properties matter more than the convenience:
+
+- **A flagged result is never reported acceptable.** When the ladder is exhausted the
+  answer is `needs_human`, carrying the best attempt and what it still fails on. There
+  is no strength at which the loop shrugs and ships.
+- **Every sampled frame must pass.** Pass several timestamps — a grade that is clean on
+  the frame you happened to check and bands two hundred frames later has not passed
+  anything. The report names the frame that failed.
+- **It does not touch the project.** The loop returns an apply manifest and stops.
+  Applying a grade is still a deliberate, version-protected step, and a result carrying
+  unresolved flags should reach a human before it reaches a timeline.
+
+Reach for it when applying an unfamiliar look LUT to unfamiliar footage, which is
+exactly where "it looked fine on the first shot" goes wrong. The flags are advisory
+thresholds, not standards — the raw measurements come back too, so a colorist can
+disagree with the flag rather than only with the verdict.
+
 ## Safe Color Workflow
 
 Before changing color:

package/docs/kernels/color-grade-kernel.md

@@ -67,6 +67,28 @@ All actions are exposed through `timeline_item_color`.
   and delete worked.
 - Gallery capability and album list/create calls worked.
 
+## Numeric grade QC (`media_analysis`)
+
+Not part of the live kernel — no Resolve connection is involved — but it belongs to the
+same decision. Both actions measure a decoded frame of the real result, never a
+simulated transform, because LUT interpolation and encode rounding are where banding is
+actually introduced.
+
+- `assess_grade(source_path, time_seconds, graded_path|lut_path, working_space)` —
+  flags (`flat`, `washed_out`, `milky`, `noisy`, `clipped`, `posterized`, `banding`),
+  each with a remedy, plus the raw tonal/noise/damage measurements.
+- `grade_loop(source_path, lut_path, times[], strength?, max_tries?, strength_floor?,
+  dry_run?)` — the retry ladder over `assess_grade`. Attenuates the look toward identity
+  until every sampled frame clears, or returns `needs_human` with the best attempt.
+  `dry_run` defaults to **true** and reports the ffmpeg decode budget first.
+- `grade_loop_capabilities()` — dependency state, ladder constants, and which modes
+  exist. The in-loop **live** mode (apply in Resolve, render, assess) is **not built**;
+  the loop returns an apply manifest instead of driving the project.
+
+Both are display-referred only. Log and scene-referred encodings run through the same
+arithmetic happily and produce meaningless numbers, so `working_space` must be declared
+and non-display-referred values are refused rather than guessed at.
+
 ## Boundaries
 
 - Node graph internals are intentionally limited by Resolve's public API. The

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.100.0"
+VERSION = "2.101.0"
 # 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.100.0",
+  "version": "2.101.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.100.0"
+VERSION = "2.101.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.100.0"
+VERSION = "2.101.0"
 
 import base64
 import os
@@ -20076,6 +20076,58 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                     "metrics are undefined on them and will not be guessed at."
                 ),
             )
+    if action == "grade_loop":
+        # The retry ladder that consumes assess_grade's own verdict: apply the look,
+        # measure the real decoded frame, and on any flag retry with the look
+        # attenuated toward identity. Exhausting the ladder returns needs_human with
+        # the best attempt — never a quiet success at a strength that still bands.
+        from src.utils import grade_loop as _grade_loop_mod
+
+        source = str(p.get("source_path") or p.get("sourcePath") or "")
+        lut = str(p.get("lut_path") or p.get("lutPath") or "")
+        err, _clean = _validate_params(
+            {"source_path": source, "lut_path": lut},
+            {
+                "source_path": {"type": str, "required": True, "non_empty": True},
+                "lut_path": {"type": str, "required": True, "non_empty": True},
+            },
+        )
+        if err:
+            return _err(err)
+        kwargs = dict(
+            times=p.get("times"),
+            time_seconds=p.get("time_seconds", p.get("timeSeconds")),
+            strength=float(p.get("strength", 1.0) or 1.0),
+            max_tries=int(p.get("max_tries", p.get("maxTries", _grade_loop_mod.DEFAULT_MAX_TRIES))),
+            strength_floor=float(
+                p.get("strength_floor", p.get("strengthFloor", _grade_loop_mod.DEFAULT_STRENGTH_FLOOR))
+            ),
+            working_space=str(p.get("working_space") or p.get("workingSpace") or "rec709"),
+            cost_tier=str(p.get("cost_tier") or p.get("costTier") or _grade_loop_mod.DEFAULT_COST_TIER),
+        )
+        try:
+            # Dry run by default: the ladder can spend a dozen ffmpeg decodes per clip,
+            # and the plan names that budget before anyone commits to it.
+            if p.get("dry_run", True):
+                return _ok(**_grade_loop_mod.plan(source, lut, **kwargs))
+            return _ok(**_grade_loop_mod.run(
+                source, lut,
+                output_dir=(p.get("output_dir") or p.get("outputDir")) or None,
+                **kwargs,
+            ))
+        except (_grade_loop_mod.GradeLoopError, _grade_loop_mod.cube_lut.CubeLutError) as exc:
+            return _err(str(exc), code="GRADE_LOOP_REFUSED", category="invalid_input",
+                        remediation=(
+                            "Supply an existing source_path and a 3D .cube lut_path, plus "
+                            "times=[seconds,...] to sample. A grade clean on one frame is "
+                            "not a grade that passed."
+                        ))
+        except _grade_loop_mod.image_qc.ImageQcError as exc:
+            return _err(str(exc), code="IMAGE_QC_REFUSED", category="invalid_input")
+    if action == "grade_loop_capabilities":
+        from src.utils import grade_loop as _grade_loop_mod
+
+        return _ok(**_grade_loop_mod.capabilities())
     if action == "image_qc_capabilities":
         from src.utils import image_qc as _image_qc_mod
 
@@ -21028,6 +21080,8 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "capabilities",
         "recheck_capabilities",
         "assess_grade",
+        "grade_loop",
+        "grade_loop_capabilities",
         "image_qc_capabilities",
         "install_guidance",
         "resolve_output_root",

package/src/utils/cube_lut.py

@@ -0,0 +1,270 @@
+"""Read, write, and attenuate Iridas/Resolve `.cube` 3D LUTs.
+
+Exists to serve one operation the grade loop needs and nothing else has: producing a
+*weaker version of the same look*. When numeric image QC reports that a grade bands the
+sky or crunches the highlights, the remedy it prints is "reduce the strength" — and
+without a way to actually build the reduced LUT, that remedy is advice an agent cannot
+take.
+
+## Attenuation is a blend toward identity
+
+`blend_toward_identity(table, size, s)` returns `(1 - s)·identity + s·table`, which is
+the same thing a mix/strength control on a LUT node does. The blend happens in the LUT's
+own output encoding, not in a perceptual space: a look LUT's entries *are* output values,
+and re-encoding them to blend would change the look at s = 1, where the caller asked for
+no change at all. The identity endpoint is exact by construction, so s = 0 is a genuine
+no-op rather than an almost-no-op.
+
+## What this refuses
+
+1D LUTs (`LUT_1D_SIZE`) parse as a valid `.cube` and are not interchangeable with a 3D
+table; they are refused by name rather than silently reshaped. A `DOMAIN_MIN`/`DOMAIN_MAX`
+other than 0..1 is carried through untouched, and blending is refused on mismatched
+domains, because interpolating between two different input ranges produces a table that
+is wrong everywhere without ever looking malformed.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, Optional, Tuple
+
+try:
+    import numpy as _np
+except ImportError:  # pragma: no cover - guarded by capabilities()
+    _np = None  # type: ignore
+
+#: Every entry point that touches an array calls `_require_numpy()` first, so the
+#: arithmetic below treats `_np` as present. Declared machine-readably rather than left
+#: implied — see tests/test_optional_dependency_guards.py.
+_OPTIONAL_DEPENDENCY_CONTRACT = (
+    "numpy: every array entry point calls _require_numpy() first; internals assume it is present"
+)
+
+MIN_SIZE = 2
+MAX_SIZE = 256
+DEFAULT_WRITE_SIZE = 33
+
+
+class CubeLutError(Exception):
+    """A `.cube` file that cannot be read, or an operation that cannot be honest."""
+
+
+def _require_numpy() -> None:
+    if _np is None:
+        raise CubeLutError("numpy is required for LUT arithmetic (pip install numpy)")
+
+
+def read_cube(path: str) -> Dict[str, Any]:
+    """Parse a 3D `.cube` file into `{size, table, domain_min, domain_max, title}`.
+
+    `table` is an (N**3, 3) float array in the file's own order: red varies fastest,
+    then green, then blue. That ordering is the format's, and it is preserved rather
+    than normalised so a write-back round-trips byte-for-byte in value terms.
+    """
+    _require_numpy()
+    if not os.path.isfile(path):
+        raise CubeLutError(f"LUT not found: {path}")
+
+    size: Optional[int] = None
+    title = ""
+    domain_min = [0.0, 0.0, 0.0]
+    domain_max = [1.0, 1.0, 1.0]
+    rows = []
+
+    with open(path, "r", encoding="utf-8", errors="replace") as handle:
+        for line_number, raw in enumerate(handle, 1):
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            upper = line.upper()
+            if upper.startswith("LUT_1D_SIZE"):
+                raise CubeLutError(
+                    f"{path} is a 1D LUT. A 1D curve and a 3D cube are not "
+                    "interchangeable; supply a 3D .cube."
+                )
+            if upper.startswith("LUT_3D_SIZE"):
+                try:
+                    size = int(line.split()[1])
+                except (IndexError, ValueError):
+                    raise CubeLutError(f"{path}:{line_number}: malformed LUT_3D_SIZE")
+                if not MIN_SIZE <= size <= MAX_SIZE:
+                    raise CubeLutError(
+                        f"{path}: LUT_3D_SIZE {size} outside the supported range "
+                        f"{MIN_SIZE}-{MAX_SIZE}"
+                    )
+                continue
+            if upper.startswith("TITLE"):
+                match = re.match(r'TITLE\s+"?(.*?)"?\s*$', line, re.I)
+                title = match.group(1) if match else ""
+                continue
+            if upper.startswith("DOMAIN_MIN"):
+                domain_min = [float(value) for value in line.split()[1:4]]
+                continue
+            if upper.startswith("DOMAIN_MAX"):
+                domain_max = [float(value) for value in line.split()[1:4]]
+                continue
+            parts = line.split()
+            if len(parts) != 3:
+                raise CubeLutError(f"{path}:{line_number}: expected 3 values, got {len(parts)}")
+            try:
+                rows.append([float(value) for value in parts])
+            except ValueError:
+                raise CubeLutError(f"{path}:{line_number}: non-numeric entry '{line}'")
+
+    if size is None:
+        raise CubeLutError(f"{path}: no LUT_3D_SIZE — not a 3D .cube")
+    expected = size ** 3
+    if len(rows) != expected:
+        raise CubeLutError(
+            f"{path}: LUT_3D_SIZE {size} needs {expected} entries, found {len(rows)}"
+        )
+    return {
+        "size": size,
+        "table": _np.asarray(rows, dtype=_np.float64),
+        "domain_min": domain_min,
+        "domain_max": domain_max,
+        "title": title,
+        "path": path,
+    }
+
+
+def write_cube(
+    path: str,
+    table: "Any",
+    size: int,
+    *,
+    title: str = "",
+    domain_min: Optional[list] = None,
+    domain_max: Optional[list] = None,
+    precision: int = 6,
+) -> str:
+    """Write a 3D `.cube`. Returns the path written."""
+    _require_numpy()
+    array = _np.asarray(table, dtype=_np.float64)
+    if array.shape != (size ** 3, 3):
+        raise CubeLutError(
+            f"table shape {array.shape} does not match LUT_3D_SIZE {size} "
+            f"(expected {(size ** 3, 3)})"
+        )
+    directory = os.path.dirname(os.path.abspath(path))
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+    lines = []
+    if title:
+        lines.append(f'TITLE "{title}"')
+    lines.append(f"LUT_3D_SIZE {size}")
+    if domain_min and list(domain_min) != [0.0, 0.0, 0.0]:
+        lines.append("DOMAIN_MIN " + " ".join(f"{value:.6f}" for value in domain_min))
+    if domain_max and list(domain_max) != [1.0, 1.0, 1.0]:
+        lines.append("DOMAIN_MAX " + " ".join(f"{value:.6f}" for value in domain_max))
+    lines.append("")
+    for row in array:
+        lines.append(" ".join(f"{value:.{precision}f}" for value in row))
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+    return path
+
+
+def identity_table(size: int) -> "Any":
+    """The pass-through table for a cube of this size, in red-fastest order."""
+    _require_numpy()
+    if not MIN_SIZE <= size <= MAX_SIZE:
+        raise CubeLutError(f"size {size} outside {MIN_SIZE}-{MAX_SIZE}")
+    axis = _np.linspace(0.0, 1.0, size)
+    # Red fastest, then green, then blue — index = r + g*N + b*N*N.
+    blue, green, red = _np.meshgrid(axis, axis, axis, indexing="ij")
+    return _np.stack([red.ravel(), green.ravel(), blue.ravel()], axis=1)
+
+
+def blend_toward_identity(table: "Any", size: int, strength: float) -> "Any":
+    """`(1 - strength)·identity + strength·table`, clamped to [0, 1] strength.
+
+    strength 1.0 returns the table unchanged (not merely close to it), and 0.0 returns
+    exact identity. Values between are the same attenuation a LUT mix control applies.
+    """
+    _require_numpy()
+    amount = float(min(1.0, max(0.0, strength)))
+    array = _np.asarray(table, dtype=_np.float64)
+    if amount == 1.0:
+        return array.copy()
+    identity = identity_table(size)
+    if amount == 0.0:
+        return identity
+    return (1.0 - amount) * identity + amount * array
+
+
+def attenuate_file(
+    source_lut: str,
+    strength: float,
+    out_path: str,
+    *,
+    title_suffix: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Read a `.cube`, blend it toward identity, write the result. Returns a summary."""
+    parsed = read_cube(source_lut)
+    if parsed["domain_min"] != [0.0, 0.0, 0.0] or parsed["domain_max"] != [1.0, 1.0, 1.0]:
+        # Identity is only identity on a 0..1 domain. Blending against it on a scaled
+        # domain silently produces a table that is wrong across the whole range.
+        raise CubeLutError(
+            f"{source_lut} declares a non-unit domain "
+            f"({parsed['domain_min']}..{parsed['domain_max']}); attenuation toward "
+            "identity is only defined on 0..1"
+        )
+    blended = blend_toward_identity(parsed["table"], parsed["size"], strength)
+    suffix = title_suffix if title_suffix is not None else f" @ {round(float(strength), 3)}"
+    write_cube(
+        out_path,
+        blended,
+        parsed["size"],
+        title=(parsed["title"] or os.path.splitext(os.path.basename(source_lut))[0]) + suffix,
+    )
+    return {
+        "path": out_path,
+        "size": parsed["size"],
+        "strength": round(float(min(1.0, max(0.0, strength))), 4),
+        "source_lut": source_lut,
+    }
+
+
+def sample(table: "Any", size: int, rgb: "Any") -> "Any":
+    """Trilinearly interpolate the table at RGB inputs in [0, 1].
+
+    Present so the blending maths can be unit-tested without shelling out to ffmpeg.
+    The real pixel path is ffmpeg's `lut3d`, and that stays the measurement of record —
+    LUT interpolation and encode rounding are where banding is actually introduced.
+    """
+    _require_numpy()
+    array = _np.asarray(table, dtype=_np.float64).reshape(size, size, size, 3)
+    points = _np.clip(_np.atleast_2d(_np.asarray(rgb, dtype=_np.float64)), 0.0, 1.0)
+    scaled = points * (size - 1)
+    low = _np.floor(scaled).astype(int)
+    high = _np.minimum(low + 1, size - 1)
+    frac = scaled - low
+
+    out = _np.zeros((points.shape[0], 3), dtype=_np.float64)
+    for corner in range(8):
+        red_hi, green_hi, blue_hi = (corner >> 0) & 1, (corner >> 1) & 1, (corner >> 2) & 1
+        weight = (
+            (frac[:, 0] if red_hi else 1 - frac[:, 0])
+            * (frac[:, 1] if green_hi else 1 - frac[:, 1])
+            * (frac[:, 2] if blue_hi else 1 - frac[:, 2])
+        )
+        # Indexed [blue][green][red] because red varies fastest in the file order.
+        corner_values = array[
+            high[:, 2] if blue_hi else low[:, 2],
+            high[:, 1] if green_hi else low[:, 1],
+            high[:, 0] if red_hi else low[:, 0],
+        ]
+        out += weight[:, None] * corner_values
+    return out
+
+
+def capabilities() -> Dict[str, Any]:
+    return {
+        "numpy_available": _np is not None,
+        "supported": "3D .cube (Iridas/Resolve)",
+        "refused": "1D .cube; attenuation on a non-unit DOMAIN_MIN/MAX",
+        "size_range": [MIN_SIZE, MAX_SIZE],
+    }

package/src/utils/grade_loop.py

@@ -0,0 +1,356 @@
+"""The retry ladder that lets a grade reject itself.
+
+`image_qc.assess_grade` already measures whether a graded frame carries damage its
+source did not — banding in the sky, crushed highlights, amplified shadow grain — and
+every flag it raises carries a remedy. Until now nothing consumed that report. The
+measurement existed; the loop did not, so the remedy "reduce the strength" was advice
+an agent had no way to act on.
+
+This closes it. Given a source and a look LUT, the ladder applies the look, measures the
+real decoded result, and on any flag retries with the same look attenuated toward
+identity. The first strength that clears every gate wins.
+
+## What it never does
+
+Report a flagged result as acceptable. When the ladder is exhausted the return carries
+`needs_human` with the best attempt and its remaining flags — not a quiet success at a
+strength that still bands. `acceptable` is derived from the flag list at every rung and
+is never assigned.
+
+## Every sampled frame must pass
+
+A grade that is clean on the frame you happened to check and bands two hundred frames
+later has not passed anything. `times` accepts several timestamps and a strength is
+accepted only when *all* of them clear; the report names the frame that failed, because
+"the grade bands" and "the grade bands on the sky at 00:41" are different amounts of
+help.
+
+## The best attempt is the gentlest one
+
+When nothing converges, attempts are ranked by flag count and ties broken by the
+*smallest* colour shift. A tie on damage means choosing between two equally-flawed
+grades, and the one that moved the image less is the one a human has less to undo.
+
+## Cost
+
+The default `cost_tier` here is `numeric` rather than `image_qc`'s own default. The
+ladder runs several assessments per clip; escalating each of them to vision would spend
+host turns on rungs that exist only to be rejected. Pass a different tier deliberately.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from typing import Any, Dict, List, Optional, Sequence
+
+from . import cube_lut, image_qc
+
+# Each rung multiplies the last. Three rungs from 1.0 reach 0.64 — far enough to clear
+# most damage, short of the point where a look stops reading as itself.
+STRENGTH_DECAY = 0.8
+DEFAULT_MAX_TRIES = 3
+DEFAULT_STRENGTH_FLOOR = 0.5
+
+# Numeric assessment only. See the module docstring on cost.
+DEFAULT_COST_TIER = "numeric"
+
+
+class GradeLoopError(Exception):
+    """Bad inputs. Damage found in the image is a result, not an error."""
+
+
+def strength_schedule(
+    strength: float = 1.0,
+    max_tries: int = DEFAULT_MAX_TRIES,
+    floor: float = DEFAULT_STRENGTH_FLOOR,
+) -> List[float]:
+    """Decaying strengths, stopped when the floor makes another rung identical.
+
+    Two consecutive rungs that round to the same value would run the same LUT twice and
+    read as two independent failures. One clamped rung is evidence; a repeat of it is
+    not, so the schedule ends there.
+    """
+    start = float(min(1.0, max(0.0, strength)))
+    limit = float(min(start, max(0.0, floor)))
+    schedule: List[float] = []
+    current = start
+    for _ in range(max(1, int(max_tries))):
+        rung = round(max(current, limit), 4)
+        if schedule and schedule[-1] == rung:
+            break
+        schedule.append(rung)
+        current *= STRENGTH_DECAY
+    return schedule
+
+
+def _normalise_times(times: Any, time_seconds: Any) -> List[float]:
+    if times is None and time_seconds is None:
+        raise GradeLoopError("supply times=[...] or time_seconds=<float>")
+    raw = times if times is not None else time_seconds
+    if isinstance(raw, (int, float)):
+        raw = [raw]
+    if not isinstance(raw, (list, tuple)) or not raw:
+        raise GradeLoopError("times must be a non-empty list of seconds")
+    out: List[float] = []
+    for value in raw:
+        try:
+            seconds = float(value)
+        except (TypeError, ValueError):
+            raise GradeLoopError(f"'{value}' is not a timestamp in seconds")
+        if seconds < 0:
+            raise GradeLoopError("timestamps must be >= 0")
+        out.append(seconds)
+    return out
+
+
+def _flag_ids(report: Dict[str, Any]) -> List[str]:
+    return [str(flag.get("id")) for flag in report.get("flags", [])]
+
+
+def plan(
+    source_path: str,
+    lut_path: str,
+    *,
+    times: Optional[Sequence[float]] = None,
+    time_seconds: Optional[float] = None,
+    strength: float = 1.0,
+    max_tries: int = DEFAULT_MAX_TRIES,
+    strength_floor: float = DEFAULT_STRENGTH_FLOOR,
+    working_space: str = "rec709",
+    cost_tier: str = DEFAULT_COST_TIER,
+) -> Dict[str, Any]:
+    """What the ladder would do, and what it would cost. Touches nothing."""
+    sampled = _normalise_times(times, time_seconds)
+    schedule = strength_schedule(strength, max_tries, strength_floor)
+    for path in (source_path, lut_path):
+        if not os.path.isfile(path):
+            raise GradeLoopError(f"file not found: {path}")
+    return {
+        "dry_run": True,
+        "source_path": source_path,
+        "lut_path": lut_path,
+        "times": sampled,
+        "strength_schedule": schedule,
+        "strength_floor": round(float(min(strength, max(0.0, strength_floor))), 4),
+        "working_space": working_space,
+        "cost_tier": cost_tier,
+        "cost": {
+            "max_assessments": len(schedule) * len(sampled),
+            # assess_grade decodes the source frame and the LUT-applied frame per call.
+            "max_ffmpeg_decodes": 2 * len(schedule) * len(sampled),
+            "luts_written": max(0, len(schedule) - (1 if schedule and schedule[0] == 1.0 else 0)),
+            "note": (
+                "Worst case. The ladder stops at the first strength that clears every "
+                "sampled frame, and a frame that fails ends that rung early."
+            ),
+        },
+    }
+
+
+def run(
+    source_path: str,
+    lut_path: str,
+    *,
+    times: Optional[Sequence[float]] = None,
+    time_seconds: Optional[float] = None,
+    strength: float = 1.0,
+    max_tries: int = DEFAULT_MAX_TRIES,
+    strength_floor: float = DEFAULT_STRENGTH_FLOOR,
+    working_space: str = "rec709",
+    cost_tier: str = DEFAULT_COST_TIER,
+    output_dir: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Run the ladder. Returns the converged grade, or the best attempt flagged."""
+    sampled = _normalise_times(times, time_seconds)
+    schedule = strength_schedule(strength, max_tries, strength_floor)
+    for path in (source_path, lut_path):
+        if not os.path.isfile(path):
+            raise GradeLoopError(f"file not found: {path}")
+
+    # Attenuated LUTs are derived artifacts and go to scratch, never beside the source.
+    target_dir = output_dir or tempfile.mkdtemp(prefix="grade_loop_")
+    os.makedirs(target_dir, exist_ok=True)
+    base = os.path.splitext(os.path.basename(lut_path))[0]
+
+    attempts: List[Dict[str, Any]] = []
+    converged: Optional[Dict[str, Any]] = None
+
+    for rung in schedule:
+        if rung >= 1.0:
+            candidate = lut_path
+        else:
+            candidate = os.path.join(target_dir, f"{base}_{int(round(rung * 1000)):04d}.cube")
+            cube_lut.attenuate_file(lut_path, rung, candidate)
+
+        frames: List[Dict[str, Any]] = []
+        failing_frame: Optional[float] = None
+        for seconds in sampled:
+            report = image_qc.assess_grade(
+                source_path,
+                time_seconds=seconds,
+                lut_path=candidate,
+                working_space=working_space,
+                cost_tier=cost_tier,
+            )
+            frames.append(
+                {
+                    "time_seconds": seconds,
+                    "acceptable": bool(report.get("acceptable")),
+                    "flags": _flag_ids(report),
+                    "grade_shift_delta_e2000": report.get("grade_shift_delta_e2000"),
+                    "report": report,
+                }
+            )
+            if not report.get("acceptable"):
+                failing_frame = seconds
+                # No point measuring the rest of the frames at a strength already known
+                # to fail; the next rung has to run regardless.
+                break
+
+        flags = sorted({flag for frame in frames for flag in frame["flags"]})
+        shifts = [
+            frame["grade_shift_delta_e2000"]
+            for frame in frames
+            if frame["grade_shift_delta_e2000"] is not None
+        ]
+        attempt = {
+            "strength": rung,
+            "lut_path": candidate,
+            "acceptable": failing_frame is None,
+            "flags": flags,
+            "failing_time_seconds": failing_frame,
+            "frames_measured": len(frames),
+            "frames_total": len(sampled),
+            "max_grade_shift_delta_e2000": round(max(shifts), 3) if shifts else None,
+            "frames": frames,
+        }
+        attempts.append(attempt)
+        if failing_frame is None:
+            converged = attempt
+            break
+
+    if converged is not None:
+        chosen = converged
+    else:
+        # Fewest flags first; ties to the gentlest grade. A shift of None sorts last so
+        # an unmeasurable attempt never wins on a missing number.
+        chosen = min(
+            attempts,
+            key=lambda item: (
+                len(item["flags"]),
+                item["max_grade_shift_delta_e2000"]
+                if item["max_grade_shift_delta_e2000"] is not None
+                else float("inf"),
+            ),
+        )
+
+    remedies: List[Dict[str, str]] = []
+    seen_ids = set()
+    for frame in chosen["frames"]:
+        for flag in frame["report"].get("flags", []):
+            if flag.get("id") not in seen_ids:
+                seen_ids.add(flag.get("id"))
+                remedies.append(flag)
+
+    return {
+        "converged": converged is not None,
+        "needs_human": converged is None,
+        "acceptable": converged is not None,
+        "chosen": {
+            "strength": chosen["strength"],
+            "lut_path": chosen["lut_path"],
+            "flags": chosen["flags"],
+            "remedies": remedies,
+            "max_grade_shift_delta_e2000": chosen["max_grade_shift_delta_e2000"],
+        },
+        "attempts": [
+            {key: value for key, value in attempt.items() if key != "frames"}
+            for attempt in attempts
+        ],
+        "reports": {
+            str(attempt["strength"]): [
+                {"time_seconds": frame["time_seconds"], "report": frame["report"]}
+                for frame in attempt["frames"]
+            ]
+            for attempt in attempts
+        },
+        "strength_schedule": schedule,
+        "times": sampled,
+        "source_path": source_path,
+        "lut_path": lut_path,
+        "output_dir": target_dir,
+        "working_space": working_space,
+        "cost_tier": cost_tier,
+        "apply_manifest": _apply_manifest(chosen, converged is not None),
+        "summary": _summary(chosen, converged is not None, schedule, attempts),
+    }
+
+
+def _apply_manifest(chosen: Dict[str, Any], converged: bool) -> Dict[str, Any]:
+    """How to put the chosen LUT into Resolve, and whether it should be put there yet.
+
+    The ladder does not touch the project. Applying a grade is a separate, versioned,
+    confirm-gated operation, and a result carrying unresolved flags should reach a human
+    before it reaches a timeline.
+    """
+    return {
+        "lut_path": chosen["lut_path"],
+        "strength": chosen["strength"],
+        "safe_to_apply": converged,
+        "apply_with": (
+            "timeline_item_color(action='apply_lut', params={'lut_path': ..., "
+            "'clip_index': ...}) — create or switch to a recoverable grade version first"
+        ),
+        "blocked_reason": None if converged else (
+            "The grade still carries measured damage at every strength tried. Read the "
+            "remedies, adjust the look, or accept it deliberately — do not apply on the "
+            "strength of this report alone."
+        ),
+    }
+
+
+def _summary(
+    chosen: Dict[str, Any],
+    converged: bool,
+    schedule: List[float],
+    attempts: List[Dict[str, Any]],
+) -> str:
+    if converged:
+        if chosen["strength"] >= 1.0:
+            return "Clean at full strength; no attenuation needed."
+        # What the FIRST rung carried is the interesting part — the chosen rung is
+        # clean by definition, so quoting its (empty) flag list says nothing.
+        first = ", ".join(attempts[0]["flags"]) or "damage"
+        return (
+            f"Converged at strength {chosen['strength']}; "
+            f"strength {attempts[0]['strength']} carried {first}."
+        )
+    return (
+        f"No strength cleared every gate across {len(schedule)} attempts "
+        f"({schedule[0]} down to {schedule[-1]}). Best attempt {chosen['strength']} "
+        f"still carries: {', '.join(chosen['flags'])}."
+    )
+
+
+def capabilities() -> Dict[str, Any]:
+    report = dict(image_qc.capabilities())
+    report.update(
+        {
+            "cube_lut": cube_lut.capabilities(),
+            "default_cost_tier": DEFAULT_COST_TIER,
+            "cost_tiers": list(image_qc.COST_TIERS),
+            "strength_decay": STRENGTH_DECAY,
+            "default_max_tries": DEFAULT_MAX_TRIES,
+            "default_strength_floor": DEFAULT_STRENGTH_FLOOR,
+            "modes": {
+                "lut": "Built and validated offline: attenuate a .cube and measure the real decoded result.",
+                "live": (
+                    "Not built. Applying inside the loop needs a per-rung single-frame "
+                    "render from Resolve; until that is live-validated the loop returns "
+                    "an apply manifest instead of driving the project."
+                ),
+            },
+        }
+    )
+    return report