@motionharness/bridge-davinci 0.0.0-stage → 0.0.23

package/dist/resolve_rpc.py

@@ -0,0 +1,1451 @@
+#!/usr/bin/env python3
+"""One JSON request over stdin. Only documented Resolve scripting APIs are used.
+
+Only explicit targets and owned render IDs can be modified. Resolve's database
+is never edited directly. Updating a bound media-pool item leaves its timeline
+instances and effects under Resolve ownership.
+"""
+import hashlib
+import importlib
+import json
+import math
+import os
+import platform
+import shutil
+import sys
+import tempfile
+import time
+import uuid
+import xml.etree.ElementTree as ET
+from collections import OrderedDict  # Fusion's Python table decoder evaluates ordered() tables in __main__.
+from contextlib import contextmanager
+from urllib.parse import unquote, urlparse
+
+# Runtime helpers are shipped beside this adapter; importing them is offline.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import inspector_runtime as inspector
+import intrinsic_runtime as intrinsic
+import instance_runtime as instances
+import legacy_conversion as legacy
+from runtime_io import atomic_json, file_digest
+
+# Frame boundaries were read back on this exact build; do not extrapolate to unknown builds.
+VALIDATED_BUILD = "21.1.0.14"
+SUPPORTED_INSPECTOR_EFFECTS = {
+    "Transform", "Source Transform", "Immersive Transform", "Cropping", "Source Cropping",
+    "Source Looks", "Dynamic Zoom", "Composite", "Lens Correction", "Retime and Scaling",
+    "Video Faders", "Immersive Output Transform",
+}
+ORIGINAL_PLAYBACK = {"perfProxyMediaMode": "0", "perfOptimisedMediaOn": "0", "perfRenderCacheMode": "none"}
+
+
+def validated_host(resolve):
+    return resolve.GetVersionString() == VALIDATED_BUILD and sys.platform == "darwin" and platform.machine() == "arm64"
+
+
+class BridgeFailure(Exception):
+    def __init__(self, code, message, **details):
+        super().__init__(message)
+        self.code, self.message, self.details = code, message, details
+
+
+def require(value, code, message, **details):
+    if not value:
+        raise BridgeFailure(code, message, **details)
+
+
+def fingerprint(value):
+    return "sha256:" + hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+
+
+def connect():
+    api = os.environ.get("RESOLVE_SCRIPT_API", "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting")
+    sys.path.insert(0, os.path.join(api, "Modules"))
+    try:
+        module = importlib.import_module("DaVinciResolveScript")
+        resolve = module.scriptapp("Resolve")
+    except Exception as error:
+        raise BridgeFailure("CAPABILITY_UNAVAILABLE", "无法加载 Resolve 脚本模块。", diagnostic=str(error))
+    require(resolve, "RESOLVE_UNAVAILABLE", "请启动 Resolve Studio，并启用本机外部脚本访问。")
+    return resolve
+
+
+def scope_for(manager, project):
+    database = manager.GetCurrentDatabase()
+    deadline = time.monotonic() + 5
+    # During StartRendering the UI can briefly return no database through the scripting bridge.
+    while not database and time.monotonic() < deadline:
+        time.sleep(0.05)
+        database = manager.GetCurrentDatabase()
+    require(isinstance(database, dict) and database, "CAPABILITY_UNAVAILABLE", "无法读取 Resolve 数据库作用域。")
+    return {"databaseId": fingerprint(database), "projectId": project.GetUniqueId()}
+
+
+def project_for(resolve, requested=None, render_proof=None):
+    manager = resolve.GetProjectManager()
+    project = manager.GetCurrentProject()
+    require(project, "PROJECT_MISSING", "Resolve 当前没有打开工程。")
+    # GetCurrentDatabase returns None throughout some renders on 21.1.0.14.
+    # Monitoring/cancelling an already-started job may use its previously
+    # verified project + complete queue fingerprint; starting still requires DB.
+    if (render_proof and requested and not manager.GetCurrentDatabase()
+            and validated_host(resolve) and project.IsRenderingInProgress()):
+        require(project.GetUniqueId() == requested["projectId"], "VERSION_CONFLICT", "运行中的任务已不属于原工程。")
+        job = render_job(project, render_proof["jobId"])
+        require(render_proof.get("expectedJobFingerprint") and fingerprint(job) == render_proof["expectedJobFingerprint"],
+                "VERSION_CONFLICT", "运行中的队列 ID 或设置与启动前记录不一致。")
+        scope = requested
+    else:
+        scope = scope_for(manager, project)
+    if requested is not None:
+        require(scope == requested, "VERSION_CONFLICT", "Resolve 当前工程与明确指定的作用域不一致。", actual=scope)
+        require_active_project(resolve, project)
+    return project, scope
+
+
+def timelines(project):
+    return [project.GetTimelineByIndex(i) for i in range(1, project.GetTimelineCount() + 1)]
+
+
+def timeline_for(project, timeline_id):
+    found = [t for t in timelines(project) if t and t.GetUniqueId() == timeline_id]
+    require(len(found) == 1, "TIMELINE_MISSING", "指定时间线不存在，未按名称猜测。")
+    return found[0]
+
+
+def all_media(folder):
+    result = list(folder.GetClipList() or [])
+    for child in folder.GetSubFolderList() or []:
+        result.extend(all_media(child))
+    return result
+
+
+def media_for(project, media_id):
+    found = [m for m in all_media(project.GetMediaPool().GetRootFolder()) if m.GetUniqueId() == media_id]
+    require(len(found) == 1, "MEDIA_MISSING", "指定媒体池对象不存在，未按文件名猜测。")
+    return found[0]
+
+
+def ofx_source_target(resolve, params):
+    """Match the actual input file to its registered media-pool identity.
+
+    Read file paths once to reject ambiguous imports. Only the target's bridge
+    metadata matters; unrelated subtitles, generators and metadata are ignored.
+    """
+    requested = params.get("scope")
+    media_id, raw_path = params.get("mediaPoolItemId"), params.get("path")
+    valid = lambda value: isinstance(value, str) and bool(value.strip()) and "\0" not in value
+    require(isinstance(requested, dict) and set(requested) == {"databaseId", "projectId"}
+            and all(valid(value) for value in requested.values()) and valid(media_id),
+            "INVALID_ARGUMENT", "侧栏入口需要明确的数据库、工程和素材池对象 ID。")
+    require(valid(raw_path) and os.path.isabs(raw_path), "INVALID_ARGUMENT", "侧栏源路径必须是非空绝对路径。")
+    path = os.path.realpath(raw_path)
+    project, scope = project_for(resolve, requested)
+    matches = []
+    for media in all_media(project.GetMediaPool().GetRootFolder()):
+        try:
+            properties = media.GetClipProperty() or {}
+            source_path = properties.get("File Path")
+        except Exception:
+            require(media.GetUniqueId() != media_id, "CAPABILITY_UNAVAILABLE", "无法读取目标素材的文件路径。")
+            continue
+        if valid(source_path) and os.path.isabs(source_path) and os.path.realpath(source_path) == path:
+            matches.append(media)
+    require(len(matches) == 1 and matches[0].GetUniqueId() == media_id,
+            "VERSION_CONFLICT", "侧栏源路径没有对应唯一且匹配的素材池对象；请从固定菜单管理片段。")
+    result = media_identity(project, scope, matches[0])
+    require(os.path.realpath(result["path"]) == path, "VERSION_CONFLICT", "目标素材已被重新链接。")
+    project_for(resolve, requested)
+    return {**result, "path": path, "unique": True}
+
+
+def fps_value(value):
+    text = str(value).replace(" DF", "").strip()
+    if text in ("29.97", "29.970", "29.97002997002997"):
+        return {"num": 30000, "den": 1001}
+    number = float(text)
+    require(number in (25.0, 30.0), "UNSUPPORTED_FPS", "首版只接受 25、30 和 30000/1001 fps。", actual=text)
+    return {"num": int(number), "den": 1}
+
+
+def native_timeline_frames(count, source_fps, timeline_fps):
+    frames = count * timeline_fps["num"] * source_fps["den"] // (timeline_fps["den"] * source_fps["num"])
+    require(frames > 0, "INVALID_RANGE", "源区间不足一个目标时间线帧。")
+    return frames
+
+
+def sample_end_time(start, timeline_frames, source_fps, timeline_fps, source_frames):
+    source_rate, timeline_rate = source_fps["num"] / source_fps["den"], timeline_fps["num"] / timeline_fps["den"]
+    return min(source_frames / source_rate, start / source_rate + (timeline_frames - 1) / timeline_rate + 1 / source_rate)
+
+
+def item_snapshot(item, timeline_id, track, validated=False, media_index=None, timeline_fps=None):
+    media = item.GetMediaPoolItem()
+    intrinsic_entry = intrinsic.read_entry(item, media_index or {}) if validated and not media else None
+    if intrinsic_entry:
+        media = media_index[intrinsic_entry['identity']['mediaPoolItemId']]
+    unsupported = [] if validated else ["host-build-and-frame-conventions-unverified"]
+    kind = item.GetType() if validated else "unknown"
+    if not media and kind != "transition":
+        unsupported.append("no-plain-media-source")
+    fusion_count = item.GetFusionCompCount() if media else 0
+    entry = inspector.read_entry(item) if fusion_count > 0 and not intrinsic_entry else None
+    if fusion_count > 0 and not intrinsic_entry:
+        if entry:
+            if not inspector.experimental_enabled(): unsupported.append("inspector-entry-unverified")
+        else:
+            unsupported.append("fusion-composition")
+    if media and item.GetTakesCount() > 0:
+        unsupported.append("take-selector-or-multicam")
+    props = media.GetClipProperty() if media else {}
+    speed, properties, fades = None, None, None
+    if validated and media:
+        if media.GetTimeline():
+            unsupported.append("nested-or-compound-timeline")
+        if kind != "video":
+            unsupported.append("not-plain-video-item")
+        speed, properties, fades = item.GetSpeed(), item.GetProperties(), item.GetFades()
+        if properties.get("Distortion"):
+            unsupported.append("lens-correction-unverified")
+        percentage = speed.get("Percentage") if isinstance(speed, dict) else None
+        if not isinstance(percentage, (int, float)) or not math.isfinite(percentage):
+            unsupported.append("speed-state-unverified")
+        if str(props.get("Audio Ch", "0")) not in ("", "0"):
+            unsupported.append("source-audio-unsupported")
+        if intrinsic_entry:
+            attrs = item.GetFusionCompByIndex(1).GetAttrs()
+            source_in, source_out = int(attrs['COMPN_GlobalStart']), int(attrs['COMPN_GlobalEnd']) + 1
+        else:
+            source_in, source_out = item.GetSourceStartFrame(), item.GetSourceEndFrame()
+        source_fps = None
+        try:
+            source_fps = fps_value(props.get("FPS"))
+        except (BridgeFailure, TypeError, ValueError):
+            unsupported.append("source-fps-unverified")
+        cross_fps = source_fps and timeline_fps and source_fps != timeline_fps
+        # 21.1.0.14 clamps GetSourceEndFrame to the last inclusive media frame at
+        # EOF, although AppendToTimeline and GetSourceEndTime stay half open.
+        # Normalize only that observed case, with independent time/offset proof.
+        if percentage == 100 and not cross_fps and source_out - source_in + 1 == item.GetEnd() - item.GetStart():
+            try:
+                rate = fps_value(props.get("FPS"))
+                timed_end = item.GetSourceEndTime() * rate["num"] / rate["den"]
+                if (int(props.get("Start", 0)) == 0 and source_out + 1 == int(props["Frames"])
+                        and item.GetRightOffset() == 0 and abs(timed_end - (source_out + 1)) < 0.001):
+                    source_out += 1
+            except (BridgeFailure, KeyError, TypeError, ValueError, AttributeError):
+                pass
+        if cross_fps:
+            if percentage != 100:
+                unsupported.append("cross-fps-retime-unverified")
+            else:
+                source_rate = source_fps["num"] / source_fps["den"]
+                sample_start, sample_end = item.GetSourceStartTime(), item.GetSourceEndTime()
+                expected_end = sample_end_time(source_in, item.GetEnd() - item.GetStart(), source_fps, timeline_fps, int(props["Frames"]))
+                if not all(isinstance(value, (int, float)) and math.isfinite(value) for value in (sample_start, sample_end)) or abs(sample_end - expected_end) > 1e-6:
+                    unsupported.append("source-sampling-or-variable-retime-unverified")
+                else:
+                    # Source frames may be fractional on a different-rate timeline.
+                    # These half-open sample bounds come from the native time API.
+                    source_in, source_out = sample_start * source_rate, sample_end * source_rate
+        elif percentage == 100 and source_out - source_in != item.GetEnd() - item.GetStart():
+            unsupported.append("source-sampling-or-variable-retime-unverified")
+    else:
+        source_in, source_out = item.GetSourceStartFrame(), item.GetSourceEndFrame()
+    return {
+        "id": item.GetUniqueId(), "timelineId": timeline_id, "track": track,
+        "startFrame": item.GetStart(), "endFrame": item.GetEnd(),
+        "sourceIn": source_in, "sourceOut": source_out,
+        "mediaPoolItemId": media.GetUniqueId() if media else None, "unsupported": unsupported,
+        "kind": kind, "speed": speed, "properties": properties, "fades": fades,
+        "enabled": item.GetClipEnabled() if validated and media else None,
+        "sourceStartTime": item.GetSourceStartTime() if validated and media else None,
+        "sourceEndTime": item.GetSourceEndTime() if validated and media else None,
+        "leftOffset": item.GetLeftOffset() if validated and media else None,
+        "rightOffset": item.GetRightOffset() if validated and media else None,
+        "markers": item.GetMarkers() if validated and media else None,
+        **({"inspectorEntry": entry} if entry else {}),
+        **({"intrinsicEntry": intrinsic_entry} if intrinsic_entry else {}),
+    }
+
+
+def otio_seconds(value):
+    try:
+        rate, number = float(value["rate"]), float(value["value"])
+        return number / rate if rate > 0 and math.isfinite(rate) and math.isfinite(number) else None
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def otio_effect_reasons(effects):
+    reasons = []
+    for effect in effects:
+        kind, scalar = effect.get("OTIO_SCHEMA"), effect.get("time_scalar")
+        if (kind == "FreezeFrame.1" and scalar == 0
+                or kind == "LinearTimeWarp.1" and isinstance(scalar, (int, float)) and math.isfinite(scalar) and scalar != 0):
+            continue
+        metadata = effect.get("metadata", {}).get("Resolve_OTIO", {})
+        name = metadata.get("Effect Name")
+        if (metadata.get("Enabled") is False and str(effect.get("OTIO_SCHEMA", "")).startswith("Effect.")
+                and effect.get("effect_name") == "Resolve Effect"):
+            continue
+        if (not str(effect.get("OTIO_SCHEMA", "")).startswith("Effect.")
+                or effect.get("effect_name") != "Resolve Effect" or name not in SUPPORTED_INSPECTOR_EFFECTS):
+            reasons.append("unsupported-otio-effect-or-retime")
+        if name == "Retime and Scaling" and metadata.get("Parameters"):
+            reasons.append("retime-parameters-unverified")
+        if name not in ("Video Faders", "Dynamic Zoom") and any(len(parameter.get("Key Frames", {})) > 1 for parameter in metadata.get("Parameters", []) if isinstance(parameter, dict)):
+            reasons.append("animated-inspector-unverified")
+    return sorted(set(reasons))
+
+
+def inspect_otio(document):
+    """Conservative semantic digest, independent of the artifact's new filename/path."""
+    reasons, clips, coverage, global_reasons = [], [], [], []
+    tracks = document.get("tracks", {})
+    if not str(document.get("OTIO_SCHEMA", "")).startswith("Timeline.") or not str(tracks.get("OTIO_SCHEMA", "")).startswith("Stack."):
+        return {"complete": False, "reasons": ["otio-root-unrecognized"], "hash": None}
+    semantics = []
+    if tracks.get("effects"):
+        global_reasons.append("otio-stack-effects-unverified")
+    for track in tracks.get("children", []):
+        if track.get("kind") != "Video":
+            continue
+        if not str(track.get("OTIO_SCHEMA", "")).startswith("Track."):
+            global_reasons.append("nested-otio-track")
+        children, track_clips, track_reasons, cursor = [], [], [], 0.0
+        if track.get("effects") or track.get("source_range") is not None:
+            track_reasons.append("otio-track-effects-or-trim-unverified")
+        for child in track.get("children", []):
+            kind = str(child.get("OTIO_SCHEMA", "")).split(".")[0]
+            child_reasons = otio_effect_reasons(child.get("effects", []))
+            if kind == "Transition":
+                transition = child.get("metadata", {}).get("Resolve_OTIO", {})
+                if child.get("transition_type") != "SMPTE_Dissolve" or transition.get("Transition Type") != "Cross Dissolve":
+                    track_reasons.append("unsupported-transition")
+            elif kind not in ("Clip", "Gap"):
+                global_reasons.append("nested-or-unknown-otio-item")
+            effects = child.get("effects", [])
+            duration = otio_seconds((child.get("source_range") or {}).get("duration"))
+            if kind == "Clip":
+                clips.append(child)
+                refs = child.get("media_references", {})
+                reference = child.get("media_reference") or refs.get(child.get("active_media_reference_key")) or {}
+                reference_type = str(reference.get("OTIO_SCHEMA", ""))
+                if reference_type.startswith("MissingReference."):
+                    child_reasons.append("offline-media-reference")
+                elif not reference_type.startswith("ExternalReference."):
+                    child_reasons.append("nested-media-reference")
+                track_clips.append({"startSeconds": cursor, "durationSeconds": duration,
+                                    "path": reference.get("target_url"), "referenceType": reference_type,
+                                    "effects": effects,
+                                    "reasons": sorted(set(child_reasons))})
+            else:
+                track_reasons.extend(child_reasons)
+            reasons.extend(child_reasons)
+            # Resolve's OTIO duration already represents the timeline span, even
+            # for LinearTimeWarp. Transitions overlap adjacent spans, not gaps.
+            if kind != "Transition":
+                cursor = cursor + duration if cursor is not None and duration is not None and duration >= 0 else None
+            children.append({"kind": kind, "range": child.get("source_range"), "inOffset": child.get("in_offset"), "outOffset": child.get("out_offset"), "transitionType": child.get("transition_type"), "effects": effects,
+                             "metadata": child.get("metadata", {})})
+        semantics.append({"children": children, "effects": track.get("effects", []), "range": track.get("source_range")})
+        reasons.extend(track_reasons)
+        coverage.append({"clips": track_clips, "reasons": sorted(set(track_reasons))})
+    reasons = sorted(set(reasons + global_reasons))
+    return {"complete": not reasons, "reasons": reasons, "globalReasons": sorted(set(global_reasons)),
+            "hash": fingerprint({"tracks": semantics, "stackEffects": tracks.get("effects", [])}), "clipCount": len(clips), "tracks": coverage}
+
+
+def otio_item_reasons(evidence, items, paths, timeline_start, fps):
+    """Match each exported clip to a native track/span/path before scoping effects.
+
+    A retime elsewhere must not poison a plain bridge clip. Unknown structure or
+    a failed match still blocks coverage; never assign effects by name or count.
+    """
+    result = {item["id"]: list(evidence.get("globalReasons", evidence["reasons"])) for item in items}
+    if "tracks" not in evidence:
+        return result
+    rate = fps["num"] / fps["den"]
+    for track, details in enumerate(evidence["tracks"], 1):
+        native = sorted((item for item in items if item["track"] == track and item["kind"] == "video" and item["mediaPoolItemId"]), key=lambda item: item["startFrame"])
+        exported = details["clips"]
+        matched = len(native) == len(exported)
+        for item, clip in zip(native, exported):
+            start, duration = clip["startSeconds"], clip["durationSeconds"]
+            path = clip["path"]
+            if path:
+                parsed = urlparse(path)
+                path = unquote(parsed.path) if parsed.scheme == "file" and parsed.netloc in ("", "localhost") else path
+            matched = matched and start is not None and duration is not None and (
+                abs(start * rate - (item["startFrame"] - timeline_start)) < 0.01
+                and abs(duration * rate - (item["endFrame"] - item["startFrame"])) < 0.01)
+            if clip["referenceType"].startswith("ExternalReference."):
+                matched = matched and not item.get('intrinsicEntry') and bool(path) and os.path.realpath(path) == os.path.realpath(paths[item["id"]])
+            elif clip["referenceType"].startswith("MissingReference.") and item.get('intrinsicEntry'):
+                matched = matched and not path
+        if not matched:
+            for item in items:
+                if item["track"] == track:
+                    result[item["id"]].append("otio-item-coverage-mismatch")
+        for item, clip in zip(native, exported):
+            clip_reasons = list(clip["reasons"])
+            if matched and item.get('intrinsicEntry') and clip['referenceType'].startswith('MissingReference.'):
+                # Native generators export MissingReference even when their
+                # separately verified MediaIn reads an online media-pool item.
+                clip_reasons = [r for r in clip_reasons if r != 'offline-media-reference']
+            entry = item.get("inspectorEntry")
+            if matched and entry and inspector.experimental_enabled():
+                effects = clip.get("effects", [])
+                own = inspector.unknown_effects(effects, SUPPORTED_INSPECTOR_EFFECTS)
+                if inspector.signature(own) == entry.get("otioEffectsFingerprint"):
+                    # Only the exact effects captured after attaching to a plain
+                    # clip can be waived. Other effects/animation stay guarded.
+                    ordinary = [effect for effect in effects if effect not in own]
+                    clip_reasons = sorted((set(clip_reasons) - set(otio_effect_reasons(effects))) | set(otio_effect_reasons(ordinary)))
+            if matched:
+                time_effects = [effect for effect in clip.get("effects", []) if effect.get("OTIO_SCHEMA") in ("LinearTimeWarp.1", "FreezeFrame.1")]
+                percentage = (item.get("speed") or {}).get("Percentage")
+                if percentage != 100 and (len(time_effects) != 1 or not isinstance(percentage, (int, float))
+                        or not isinstance(time_effects[0].get("time_scalar"), (int, float))
+                        or abs(time_effects[0]["time_scalar"] * 100 - percentage) > 0.000001):
+                    clip_reasons.append("retime-native-and-otio-disagree")
+                if percentage == 100 and any(effect.get("time_scalar") != 1 for effect in time_effects):
+                    clip_reasons.append("retime-native-and-otio-disagree")
+            result[item["id"]].extend(details["reasons"] + (clip_reasons if matched else []))
+        if not native and (exported or details["reasons"]):
+            for item in items:
+                result[item["id"]].append("otio-item-coverage-mismatch")
+    for item in items:
+        if item["track"] > len(evidence["tracks"]):
+            result[item["id"]].append("otio-item-coverage-mismatch")
+    return result
+
+
+def otio_evidence(resolve, timeline):
+    project = resolve.GetProjectManager().GetCurrentProject()
+    previous = project.GetCurrentTimeline()
+    try:
+        # Export has a current-timeline context on this build even when called
+        # through another Timeline object. Never fingerprint the selected tab.
+        require(project.SetCurrentTimeline(timeline), "CAPABILITY_UNAVAILABLE", "无法明确设置结构检查时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        with tempfile.TemporaryDirectory(prefix="mh-bridge-otio-") as directory:
+            path = os.path.join(directory, "timeline.otio")
+            if not timeline.Export(path, resolve.EXPORT_OTIO):
+                raise RuntimeError("OTIO export unavailable")
+            with open(path, encoding="utf8") as file:
+                return inspect_otio(json.load(file))
+    except BridgeFailure:
+        raise
+    except Exception:
+        return {"complete": False, "reasons": ["otio-inspection-unavailable"], "hash": None}
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if (active and active.GetUniqueId() == project.GetUniqueId() and previous
+                and previous.GetUniqueId() != timeline.GetUniqueId()
+                and project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId()):
+            project.SetCurrentTimeline(previous)
+            await_timeline(project, previous, resolve=resolve)
+
+
+def identity_lut(data):
+    if not data or data[0] != "LUT_3D_SIZE 17" or len(data) != 4914:
+        return False
+    try:
+        for index, line in enumerate(data[1:]):
+            values = [float(value) for value in line.split()]
+            expected = ((index % 17) / 16, ((index // 17) % 17) / 16, (index // 289) / 16)
+            # Resolve may export its identity cube on a 16-bit floor-quantized
+            # grid (4095/65535 instead of 1/16). Accept these exact two grids,
+            # with text serialization tolerance; a broad color tolerance would
+            # incorrectly accept a real primary correction as identity.
+            if len(values) != 3 or any(not math.isfinite(value) or min(abs(value - wanted), abs(value - math.floor(wanted * 65535) / 65535)) > .000001
+                                      for value, wanted in zip(values, expected)):
+                return False
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+def grade_evidence(resolve, timeline, native_items, intrinsic_ids=None):
+    """ExportLUT is a public Color-page API; select and restore its context explicitly."""
+    result = {}
+    project, _scope = project_for(resolve)
+    previous, page = project.GetCurrentTimeline(), resolve.GetCurrentPage()
+    try:
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "渲染期间不能完整检查调色。")
+        require(project.SetCurrentTimeline(timeline), "CAPABILITY_UNAVAILABLE", "无法设置调色检查时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        require(resolve.OpenPage("color"), "CAPABILITY_UNAVAILABLE", "无法进入受支持的调色检查上下文。")
+        await_page(resolve, project, "color")
+        with tempfile.TemporaryDirectory(prefix="mh-bridge-grade-") as directory:
+            for item in native_items:
+                intrinsic_item = item.GetUniqueId() in (intrinsic_ids or set())
+                if not intrinsic_item and (item.GetType() != "video" or not item.GetMediaPoolItem()):
+                    continue
+                reasons = []
+                graph = item.GetNodeGraph()
+                tools = [graph.GetToolsInNode(index) or [] for index in range(1, graph.GetNumNodes() + 1)] if graph else []
+                allowed_tools = {"一级平衡", "饱和度，色相与亮度 混合", "Primaries", "Saturation, Hue and Lum Mix", "Primary Balance"}
+                if any(tool not in allowed_tools for group in tools for tool in group) or item.GetColorGroup():
+                    reasons.append("grade-tools-or-group-unverified")
+                path = os.path.join(directory, item.GetUniqueId() + ".cube")
+                deadline, exported = time.monotonic() + 3, False
+                while time.monotonic() < deadline:
+                    require_active_project(resolve, project)
+                    require(project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId() and resolve.GetCurrentPage() == "color", "VERSION_CONFLICT", "调色检查期间上下文被另一控制端修改。")
+                    if item.ExportLUT(resolve.EXPORT_LUT_17PTCUBE, path):
+                        exported = True
+                        break
+                    time.sleep(0.05)
+                if exported:
+                    with open(path, encoding="utf8") as file:
+                        data = [line.strip() for line in file if line.strip() and not line.startswith(("TITLE", "#"))]
+                    require(data and data[0] == "LUT_3D_SIZE 17" and len(data) >= 4914, "CAPABILITY_UNAVAILABLE", "调色校验 LUT 不完整。")
+                    result[item.GetUniqueId()] = {"hash": fingerprint({"lut": data, "tools": tools, "version": item.GetCurrentVersion()}), "unsupported": reasons, "identity": identity_lut(data)}
+                else:
+                    result[item.GetUniqueId()] = {"hash": None, "unsupported": ["grade-inspection-unavailable"], "identity": False}
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if active and active.GetUniqueId() == project.GetUniqueId() and project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId() and resolve.GetCurrentPage() == "color":
+            if previous and previous.GetUniqueId() != timeline.GetUniqueId():
+                project.SetCurrentTimeline(previous)
+                await_timeline(project, previous, resolve=resolve)
+            if page != "color":
+                resolve.OpenPage(page)
+                await_page(resolve, project, page)
+    return result
+
+
+@contextmanager
+def timeline_context(resolve, timeline):
+    if resolve is None or not validated_host(resolve):
+        yield
+        return
+    project = resolve.GetProjectManager().GetCurrentProject()
+    previous = project.GetCurrentTimeline()
+    try:
+        require(project.SetCurrentTimeline(timeline), "CAPABILITY_UNAVAILABLE", "无法明确设置检查时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        yield
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if (active and active.GetUniqueId() == project.GetUniqueId() and previous
+                and previous.GetUniqueId() != timeline.GetUniqueId()
+                and project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId()):
+            project.SetCurrentTimeline(previous)
+            await_timeline(project, previous, resolve=resolve)
+
+
+def scan_timeline(timeline, resolve=None, grade_media_id=None):
+    with timeline_context(resolve, timeline):
+        return scan_current_timeline(timeline, resolve, grade_media_id)
+
+
+def scan_current_timeline(timeline, resolve=None, grade_media_id=None):
+    validated = resolve is not None and validated_host(resolve)
+    items, native_items, paths = [], [], {}
+    media_index = None
+    for track in range(1, timeline.GetTrackCount("video") + 1):
+        native = timeline.GetItemListInTrack("video", track) or []
+        native_items.extend(native)
+        for item in native:
+            if validated and not item.GetMediaPoolItem() and item.GetFusionCompCount() > 0 and media_index is None:
+                project = resolve.GetProjectManager().GetCurrentProject()
+                media_index = {m.GetUniqueId(): m for m in all_media(project.GetMediaPool().GetRootFolder())}
+            snapshot = item_snapshot(item, timeline.GetUniqueId(), track, validated, media_index, fps_value(timeline.GetSetting("timelineFrameRate")) if validated else None)
+            snapshot.update(trackEnabled=timeline.GetIsTrackEnabled("video", track) if validated else None,
+                            trackLocked=timeline.GetIsTrackLocked("video", track) if validated else None)
+            items.append(snapshot)
+            if validated and item.GetMediaPoolItem():
+                paths[snapshot["id"]] = item.GetMediaPoolItem().GetClipProperty("File Path") or ""
+            elif snapshot.get('intrinsicEntry'):
+                paths[snapshot['id']] = media_index[snapshot['mediaPoolItemId']].GetClipProperty('File Path') or ''
+    evidence = otio_evidence(resolve, timeline) if validated and items else {"complete": not items, "reasons": [], "hash": None}
+    if validated and items and evidence.get("clipCount") != sum(1 for item in items if item["kind"] == "video" and item["mediaPoolItemId"]):
+        evidence["reasons"] = sorted(set(evidence["reasons"] + ["otio-item-coverage-mismatch"]))
+        evidence["globalReasons"] = sorted(set(evidence.get("globalReasons", evidence["reasons"]) + ["otio-item-coverage-mismatch"]))
+    scoped_reasons = otio_item_reasons(evidence, items, paths, timeline.GetStartFrame(), fps_value(timeline.GetSetting("timelineFrameRate"))) if validated and items else {}
+    # A media readback retains grades only for that media's uses. Keep every
+    # native item and OTIO check for indirect references, but avoid exporting
+    # unrelated LUTs. Whole-timeline snapshots still inspect all grades.
+    grade_items = [native for native, item in zip(native_items, items)
+                   if grade_media_id is None or item["mediaPoolItemId"] == grade_media_id]
+    grades = grade_evidence(resolve, timeline, grade_items, {i['id'] for i in items if i.get('intrinsicEntry')}) if validated and grade_items and any(i["kind"] == "video" for i in items) else {}
+    entry_scope = scope_for(resolve.GetProjectManager(), resolve.GetProjectManager().GetCurrentProject()) if validated and any(i.get("inspectorEntry") or i.get('intrinsicEntry') for i in items) else None
+    for item in items:
+        item["otioHash"] = evidence["hash"]
+        item["unsupported"] = sorted(set(item["unsupported"] + scoped_reasons.get(item["id"], evidence["reasons"])))
+        if item["id"] in grades:
+            item["gradeHash"] = grades[item["id"]]["hash"]
+            item["unsupported"] = sorted(set(item["unsupported"] + grades[item["id"]]["unsupported"]))
+        entry = item.get('intrinsicEntry') or item.get('inspectorEntry')
+        if entry and entry_scope:
+            owner = entry["identity"]
+            if any(owner[key] != value for key, value in entry_scope.items()):
+                item["unsupported"] = sorted(set(item["unsupported"] + ["inspector-identity-conflict"]))
+    if validated:
+        graph = timeline.GetNodeGraph()
+        if graph and any(graph.GetToolsInNode(index) for index in range(1, graph.GetNumNodes() + 1)):
+            for item in items: item["unsupported"] = sorted(set(item["unsupported"] + ["timeline-grade-unverified"]))
+    return items
+
+
+def publish_playback(path, publication, before_path):
+    """Publish only a validated private copy. History is never overwritten or linked."""
+    source = os.path.realpath(publication["sourcePath"])
+    require(path == os.path.abspath(path) and not os.path.islink(path), "INVALID_ARTIFACT_PATH", "固定视频不能是符号链接。")
+    # artifacts/<version>/<file> -> artifacts/media/<binding>/<same file>
+    root = os.path.dirname(os.path.dirname(source))
+    require(os.path.dirname(os.path.dirname(os.path.dirname(path))) == root
+            and os.path.basename(os.path.dirname(os.path.dirname(path))) == "media"
+            and os.path.basename(os.path.dirname(path)).startswith("binding-")
+            and os.path.basename(source) == os.path.basename(path) and source != path,
+            "INVALID_ARTIFACT_PATH", "固定视频必须位于同一桥接目录的独立关联位置。")
+    require(file_digest(source) == publication["sha256"], "ARTIFACT_CHANGED", "新视频与已验证的历史产物不同。")
+    previous = publication.get("previousSha256")
+    if os.path.exists(path):
+        current = file_digest(path)
+        require(current in (previous, publication["sha256"]), "ARTIFACT_CHANGED", "固定视频已被其他操作改变，未覆盖。")
+        require(os.path.realpath(before_path) == path or current == publication["sha256"], "RECOVERY_CONFLICT", "固定视频已有不同关联，未覆盖。")
+    else:
+        require(not previous or not os.path.exists(before_path), "ARTIFACT_MISSING", "当前固定视频缺失，请通过管理窗口恢复。")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd, pending = tempfile.mkstemp(prefix=".publish-", dir=os.path.dirname(path))
+    try:
+        with os.fdopen(fd, "wb") as out, open(source, "rb") as inp:
+            shutil.copyfileobj(inp, out)
+            out.flush()
+            os.fsync(out.fileno())
+        require(file_digest(pending) == publication["sha256"], "ARTIFACT_CHANGED", "发布副本与已验证产物不同。")
+        os.replace(pending, path)
+        directory = os.open(os.path.dirname(path), os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        if os.path.exists(pending):
+            os.unlink(pending)
+
+
+def media_identity(project, scope, media):
+    """The original media owns the binding, independently of its timeline uses."""
+    try:
+        properties = media.GetClipProperty() or {}
+        metadata = media.GetThirdPartyMetadata() or {}
+    except Exception as error:
+        raise BridgeFailure("CAPABILITY_UNAVAILABLE", "无法读取目标原素材的身份或关联。", diagnostic=str(error))
+    require(isinstance(properties, dict) and isinstance(metadata, dict)
+            and all(isinstance(key, str) and isinstance(value, str) for key, value in metadata.items()),
+            "CAPABILITY_UNAVAILABLE", "无法读取目标素材的身份或关联。")
+    data = {"scope": scope, "projectName": project.GetName(), "mediaPoolItemId": media.GetUniqueId(),
+            "path": properties.get("File Path", ""), "metadata": metadata,
+            "uses": [], "usageScanComplete": False,
+            "clipProperties": {key: properties.get(key) for key in ("FPS", "Frames", "Resolution", "Audio Ch", "Proxy Media Path", "Input Color Space", "Input Gamma", "Data Level", "Alpha mode", "PAR", "Field Dominance", "Clip Name")}}
+    data["fingerprint"] = fingerprint({"scope": scope, "mediaPoolItemId": data["mediaPoolItemId"], "path": data["path"],
+        "bridgeMetadata": metadata.get("motionharness.bridge"),
+        "properties": {key: value for key, value in data["clipProperties"].items() if key != "Clip Name"}})
+    return data
+
+
+def media_snapshot(project, scope, media, resolve=None):
+    data = media_identity(project, scope, media)
+    media_id = media.GetUniqueId()
+    uses = []
+    complete = True
+    for timeline in timelines(project):
+        if not timeline:
+            complete = False
+            continue
+        items = scan_timeline(timeline, resolve, grade_media_id=media_id)
+        uses.extend(i for i in items if i["mediaPoolItemId"] == media_id)
+        # A nested timeline could reference this media indirectly.
+        if any(any(reason in i["unsupported"] for reason in ("nested-or-compound-timeline", "no-plain-media-source", "nested-or-unknown-otio-item", "nested-media-reference", "otio-inspection-unavailable", "otio-item-coverage-mismatch", "host-build-and-frame-conventions-unverified")) for i in items):
+            complete = False
+    settings = project.GetSettings() if resolve and validated_host(resolve) else {}
+    data.update({"uses": uses, "usageScanComplete": complete,
+                 "playbackPolicy": {key: settings.get(key) for key in ("perfProxyMediaMode", "perfOptimisedMediaOn", "perfRenderCacheMode")}})
+    return data
+
+
+def timeline_snapshot(project, scope, timeline, resolve=None):
+    with timeline_context(resolve, timeline):
+        return current_timeline_snapshot(project, scope, timeline, resolve)
+
+
+def current_timeline_snapshot(project, scope, timeline, resolve=None):
+    items = scan_timeline(timeline, resolve)
+    sources = []
+    # Rebuild once per snapshot, not once per source. Do not cache across calls:
+    # imports/replacements and edits by another controller must remain visible.
+    media_index = {}
+    for media in all_media(project.GetMediaPool().GetRootFolder()):
+        media_id = media.GetUniqueId()
+        require(media_id not in media_index, "MEDIA_MISSING", "媒体池稳定身份不唯一。")
+        media_index[media_id] = media
+    for media_id in sorted(set(item["mediaPoolItemId"] for item in items if item["mediaPoolItemId"])):
+        media = media_index.get(media_id)
+        require(media, "MEDIA_MISSING", "指定媒体池对象不存在，未按文件名猜测。")
+        props = media.GetClipProperty() or {}
+        sources.append({"mediaPoolItemId": media_id, "properties": {key: props.get(key) for key in ("File Path", "FPS", "Frames", "Resolution", "Input Color Space", "Input Gamma", "Data Level", "Proxy Media Path")},
+                        "bridgeMetadata": (media.GetThirdPartyMetadata() or {}).get("motionharness.bridge")})
+    settings = project.GetSettings() if resolve and validated_host(resolve) else {}
+    data = {"scope": scope, "timelineId": timeline.GetUniqueId(), "name": timeline.GetName(), "validatedHost": bool(resolve and validated_host(resolve)),
+            "fps": fps_value(timeline.GetSetting("timelineFrameRate")), "startFrame": timeline.GetStartFrame(),
+            "resolution": {"width": int(timeline.GetSetting("timelineResolutionWidth")), "height": int(timeline.GetSetting("timelineResolutionHeight"))},
+            "endFrame": timeline.GetEndFrame(), "items": items, "sources": sources,
+            "videoTracks": [{"index": track, "locked": timeline.GetIsTrackLocked("video", track), "enabled": timeline.GetIsTrackEnabled("video", track)} for track in range(1, timeline.GetTrackCount("video") + 1)],
+            "dropFrame": str(timeline.GetSetting("timelineDropFrameTimecode")) == "1",
+            "audioItems": sum(len(timeline.GetItemListInTrack("audio", track) or []) for track in range(1, timeline.GetTrackCount("audio") + 1)),
+            "missingMedia": [s["mediaPoolItemId"] for s in sources if not os.path.isfile(s["properties"].get("File Path") or "")],
+            "playbackPolicy": {key: settings.get(key) for key in ("perfProxyMediaMode", "perfOptimisedMediaOn", "perfRenderCacheMode")},
+            "projectSettingsHash": fingerprint({key: value for key, value in settings.items() if (key.startswith(("color", "timeline", "node", "isAutoColor", "useColor", "separateColor")) and not key.startswith("colorGallery"))}),
+            "colorPolicy": {"supported": settings.get("colorScienceMode") == "davinciYRGB" and str(settings.get("colorSpaceTimeline", "")).startswith("Rec.709") and str(settings.get("colorSpaceOutput", "")).startswith("Rec.709"),
+                            "science": settings.get("colorScienceMode", ""), "timeline": settings.get("colorSpaceTimeline", ""), "output": settings.get("colorSpaceOutput", "")},
+            "complete": all(not i["unsupported"] for i in items), "unsupported": sorted(set(reason for i in items for reason in i["unsupported"]))}
+    data["fingerprint"] = fingerprint(data)
+    return data
+
+
+def set_metadata(media, metadata):
+    require(media.SetThirdPartyMetadata(metadata), "APPLY_OUTCOME_UNKNOWN", "媒体已可能变更，但第三方关联元数据写入失败。")
+    actual = media.GetThirdPartyMetadata() or {}
+    require(all(actual.get(k) == v for k, v in metadata.items()), "APPLY_OUTCOME_UNKNOWN", "关联元数据读回不一致。")
+
+
+def save_insert_progress(params, before, stage, media=None, item=None):
+    path = params.get("nativeJournal")
+    if not path:
+        return
+    scratch = os.path.realpath(os.environ.get("MH_BRIDGE_SCRATCH", ""))
+    require(scratch and os.path.dirname(os.path.realpath(path)) == scratch and os.path.basename(path).startswith("native-insert-"),
+            "INVALID_REQUEST", "原生插入记录必须位于桥接工作目录。")
+    record = {"schemaVersion": 1, "token": params["nativeToken"], "stage": stage,
+              "scope": params["scope"], "timelineId": params["timelineId"], "metadata": params["metadata"],
+              "originalFingerprint": params["expectedTimelineFingerprint"], "timelineFingerprint": before["fingerprint"],
+              "mediaPoolItemId": media.GetUniqueId() if media else None, "itemId": item.GetUniqueId() if item else None}
+    os.makedirs(scratch, mode=0o700, exist_ok=True)
+    atomic_json(path, record)
+
+
+def frame_timecode(frame, fps, drop_frame=False):
+    require(isinstance(frame, int) and frame >= 0, "INVALID_RANGE", "帧坐标必须是非负整数。")
+    nominal = round(fps["num"] / fps["den"])
+    label = frame
+    if drop_frame:
+        require(fps == {"num": 30000, "den": 1001}, "UNSUPPORTED_FPS", "仅验证了 30000/1001 的 drop-frame 时间码。")
+        tens, remainder = divmod(frame, 17982)
+        label += 18 * tens + 2 * max(0, (remainder - 2) // 1798)
+    hours, rest = divmod(label, nominal * 3600)
+    minutes, rest = divmod(rest, nominal * 60)
+    seconds, frames = divmod(rest, nominal)
+    return "%02d:%02d:%02d%s%02d" % (hours, minutes, seconds, ";" if drop_frame else ":", frames)
+
+
+def require_active_project(resolve, project):
+    active = resolve.GetProjectManager().GetCurrentProject()
+    require(active and active.GetUniqueId() == project.GetUniqueId(), "VERSION_CONFLICT", "操作期间当前 Resolve 工程发生变化。")
+
+
+def await_page(resolve, project, page, timeout=3):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        require_active_project(resolve, project)
+        if resolve.GetCurrentPage() == page:
+            return
+        time.sleep(0.02)
+    raise BridgeFailure("VERSION_CONFLICT", "Resolve 未就绪到明确指定的检查页面。", page=page)
+
+
+def await_timeline(project, timeline, timeout=3.0, resolve=None):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if resolve is not None:
+            require_active_project(resolve, project)
+        active = project.GetCurrentTimeline()
+        if active and active.GetUniqueId() == timeline.GetUniqueId():
+            return
+        time.sleep(0.02)
+    raise BridgeFailure("VERSION_CONFLICT", "Resolve 未就绪到明确指定的时间线。")
+
+
+def seek_timecode(project, timeline, requested, timeout=3.0, resolve=None):
+    deadline = time.monotonic() + timeout
+    last_request, actual = 0.0, None
+    while time.monotonic() < deadline:
+        if resolve is not None:
+            require_active_project(resolve, project)
+        active = project.GetCurrentTimeline()
+        require(active and active.GetUniqueId() == timeline.GetUniqueId(), "VERSION_CONFLICT", "定位期间当前时间线发生变化。")
+        if time.monotonic() - last_request >= 0.25:
+            require(timeline.SetCurrentTimecode(requested), "CAPABILITY_UNAVAILABLE", "无法定位到请求时间码。")
+            last_request = time.monotonic()
+        actual = timeline.GetCurrentTimecode()
+        if actual.replace(";", ":") == requested.replace(";", ":"):
+            return actual
+        time.sleep(0.02)
+    raise BridgeFailure("PREVIEW_READBACK_MISMATCH", "播放头未停在请求帧。", expected=requested, actual=actual)
+
+
+def preview_frame(resolve, project, scope, params, before=None):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该平台与构建的画面捕获尚未验证。")
+    require_active_project(resolve, project)
+    require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出。")
+    timeline = timeline_for(project, params["timelineId"])
+    before = before if before is not None else timeline_snapshot(project, scope, timeline, resolve)
+    require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "截图前时间线已改变。")
+    frame = params["frame"]
+    require(before["startFrame"] <= frame < before["endFrame"], "INVALID_RANGE", "截图帧超出时间线区间。")
+    output = params["outputPath"]
+    require(os.path.isabs(output) and output.lower().endswith(".png") and not os.path.exists(output), "INVALID_REQUEST", "检查图片需要新的绝对 PNG 路径。")
+    previous = project.GetCurrentTimeline()
+    previous_page = resolve.GetCurrentPage()
+    target_timecode = timeline.GetCurrentTimecode()
+    requested_timecode = frame_timecode(frame, before["fps"], before["dropFrame"])
+    current_timecode, restored = None, False
+    try:
+        require(project.SetCurrentTimeline(timeline), "VERSION_CONFLICT", "无法明确设置检查时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        require(resolve.OpenPage("edit"), "CAPABILITY_UNAVAILABLE", "无法明确设置合成截图页面。")
+        await_page(resolve, project, "edit")
+        current_timecode = seek_timecode(project, timeline, requested_timecode, resolve=resolve)
+        require(project.ExportCurrentFrameAsStill(output), "CAPABILITY_UNAVAILABLE", "Resolve 未能捕获当前合成画面。")
+        require_active_project(resolve, project)
+        require(project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId() and timeline.GetCurrentTimecode() == current_timecode,
+                "VERSION_CONFLICT", "捕获期间时间线或播放头已改变。")
+        require(timeline_snapshot(project, scope, timeline, resolve)["fingerprint"] == before["fingerprint"], "VERSION_CONFLICT", "捕获期间时间线内容已改变。")
+    finally:
+        active_project = resolve.GetProjectManager().GetCurrentProject()
+        active = project.GetCurrentTimeline() if active_project and active_project.GetUniqueId() == project.GetUniqueId() else None
+        restore_from = (current_timecode, requested_timecode, target_timecode) if current_timecode is None else (current_timecode,)
+        if active and active.GetUniqueId() == timeline.GetUniqueId() and timeline.GetCurrentTimecode() in restore_from:
+            try:
+                restored = bool(seek_timecode(project, timeline, target_timecode, resolve=resolve))
+                if previous and previous.GetUniqueId() != timeline.GetUniqueId():
+                    restored = bool(project.SetCurrentTimeline(previous)) and restored
+                    await_timeline(project, previous, resolve=resolve)
+                if resolve.GetCurrentPage() == "edit" and previous_page != "edit":
+                    resolve.OpenPage(previous_page)
+                    await_page(resolve, project, previous_page)
+            except BridgeFailure:
+                restored = False
+    return {"origin": "resolve-composite", "timelineId": timeline.GetUniqueId(), "frame": frame,
+            "timecode": requested_timecode, "fingerprint": before["fingerprint"], "uiRestored": restored}
+
+
+def render_job(project, job_id):
+    found = [job for job in project.GetRenderJobList() or [] if job.get("JobId") == job_id]
+    require(len(found) == 1, "RENDER_JOB_MISSING", "指定渲染任务不存在，未启动其他队列项。", jobId=job_id)
+    return found[0]
+
+
+def playback_policy(project):
+    settings = project.GetSettings()
+    return {key: settings.get(key) for key in ORIGINAL_PLAYBACK}
+
+
+def render_preset_evidence(resolve, project):
+    name = "Motion Harness Bridge delivery check " + str(uuid.uuid4())
+    require(project.SaveAsNewRenderPreset(name), "CAPABILITY_UNAVAILABLE", "无法核对导出预设的缓存策略。")
+    try:
+        with tempfile.TemporaryDirectory(prefix="mh-bridge-preset-") as directory:
+            require(resolve.ExportRenderPreset(name, directory), "CAPABILITY_UNAVAILABLE", "无法导出自有临时预设以核对原始画面策略。")
+            root = ET.parse(os.path.join(directory, name + ".xml")).getroot()
+            fields = {key: root.findtext(key) for key in ("UseRenderCachedImagesForRecording", "RecordFormatType", "RecordFormatSubType", "RecordAudioEnabled", "RecordBitDepth")}
+            require(fields == {"UseRenderCachedImagesForRecording": "false", "RecordFormatType": "mp4", "RecordFormatSubType": "avc1", "RecordAudioEnabled": "false", "RecordBitDepth": "8"}, "PLAYBACK_POLICY_UNVERIFIED", "当前导出预设没有通过原始画面和格式核对。", actual=fields)
+            return fields
+    finally:
+        project.DeleteRenderPreset(name)
+
+
+def create_render(resolve, project, scope, params):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证指定任务导出。")
+    require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 已有输出任务在运行。")
+    timeline = timeline_for(project, params["timelineId"])
+    expected = params["expectedTimelineFingerprint"]
+    require(timeline_snapshot(project, scope, timeline, resolve)["fingerprint"] == expected, "VERSION_CONFLICT", "创建输出任务前时间线已改变。")
+    output, bounds = params["output"], params["range"]
+    path = output["filePath"]
+    require(os.path.isabs(path) and path.lower().endswith(".mp4") and not os.path.exists(path), "TARGET_OCCUPIED", "输出需要新的绝对 MP4 路径。")
+    previous = project.GetCurrentTimeline()
+    before_jobs = project.GetRenderJobList() or []
+    require(not any(os.path.realpath(job.get("TargetDir", "")) == os.path.realpath(os.path.dirname(path)) and job.get("OutputFilename") == os.path.basename(path) for job in before_jobs), "TARGET_OCCUPIED", "输出位置已被其他队列项占用。")
+    backup = "Motion Harness Bridge restore " + str(uuid.uuid4())
+    require(project.SaveAsNewRenderPreset(backup), "CAPABILITY_UNAVAILABLE", "无法保存原有导出配置，未修改设置。")
+    job_id = None
+    try:
+        require(project.SetCurrentTimeline(timeline), "VERSION_CONFLICT", "无法设置明确的输出时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        require(resolve.OpenPage("deliver"), "CAPABILITY_UNAVAILABLE", "无法明确设置输出页面。")
+        await_page(resolve, project, "deliver")
+        require(project.LoadRenderPreset("H.264 Master"), "CAPABILITY_UNAVAILABLE", "缺少经过验证的 H.264 Master 导出预设。")
+        require(project.SetCurrentRenderFormatAndCodec("mp4", "H264") and project.SetCurrentRenderMode(1), "CAPABILITY_UNAVAILABLE", "MP4/H.264 单文件输出不可用。")
+        # 21.1.0.14 rejects SelectAllFrames=False and string VideoQuality despite its declarations.
+        # Explicit marks select the range; the resulting job is checked before it can start.
+        settings = {"MarkIn": bounds["startFrame"], "MarkOut": bounds["endFrame"] - 1,
+                    "TargetDir": os.path.dirname(path), "CustomName": os.path.splitext(os.path.basename(path))[0],
+                    "UseUniqueFilenames": False, "ExportVideo": True, "ExportAudio": False,
+                    "FormatWidth": output["width"], "FormatHeight": output["height"], "FrameRate": output["fps"]["num"] / output["fps"]["den"],
+                    "PixelAspectRatio": "square", "VideoQuality": 0 if output["quality"] == "Best" else max(2400, int(output["width"] * output["height"] * output["fps"]["num"] / output["fps"]["den"] * 0.15 / 1000)),
+                    "ColorSpaceTag": "Rec.709", "GammaTag": "Gamma 2.4",
+                    "ExportSubtitle": False, "DataBurnIn": "None"}
+        require(project.SetRenderSettings(settings), "CAPABILITY_UNAVAILABLE", "Resolve 拒绝明确的输出设置。")
+        preset_evidence = render_preset_evidence(resolve, project)
+        require_active_project(resolve, project)
+        require(timeline_snapshot(project, scope, timeline, resolve)["fingerprint"] == expected, "VERSION_CONFLICT", "配置输出期间时间线已改变。")
+        job_id = project.AddRenderJob()
+        require(job_id, "APPLY_OUTCOME_UNKNOWN", "Resolve 未返回创建的任务 ID；必须按输出路径核对后恢复。")
+        job = render_job(project, job_id)
+        require(job.get("IsExportVideo") is True and job.get("IsExportAudio") is False and job.get("FormatWidth") == output["width"] and job.get("FormatHeight") == output["height"]
+                and int(job.get("MarkIn", -1)) == bounds["startFrame"] and int(job.get("MarkOut", -1)) == bounds["endFrame"] - 1
+                and os.path.realpath(job.get("TargetDir", "")) == os.path.realpath(os.path.dirname(path))
+                and job.get("OutputFilename") == os.path.basename(path) and job.get("ExportAlpha") is False
+                and fps_value(job.get("FrameRate")) == output["fps"] and job.get("VideoFormat") == "MP4" and job.get("VideoCodec") == "H.264" and job.get("RenderMode") == "Single clip",
+                "APPLY_OUTCOME_UNKNOWN", "已创建任务的输出设置与请求不一致，未开始输出。", job=job)
+        old = {job["JobId"]: job for job in before_jobs}
+        after = {job["JobId"]: job for job in project.GetRenderJobList() or []}
+        require(all(after.get(key) == value for key, value in old.items()), "APPLY_OUTCOME_UNKNOWN", "创建期间已有队列项发生变化，停止启动。")
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if active and active.GetUniqueId() == project.GetUniqueId():
+            restored = project.LoadRenderPreset(backup)
+            if restored:
+                project.DeleteRenderPreset(backup)
+            if previous and project.GetCurrentTimeline().GetUniqueId() == timeline.GetUniqueId():
+                project.SetCurrentTimeline(previous)
+                await_timeline(project, previous, resolve=resolve)
+    return {"jobId": job_id, "job": job, "jobFingerprint": fingerprint(job), "presetEvidence": preset_evidence}
+
+
+def start_render(resolve, project, scope, params):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证指定任务导出。")
+    require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在执行其他渲染；未启动队列。")
+    job = render_job(project, params["jobId"])
+    require(params.get("expectedJobFingerprint") and fingerprint(job) == params["expectedJobFingerprint"], "VERSION_CONFLICT", "队列任务的输出设置已改变或没有核对记录，未启动。")
+    require(project.GetRenderJobStatus(params["jobId"]).get("JobStatus") == "Ready", "VERSION_CONFLICT", "目标任务已不处于待开始状态。")
+    timeline = timeline_for(project, params["timelineId"])
+    require(project.SetCurrentTimeline(timeline), "VERSION_CONFLICT", "无法明确设置指定输出任务的时间线。")
+    await_timeline(project, timeline, resolve=resolve)
+    require(resolve.OpenPage("deliver"), "CAPABILITY_UNAVAILABLE", "无法明确设置指定任务的输出上下文。")
+    await_page(resolve, project, "deliver")
+    before = timeline_snapshot(project, scope, timeline, resolve)
+    require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "启动前时间线已改变，拒绝旧回执。")
+    previous = playback_policy(project)
+    try:
+        require(project.SetSettings(ORIGINAL_PLAYBACK) and playback_policy(project) == ORIGINAL_PLAYBACK, "PLAYBACK_POLICY_UNVERIFIED", "未能明确关闭代理、优化媒体和渲染缓存；未开始输出。")
+        after = timeline_snapshot(project, scope, timeline, resolve)
+        semantic = lambda data: {key: value for key, value in data.items() if key not in ("fingerprint", "playbackPolicy")}
+        require(semantic(before) == semantic(after), "VERSION_CONFLICT", "准备原始画面期间目标内容已改变，未开始输出。")
+        require(project.StartRendering([params["jobId"]], False), "APPLY_OUTCOME_UNKNOWN", "Resolve 未确认启动指定任务，必须查询该 ID；不能重启整个队列。")
+    except Exception:
+        if not project.IsRenderingInProgress() and playback_policy(project) == ORIGINAL_PLAYBACK:
+            project.SetSettings(previous)
+        raise
+    return {"jobId": params["jobId"], "job": job, "previousPolicy": previous, "deliveryPolicy": "originals"}
+
+
+def finish_render(resolve, project, params):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证输出恢复。")
+    render_job(project, params["jobId"])
+    require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "仍有渲染运行，保留原始画面模式直至可核对的终态。")
+    expected, actual = params["playbackPolicy"], playback_policy(project)
+    require(set(expected) == set(ORIGINAL_PLAYBACK), "RECOVERY_EVIDENCE_MISSING", "缺少本任务开始前的播放设置。")
+    if actual != expected:
+        require(actual == ORIGINAL_PLAYBACK, "VERSION_CONFLICT", "播放设置已被其他控制端修改，未覆盖其新设置。", actual=actual, original=expected)
+        require(project.SetSettings(expected) and playback_policy(project) == expected, "APPLY_OUTCOME_UNKNOWN", "输出已经结束，但原播放设置尚未恢复。")
+    return {"jobId": params["jobId"], "playbackPolicy": playback_policy(project), "restored": True}
+
+
+def export_references(resolve, project, scope, params):
+    require(validated_host(resolve) and not project.IsRenderingInProgress(), "RESOLVE_BUSY", "输出后画面核对需要已完成渲染的目标工程。")
+    timeline = timeline_for(project, params["timelineId"])
+    before = timeline_snapshot(project, scope, timeline, resolve)
+    require(before["fingerprint"] == params["expectedTimelineFingerprint"], "VERSION_CONFLICT", "输出后的时间线已改变，不能生成原回执的参考画面。")
+    directory = params["outputDirectory"]
+    require(os.path.isabs(directory) and os.path.isdir(directory), "INVALID_REQUEST", "检查参考图片需要明确的输出目录。")
+    original = playback_policy(project)
+    frames = []
+    try:
+        require(project.SetSettings(ORIGINAL_PLAYBACK) and playback_policy(project) == ORIGINAL_PLAYBACK, "PLAYBACK_POLICY_UNVERIFIED", "无法使用原始媒体核对输出。")
+        current = timeline_snapshot(project, scope, timeline, resolve)
+        semantic = lambda data: {key: value for key, value in data.items() if key not in ("fingerprint", "playbackPolicy")}
+        require(semantic(before) == semantic(current), "VERSION_CONFLICT", "设置原始画面策略期间时间线已改变。")
+        count = params["range"]["endFrame"] - params["range"]["startFrame"]
+        for index in sorted(set((0, count // 2, count - 1))):
+            frame = params["range"]["startFrame"] + index
+            path = os.path.join(directory, "%09d.png" % index)
+            preview_frame(resolve, project, scope, {"timelineId": params["timelineId"], "frame": frame, "expectedFingerprint": current["fingerprint"], "outputPath": path})
+            frames.append({"frame": frame, "index": index, "filePath": path})
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if active and active.GetUniqueId() == project.GetUniqueId() and playback_policy(project) == ORIGINAL_PLAYBACK:
+            require(project.SetSettings(original) and playback_policy(project) == original, "APPLY_OUTCOME_UNKNOWN", "参考图片已生成，但原始播放设置未恢复。")
+    return {"frames": frames, "origin": "resolve-composite-original-media", "timelineFingerprint": before["fingerprint"]}
+
+
+def preview_original(resolve, project, scope, params):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证原始媒体合成检查。")
+    require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "不能在导出期间改变合成画面检查策略。")
+    timeline = timeline_for(project, params["timelineId"])
+    before = timeline_snapshot(project, scope, timeline, resolve)
+    require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "原始合成画面检查前时间线已改变。")
+    original = playback_policy(project)
+    try:
+        require(project.SetSettings(ORIGINAL_PLAYBACK) and playback_policy(project) == ORIGINAL_PLAYBACK, "PLAYBACK_POLICY_UNVERIFIED", "无法确定原始媒体检查策略。")
+        current = timeline_snapshot(project, scope, timeline, resolve)
+        semantic = lambda data: {key: value for key, value in data.items() if key not in ("fingerprint", "playbackPolicy")}
+        require(semantic(before) == semantic(current), "VERSION_CONFLICT", "检查策略切换期间时间线已改变。")
+        result = preview_frame(resolve, project, scope, {**params, "expectedFingerprint": current["fingerprint"]}, before=current)
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        if active and active.GetUniqueId() == project.GetUniqueId():
+            require(playback_policy(project) == ORIGINAL_PLAYBACK, "VERSION_CONFLICT", "检查期间播放策略被另一控制端修改，未覆盖新设置。")
+            require(project.SetSettings(original) and playback_policy(project) == original, "APPLY_OUTCOME_UNKNOWN", "检查完成，但播放设置未恢复。")
+    require(timeline_snapshot(project, scope, timeline, resolve)["fingerprint"] == before["fingerprint"], "VERSION_CONFLICT", "原始合成截图后的时间线已改变。")
+    return {**result, "fingerprint": before["fingerprint"], "captureFingerprint": current["fingerprint"], "mediaPolicy": "originals", "playbackPolicyRestored": True}
+
+
+def selection_snapshot(resolve, plain_media_only=False):
+    require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证时间线选择读取。")
+
+    def plain_item(item):
+        media = item.GetMediaPoolItem()
+        require(media is not None and media is not False, "CAPABILITY_UNAVAILABLE", "请选择有直接视频源的普通片段；生成器入口暂不支持此操作。")
+        require(not media.GetTimeline(), "CAPABILITY_UNAVAILABLE", "复合片段或嵌套时间线暂不支持此入口，请选择普通视频片段。")
+        properties = media.GetClipProperty()
+        require(isinstance(properties, dict), "CAPABILITY_UNAVAILABLE", "无法读取所选片段的素材路径。")
+        path = properties.get("File Path")
+        require(isinstance(path, str) and bool(path.strip()) and "\0" not in path and os.path.isabs(path),
+                "CAPABILITY_UNAVAILABLE", "所选片段没有可验证的普通视频文件路径。")
+        metadata = media.GetThirdPartyMetadata()
+        require(isinstance(metadata, dict), "CAPABILITY_UNAVAILABLE", "无法读取所选片段的关联元数据。")
+        identity = media.GetUniqueId()
+        require(isinstance(identity, str) and bool(identity.strip()) and "\0" not in identity,
+                "CAPABILITY_UNAVAILABLE", "无法读取所选片段的素材身份。")
+        bridge_metadata = metadata.get("motionharness.bridge")
+        return {"id": item.GetUniqueId(), "name": item.GetName(), "mediaPoolItemId": identity,
+                "bridgeMetadata": bridge_metadata if isinstance(bridge_metadata, str) else None,
+                "path": os.path.realpath(path)}
+
+    def selected_clips(timeline):
+        selected = timeline.GetSelectedClips()
+        if plain_media_only:
+            require(isinstance(selected, list), "CAPABILITY_UNAVAILABLE", "无法完整读取时间线选择。")
+        return selected or []
+
+    project = resolve.GetProjectManager().GetCurrentProject()
+    data = {"scope": None, "timelineId": None, "selectedCount": 0, "item": None}
+    if project:
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "导出期间暂不读取时间线选择。")
+        project, scope = project_for(resolve)
+        data["scope"] = scope
+        timeline = project.GetCurrentTimeline()
+        if timeline:
+            raw_selected = selected_clips(timeline)
+            identities = sorted(item.GetUniqueId() for item in raw_selected)
+            selected = [item for item in raw_selected if item.GetType() == 'video']
+            data.update(timelineId=timeline.GetUniqueId(), selectedCount=len(selected))
+            if len(selected) == 1:
+                item = selected[0]
+                if plain_media_only:
+                    data["item"] = plain_item(item)
+                else:
+                    media = item.GetMediaPoolItem()
+                    if not media:
+                        index = {m.GetUniqueId(): m for m in all_media(project.GetMediaPool().GetRootFolder())}
+                        entry = intrinsic.read_entry(item, index)
+                        if entry and all(entry['identity'][key] == value for key, value in scope.items()):
+                            media = index[entry['identity']['mediaPoolItemId']]
+                    metadata = (media.GetThirdPartyMetadata() or {}).get("motionharness.bridge") if media else None
+                    data["item"] = {"id": item.GetUniqueId(), "name": item.GetName(),
+                                    "mediaPoolItemId": media.GetUniqueId() if media else None,
+                                    "bridgeMetadata": metadata if isinstance(metadata, str) else None}
+            require_active_project(resolve, project)
+            active = project.GetCurrentTimeline()
+            require(active and active.GetUniqueId() == data["timelineId"],
+                    "VERSION_CONFLICT", "读取期间所选时间线已改变。")
+            after_selected = selected_clips(active)
+            require(sorted(item.GetUniqueId() for item in after_selected) == identities,
+                    "VERSION_CONFLICT", "读取期间所选片段已改变。")
+            if plain_media_only:
+                after_video = [item for item in after_selected if item.GetType() == 'video']
+                require(len(after_video) == data["selectedCount"], "VERSION_CONFLICT", "读取期间所选片段类型已改变。")
+                if len(after_video) == 1:
+                    require(plain_item(after_video[0]) == data["item"], "VERSION_CONFLICT", "读取期间所选片段的素材身份或路径已改变。")
+        if plain_media_only:
+            if not timeline:
+                require(not project.GetCurrentTimeline(), "VERSION_CONFLICT", "读取期间当前时间线已改变。")
+            project_for(resolve, scope)
+    elif plain_media_only:
+        require(not resolve.GetProjectManager().GetCurrentProject(), "VERSION_CONFLICT", "读取期间当前工程已改变。")
+    data["fingerprint"] = fingerprint(data)
+    return data
+
+
+def entry_target(resolve, project, scope, params):
+    """Resolve one captured menu target without selecting pages or scanning edits."""
+    selection = params.get("selection") or {}
+    require(scope == selection.get("scope"), "VERSION_CONFLICT", "所点击片段的工程已改变。")
+    source = None
+    if selection.get("path"):
+        source = ofx_source_target(resolve, {"scope": scope, "mediaPoolItemId": selection.get("mediaPoolItemId"), "path": selection["path"]})
+    if not selection.get("timelineId") and not selection.get("itemId"):
+        require(source is not None, "INVALID_REQUEST", "素材级入口需要源视频路径。")
+        return {**source, "name": source["clipProperties"].get("Clip Name") or ""}
+    timeline = timeline_for(project, selection.get("timelineId"))
+    found = [item for track in range(1, timeline.GetTrackCount("video") + 1)
+             for item in timeline.GetItemListInTrack("video", track) or []
+             if item.GetUniqueId() == selection.get("itemId")]
+    require(len(found) == 1, "VERSION_CONFLICT", "所点击片段已不存在，未使用后来的选择。")
+    item = found[0]
+    media = item.GetMediaPoolItem()
+    if not media:
+        candidate = media_for(project, selection.get("mediaPoolItemId"))
+        entry = intrinsic.read_entry(item, {candidate.GetUniqueId(): candidate})
+        require(entry and all(entry["identity"].get(key) == value for key, value in scope.items()),
+                "VERSION_CONFLICT", "该片段不再指向原关联媒体。")
+        media = candidate
+    require(media.GetUniqueId() == selection.get("mediaPoolItemId"), "VERSION_CONFLICT", "所点击片段的原生媒体身份已改变。")
+    path, values = media.GetClipProperty("File Path"), media.GetThirdPartyMetadata() or {}
+    result = {"scope": scope, "timelineId": timeline.GetUniqueId(), "itemId": item.GetUniqueId(),
+              "projectName": project.GetName(), "timelineName": timeline.GetName(),
+              "mediaPoolItemId": media.GetUniqueId(), "name": item.GetName(), "metadata": values, "path": path}
+    require_active_project(resolve, project)
+    require((media.GetThirdPartyMetadata() or {}) == values and media.GetClipProperty("File Path") == path,
+            "VERSION_CONFLICT", "读取管理入口期间素材身份或文件发生变化。")
+    return result
+
+
+def inspector_operation(resolve, params):
+    require(params.get("experimental") is True, "CAPABILITY_UNAVAILABLE", "检查器入口尚待实机验收，仅开放明确的隔离实验操作。")
+    # A composition imported through the API is not an Edit-page Fusion effect.
+    # Keep the graph experiment separate from the product's Inspector entry.
+    require(params.get("remove") or params.get("compositionOnly") is True, "CAPABILITY_UNAVAILABLE",
+            "ImportFusionComp 不能创建 Edit 检查器效果，请通过原生特效库应用 Motion Harness Bridge 模板。")
+    identity = params["identity"]
+    require(identity.get("schemaVersion") == 1, "INVALID_REQUEST", "检查器入口身份版本无效。")
+    selected = selection_snapshot(resolve)
+    require(selected["fingerprint"] == params["expectedSelectionFingerprint"] and selected["selectedCount"] == 1,
+            "VERSION_CONFLICT", "挂载前所选片段已改变。")
+    require(selected["timelineId"] == params["timelineId"] and selected["item"]["id"] == params["itemId"]
+            and selected["item"]["mediaPoolItemId"] == identity["mediaPoolItemId"], "VERSION_CONFLICT", "目标片段与入口身份不一致。")
+    project, scope = project_for(resolve, {"databaseId": identity["databaseId"], "projectId": identity["projectId"]})
+    timeline = project.GetCurrentTimeline()
+    item = (timeline.GetSelectedClips() or [None])[0]
+    link = json.loads(selected["item"]["bridgeMetadata"] or "null")
+    require(isinstance(link, dict) and link.get("sourceId") == identity["sourceId"] and link.get("bindingId") == identity["bindingId"],
+            "VERSION_CONFLICT", "媒体的桥接身份已改变。")
+    owned = inspector.read_entry(item)
+    if owned:
+        require(owned["identity"] == identity, "VERSION_CONFLICT", "已有入口属于其他桥接工作目录。")
+    if params.get("remove"):
+        require(owned, "TARGET_OCCUPIED", "未找到完整且未改动的自有入口，未删除用户合成。")
+        tracks = [track for track in range(1, timeline.GetTrackCount("video") + 1)
+                  if any(clip.GetUniqueId() == item.GetUniqueId() for clip in (timeline.GetItemListInTrack("video", track) or []))]
+        require(len(tracks) == 1 and not timeline.GetIsTrackLocked("video", tracks[0]), "TARGET_LOCKED", "入口所在轨道已锁定或无法明确定位，未移除。")
+        names = item.GetFusionCompNameList() or []
+        require(len(names) == 1, "VERSION_CONFLICT", "Fusion 合成列表已改变。")
+        require(selection_snapshot(resolve)["fingerprint"] == selected["fingerprint"], "VERSION_CONFLICT", "移除前所选片段已改变。")
+        require(item.DeleteFusionCompByName(names[0]), "APPLY_OUTCOME_UNKNOWN", "移除入口的宿主结果不明，请先检查片段。")
+        require(item.GetFusionCompCount() == 0, "APPLY_OUTCOME_UNKNOWN", "移除后的合成数量未能核实。")
+        require_active_project(resolve, project)
+        return {"removed": True, "itemId": item.GetUniqueId(), "identity": identity}
+    if owned:
+        return {"attached": True, "reused": True, "itemId": item.GetUniqueId(), "entry": owned, "nativeValidation": "pending"}
+    require(item.GetFusionCompCount() == 0, "TARGET_OCCUPIED", "片段已有 Fusion 合成，未覆盖。")
+    before = timeline_snapshot(project, scope, timeline, resolve)
+    targets = [value for value in before["items"] if value["id"] == item.GetUniqueId()]
+    require(len(targets) == 1 and not targets[0]["unsupported"] and not targets[0].get("trackLocked"),
+            "UNSUPPORTED_TIMELINE_ITEM", "实验入口只接受完整读回通过、未锁定的普通 Motion Harness 片段。")
+    with open(params["compositionPath"], "rb") as stream:
+        data = stream.read()
+    require(hashlib.sha256(data).hexdigest() == params["compositionSha256"] and data.startswith(b"-- MH Resolve Bridge inspector v1\n"),
+            "VERSION_CONFLICT", "待挂载入口文件已改变。")
+    require(selection_snapshot(resolve)["fingerprint"] == selected["fingerprint"], "VERSION_CONFLICT", "导入前所选片段已改变。")
+    # From this point a native object may exist even when readback fails. Never
+    # blindly import again or roll back another controller's composition.
+    try:
+        comp = item.ImportFusionComp(params["compositionPath"])
+        require(comp and item.GetFusionCompCount() == 1, "APPLY_OUTCOME_UNKNOWN", "入口导入结果不明。")
+        macro, media_in, media_out = (comp.FindTool(name) for name in ("MHBridge", "MediaIn1", "MediaOut1"))
+        require(macro and media_in and media_out, "APPLY_OUTCOME_UNKNOWN", "入口图结构未能读回。")
+        media_in.SetInput("MediaID", item.GetMediaPoolItem().GetMediaId(), 0)
+        require(macro.ConnectInput("MainInput1", media_in.FindMainOutput(1)) and media_out.ConnectInput("Input", macro.FindMainOutput(1)),
+                "APPLY_OUTCOME_UNKNOWN", "入口图像连接未能核实。")
+        receipt = {"schemaVersion": 1, "identity": identity, "graphFingerprint": inspector.graph(comp, identity), "nativeValidation": "pending"}
+        evidence = otio_evidence(resolve, timeline)
+        rate = before["fps"]["num"] / before["fps"]["den"]
+        target = targets[0]
+        details = evidence["tracks"][target["track"] - 1]
+        matches = []
+        for clip in details["clips"]:
+            if clip["startSeconds"] is None or clip["durationSeconds"] is None: continue
+            parsed = urlparse(clip.get("path") or "")
+            path = unquote(parsed.path) if parsed.scheme == "file" and parsed.netloc in ("", "localhost") else clip.get("path")
+            if (abs(clip["startSeconds"] * rate - (target["startFrame"] - before["startFrame"])) < 0.01
+                    and abs(clip["durationSeconds"] * rate - (target["endFrame"] - target["startFrame"])) < 0.01
+                    and path and os.path.realpath(path) == os.path.realpath(item.GetMediaPoolItem().GetClipProperty("File Path"))):
+                matches.append(clip)
+        require(len(matches) == 1, "APPLY_OUTCOME_UNKNOWN", "无法将入口的 OTIO 效果对应到明确片段。")
+        receipt["otioEffectsFingerprint"] = inspector.signature(inspector.unknown_effects(matches[0].get("effects", []), SUPPORTED_INSPECTOR_EFFECTS))
+        comp.SetData(inspector.DATA_KEY, receipt)
+        require(inspector.read_entry(item) == receipt, "APPLY_OUTCOME_UNKNOWN", "入口身份和图结构未能完整核实。")
+        require_active_project(resolve, project)
+        return {"attached": True, "reused": False, "itemId": item.GetUniqueId(), "entry": receipt, "nativeValidation": "pending"}
+    except Exception as error:
+        raise BridgeFailure("APPLY_OUTCOME_UNKNOWN", "检查器挂载可能已部分完成，请先检查目标片段，不要直接重放导入。", diagnostic=str(error), itemId=item.GetUniqueId())
+
+
+def dispatch(resolve, operation, params):
+    if operation == "ofx_source_target":
+        return ofx_source_target(resolve, params)
+    if operation == "selection":
+        return selection_snapshot(resolve, plain_media_only=params.get("plainMediaOnly") is True)
+    if operation == "inspector":
+        return inspector_operation(resolve, params)
+    if operation in ("connection", "target"):
+        manager = resolve.GetProjectManager()
+        project = manager.GetCurrentProject()
+        timeline = project.GetCurrentTimeline() if project else None
+        if operation == "connection":
+            return {"connected": True, "version": resolve.GetVersionString(), "scope": scope_for(manager, project) if project else None,
+                    "timelineId": timeline.GetUniqueId() if timeline else None, "projectName": project.GetName() if project else None}
+        require(project and timeline, "TIMELINE_MISSING", "请打开一个达芬奇工程和时间线。")
+        rate = fps_value(timeline.GetSetting("timelineFrameRate"))
+        code = timeline.GetCurrentTimecode()
+        drop = ";" in code or str(timeline.GetSetting("timelineDropFrameTimecode")) == "1"
+        pieces = code.replace(";", ":").split(":")
+        require(len(pieces) == 4 and all(value.isdigit() for value in pieces), "INVALID_RANGE", "无法读取当前播放头时间码。")
+        hours, minutes, seconds, frames = map(int, pieces)
+        nominal = round(rate["num"] / rate["den"])
+        frame = (hours * 3600 + minutes * 60 + seconds) * nominal + frames
+        if drop:
+            require(nominal == 30, "UNSUPPORTED_FPS", "当前丢帧时间码尚不支持。")
+            total_minutes = hours * 60 + minutes
+            frame -= 2 * (total_minutes - total_minutes // 10)
+        return {"scope": scope_for(manager, project), "timelineId": timeline.GetUniqueId(), "recordFrame": frame, "timecode": code}
+    if operation == "discover":
+        manager = resolve.GetProjectManager()
+        project = manager.GetCurrentProject()
+        return {"product": resolve.GetProductName(), "version": resolve.GetVersionString(),
+                "scope": scope_for(manager, project) if project else None,
+                "timelines": [{"id": t.GetUniqueId(), "name": t.GetName()} for t in timelines(project)] if project else [],
+                "adapter": "documented-python-scripting", "officialMcp": "not-tested-by-scripting",
+                "replacement": "stable-playback-file-with-media-identity" if validated_host(resolve) else "host-build-unverified",
+                "frameConvention": "half-open" if validated_host(resolve) else "unverified",
+                "profile": {"platform": sys.platform, "architecture": platform.machine(), "basicBridgeValidated": validated_host(resolve)},
+                "timelineReadback": "top-level-video; native speed/properties/fades and conservative OTIO structure check"}
+    proof = params if operation in ("render_status", "cancel_render") else None
+    project, scope = project_for(resolve, params.get("scope"), proof)
+    if operation == "entry_target":
+        require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证所选片段管理。")
+        return entry_target(resolve, project, scope, params)
+    if operation in ("legacy_preview", "legacy_convert", "legacy_check"):
+        require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证旧生成器结构转换。")
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出。")
+        action = {"legacy_preview": legacy.preview, "legacy_convert": legacy.convert, "legacy_check": legacy.check}[operation]
+        return action(resolve, project, scope, params, globals())
+    if operation == "duplicate_instance":
+        require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证单实例独立副本。")
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出。")
+        return instances.duplicate_instance(resolve, project, scope, params, globals())
+    if operation == "timeline":
+        return timeline_snapshot(project, scope, timeline_for(project, params["timelineId"]), resolve)
+    if operation == "find_import":
+        path = os.path.realpath(params["filePath"])
+        found = [media for media in all_media(project.GetMediaPool().GetRootFolder()) if os.path.realpath(media.GetClipProperty("File Path") or "") == path]
+        require(len(found) <= 1, "RECOVERY_CONFLICT", "多个素材池对象指向待恢复的产物，未按名称猜测。")
+        return media_snapshot(project, scope, found[0], resolve) if found else None
+    if operation == "preview":
+        return preview_original(resolve, project, scope, params) if params.get("mediaPolicy") == "originals" else preview_frame(resolve, project, scope, params)
+    if operation == "create_render":
+        return create_render(resolve, project, scope, params)
+    if operation == "start_render":
+        return start_render(resolve, project, scope, params)
+    if operation == "finish_render":
+        return finish_render(resolve, project, params)
+    if operation == "export_references":
+        return export_references(resolve, project, scope, params)
+    if operation == "find_render":
+        path = os.path.realpath(params["filePath"])
+        jobs = [job for job in project.GetRenderJobList() or [] if os.path.realpath(os.path.join(job.get("TargetDir", ""), job.get("OutputFilename", ""))) == path]
+        require(len(jobs) <= 1, "RECOVERY_CONFLICT", "多个队列项指向同一输出路径，未按名称猜测。")
+        expected = params.get("expected")
+        if jobs and expected:
+            job, output, bounds = jobs[0], expected["output"], expected["range"]
+            timeline = timeline_for(project, expected["timelineId"])
+            require(sum(t.GetName() == timeline.GetName() for t in timelines(project)) == 1, "RECOVERY_CONFLICT", "队列接口缺少稳定时间线 ID，存在同名时间线时不能据队列显示名称恢复。")
+            require(job.get("TimelineName") == timeline.GetName() and job.get("FormatWidth") == output["width"] and job.get("FormatHeight") == output["height"] and fps_value(job.get("FrameRate")) == output["fps"]
+                    and job.get("MarkIn") == bounds["startFrame"] and job.get("MarkOut") == bounds["endFrame"] - 1 and job.get("VideoCodec") == "H.264" and job.get("IsExportAudio") is False and job.get("ExportAlpha") is False,
+                    "RECOVERY_CONFLICT", "中断队列项的时间线、区间或格式与原请求不一致。")
+        return {"jobId": jobs[0]["JobId"], "status": project.GetRenderJobStatus(jobs[0]["JobId"]), "jobFingerprint": fingerprint(jobs[0])} if jobs else None
+    if operation == "find_binding":
+        found = []
+        for media in all_media(project.GetMediaPool().GetRootFolder()):
+            try:
+                link = json.loads((media.GetThirdPartyMetadata() or {}).get("motionharness.bridge", "{}"))
+                if link.get("bindingId") == params["bindingId"]:
+                    found.append(media)
+            except (ValueError, TypeError):
+                pass
+        require(len(found) <= 1, "RECOVERY_CONFLICT", "多个媒体对象拥有同一绑定身份，未自动选择。")
+        return media_snapshot(project, scope, found[0], resolve) if found else None
+    if operation in ("render_status", "cancel_render"):
+        if operation == "cancel_render":
+            require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该构建尚未验证指定任务取消。")
+        render_job(project, params["jobId"])
+        status = project.GetRenderJobStatus(params["jobId"])
+        if operation == "cancel_render" and status.get("JobStatus") == "Rendering":
+            running = [job["JobId"] for job in project.GetRenderJobList() or [] if project.GetRenderJobStatus(job["JobId"]).get("JobStatus") == "Rendering"]
+            require(running == [params["jobId"]], "RESOLVE_BUSY", "有其他任务正在运行，未调用全局 StopRendering。", running=running)
+            project.StopRendering()
+            status = project.GetRenderJobStatus(params["jobId"])
+        return status
+    if operation == "media_identity":
+        media = media_for(project, params["mediaPoolItemId"])
+        result = media_identity(project, scope, media)
+        require_active_project(resolve, project)
+        return result
+    if operation in ("media", "bind", "replace"):
+        media = media_for(project, params["mediaPoolItemId"])
+        if operation == "media":
+            return media_snapshot(project, scope, media, resolve)
+        before = media_identity(project, scope, media)
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出，桥接没有修改媒体。")
+        require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证自动修改的帧边界。")
+        require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "Resolve 原素材的身份、关联或媒体规格已变化。")
+        if operation == "replace":
+            repair = params.get("offlineRepair")
+            path = os.path.realpath(params["filePath"])
+            publication = params.get("publication")
+            require(publication or os.path.isfile(path), "ARTIFACT_MISSING", "新产物不存在。")
+            if repair:
+                require(not os.path.exists(before["path"]) and os.path.realpath(before["path"]) == os.path.realpath(repair["previousPath"])
+                        and before["metadata"].get("motionharness.bridge") == params["metadata"].get("motionharness.bridge"),
+                        "RECOVERY_CONFLICT", "离线搬迁修复只允许原绑定、原产物身份和已记录的旧路径。")
+                require(file_digest(publication["sourcePath"] if publication else path) == repair["sha256"],
+                        "ARTIFACT_CHANGED", "搬迁媒体与记录摘要不同。")
+            require(not before["clipProperties"].get("Proxy Media Path"), "PROXY_UNSUPPORTED", "当前替换路径尚未验证已关联代理。")
+            require(os.path.basename(path) == os.path.basename(before["path"]), "BASENAME_CONFLICT", "安全重连要求版本目录中的文件名保持一致；未修改现有素材。")
+            if publication:
+                require_active_project(resolve, project)
+                require(media_identity(project, scope, media)["fingerprint"] == before["fingerprint"],
+                        "VERSION_CONFLICT", "发布前原素材的身份或关联已改变。")
+                # Require the still-current metadata; no selection or effect-stored ID is consulted.
+                old_link = json.loads(before["metadata"].get("motionharness.bridge") or "{}")
+                new_link = json.loads(params["metadata"].get("motionharness.bridge") or "{}")
+                require(not old_link or all(old_link.get(k) == new_link.get(k) for k in ("schemaVersion", "bindingId", "sourceId")),
+                        "BINDING_CONFLICT", "素材的关联身份已经改变。")
+                publish_playback(path, publication, before["path"])
+            require_active_project(resolve, project)
+            require(media_identity(project, scope, media)["fingerprint"] == before["fingerprint"],
+                    "APPLY_OUTCOME_UNKNOWN" if publication else "VERSION_CONFLICT", "重连前原素材的身份或关联已改变。")
+            require(project.GetMediaPool().RelinkClips([media], os.path.dirname(path)), "APPLY_OUTCOME_UNKNOWN", "Resolve 未确认重连版本目录，需读回核对后处理。")
+            # Clip interpretation belongs to the existing cut. Relinking may
+            # re-read container defaults; preserve the user's native settings.
+            current_properties = media.GetClipProperty() or {}
+            for key in ("Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance", "Clip Name"):
+                wanted = before["clipProperties"].get(key)
+                if wanted is not None and current_properties.get(key) != wanted:
+                    require(media.SetName(wanted) if key == "Clip Name" else media.SetClipProperty(key, wanted), "APPLY_OUTCOME_UNKNOWN", "素材已替换，但媒体解释未能恢复。", property=key, expected=wanted)
+            readback = media.GetClipProperty() or {}
+            require(all(readback.get(key) == before["clipProperties"].get(key) for key in ("Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance", "Clip Name") if key in before["clipProperties"]),
+                    "APPLY_OUTCOME_UNKNOWN", "媒体解释读回与替换前不同，需核对原生状态。")
+        set_metadata(media, {**before["metadata"], **params["metadata"]})
+        after = media_identity(project, scope, media)
+        require_active_project(resolve, project)
+        if operation == "replace":
+            require(os.path.realpath(after["path"]) == path, "APPLY_OUTCOME_UNKNOWN", "替换后的原素材路径读回不一致。")
+            for key in ("FPS", "Frames", "Resolution", "Audio Ch", "Input Color Space", "Input Gamma", "Data Level"):
+                require(before["clipProperties"].get(key) == after["clipProperties"].get(key), "APPLY_OUTCOME_UNKNOWN", "替换后媒体规格或颜色解释改变。", property=key)
+        return after
+    if operation == "insert":
+        require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出。")
+        require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证插入的帧边界。")
+        timeline = timeline_for(project, params["timelineId"])
+        before = timeline_snapshot(project, scope, timeline, resolve)
+        require(before["fingerprint"] == params["expectedTimelineFingerprint"], "VERSION_CONFLICT", "时间线在插入前发生变化。")
+        start, end, track, record = params["sourceIn"], params["sourceOut"], params["track"], params["recordFrame"]
+        spec = params.get("outputSpec") or {}
+        require(spec.get("fps") and spec.get("frameCount"), "OUTPUT_SPEC_UNVERIFIED", "插入需要已验证的源帧率与帧数。")
+        timeline_frames = native_timeline_frames(end - start, spec["fps"], before["fps"])
+        require(0 <= start < end and 1 <= track <= timeline.GetTrackCount("video") + 1 and record >= before["startFrame"], "INVALID_RANGE", "轨道或源区间不合法。")
+        require(track > timeline.GetTrackCount("video") or not timeline.GetIsTrackLocked("video", track), "TARGET_LOCKED", "目标视频轨已锁定，未导入或插入媒体。")
+        require(not any(i["track"] == track and i["startFrame"] < record + timeline_frames and record < i["endFrame"] for i in before["items"]), "TARGET_OCCUPIED", "目标轨道区间已有片段。")
+        path = os.path.realpath(params["filePath"])
+        require(os.path.isfile(path), "ARTIFACT_MISSING", "插入产物不存在。")
+        require(project.SetCurrentTimeline(timeline), "VERSION_CONFLICT", "无法明确切换到目标时间线。")
+        await_timeline(project, timeline, resolve=resolve)
+        # Resolve's insertion API is current-timeline based: select explicitly and read back.
+        require(project.GetCurrentTimeline().GetUniqueId() == params["timelineId"], "VERSION_CONFLICT", "当前时间线与目标不一致。")
+        save_insert_progress(params, before, "prepared")
+        if track == timeline.GetTrackCount("video") + 1:
+            require(timeline.AddTrack("video") and timeline.GetTrackCount("video") == track, "APPLY_OUTCOME_UNKNOWN", "新视频轨创建结果需要核对。")
+            before = timeline_snapshot(project, scope, timeline, resolve)
+            save_insert_progress(params, before, "track-added")
+        existing = params.get("existingMediaPoolItemId")
+        if existing:
+            media = media_for(project, existing)
+            require(os.path.realpath(media.GetClipProperty().get("File Path", "")) == path, "VERSION_CONFLICT", "共享素材路径已改变。")
+            actual_metadata = media.GetThirdPartyMetadata() or {}
+            require(all(actual_metadata.get(k) == v for k, v in params["metadata"].items()), "VERSION_CONFLICT", "共享素材的关联元数据已改变。")
+        else:
+            known_media = {item.GetUniqueId() for item in all_media(project.GetMediaPool().GetRootFolder())}
+            imported = project.GetMediaPool().ImportMedia([path]) or []
+            require(len(imported) == 1, "APPLY_OUTCOME_UNKNOWN", "导入结果需核对，未继续盲目插入。")
+            media = imported[0]
+            linked = (media.GetThirdPartyMetadata() or {}).get("motionharness.bridge")
+            require(not linked or linked == params["metadata"].get("motionharness.bridge"), "APPLY_OUTCOME_UNKNOWN", "Resolve 返回了已关联对象，需核对绑定身份，未覆盖其元数据。")
+        save_insert_progress(params, before, "imported", media)
+        set_metadata(media, params["metadata"])
+        save_insert_progress(params, before, "identified", media)
+        newly_imported = not existing and media.GetUniqueId() not in known_media
+        if newly_imported and params.get("sourceName"):
+            require(media.SetName(params["sourceName"]) and media.GetName() == params["sourceName"],
+                    "APPLY_OUTCOME_UNKNOWN", "媒体已导入，但工程名称没有确认；尚未插入时间线。")
+        initialize_imported = params.get("initializeImported") is True
+        if initialize_imported:
+            imported_state = media_snapshot(project, scope, media, resolve)
+            require(imported_state["usageScanComplete"] and not imported_state["uses"], "RECOVERY_CONFLICT", "待恢复的导入媒体已有时间线引用，未重新解释透明通道。")
+        if (newly_imported or initialize_imported) and params.get("outputSpec", {}).get("alpha") == "straight":
+            require(media.SetClipProperty("Alpha mode", "Straight") and (media.GetClipProperty() or {}).get("Alpha mode") == "Straight",
+                    "APPLY_OUTCOME_UNKNOWN", "媒体已导入，但直通透明解释没有确认；尚未插入时间线。")
+        require(project.GetCurrentTimeline().GetUniqueId() == params["timelineId"], "APPLY_OUTCOME_UNKNOWN", "导入后当前时间线发生变化，已保留导入对象以便恢复。")
+        actual = timeline_snapshot(project, scope, timeline, resolve)
+        require(actual["fingerprint"] == before["fingerprint"], "APPLY_OUTCOME_UNKNOWN", "导入期间目标时间线发生变化，停止插入。")
+        created = project.GetMediaPool().AppendToTimeline([{"mediaPoolItem": media, "startFrame": start, "endFrame": end,
+                                                        "mediaType": 1, "trackIndex": track, "recordFrame": record}]) or []
+        require(len(created) == 1, "APPLY_OUTCOME_UNKNOWN", "Resolve 未返回唯一插入对象，需核对后恢复。")
+        save_insert_progress(params, before, "appended", media, created[0])
+        item = item_snapshot(created[0], timeline.GetUniqueId(), track, True, {media.GetUniqueId(): media}, before["fps"])
+        sampling_matches = item["sourceIn"] == start and item["sourceOut"] == end
+        if spec["fps"] != before["fps"]:
+            expected_start = start * spec["fps"]["den"] / spec["fps"]["num"]
+            expected_end = sample_end_time(start, timeline_frames, spec["fps"], before["fps"], spec["frameCount"])
+            sampling_matches = abs(item["sourceStartTime"] - expected_start) < 1e-6 and abs(item["sourceEndTime"] - expected_end) < 1e-6
+        require(item["startFrame"] == record and item["endFrame"] == record + timeline_frames and sampling_matches,
+                "APPLY_OUTCOME_UNKNOWN", "实际插入的位置、源区间或帧数不匹配。", actual=item)
+        return {"media": media_snapshot(project, scope, media, resolve), "item": item}
+    raise BridgeFailure("CAPABILITY_UNAVAILABLE", "该脚本操作尚未实现。", operation=operation)
+
+
+def main():
+    try:
+        scratch = os.environ.get("MH_BRIDGE_SCRATCH")
+        if scratch:
+            os.makedirs(scratch, mode=0o700, exist_ok=True)
+            tempfile.tempdir = scratch
+        request = json.load(sys.stdin)
+        result = dispatch(connect(), request["operation"], request.get("params", {}))
+        response = {"ok": True, "result": result}
+    except BridgeFailure as error:
+        response = {"ok": False, "error": {"code": error.code, "message": error.message, "details": error.details}}
+    except Exception as error:
+        response = {"ok": False, "error": {"code": "RESOLVE_ADAPTER_ERROR", "message": str(error)}}
+    print(json.dumps(response, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()