@motionharness/bridge-davinci 0.0.0-stage → 0.0.22

package/dist/legacy_conversion.py

@@ -0,0 +1,619 @@
+"""Convert recognized legacy generators only inside a newly duplicated timeline.
+
+The original timeline and original media objects are never mutation targets.
+Unknown Fusion processing remains on the original timeline; a copy is refused
+when it would retain an unconverted Fusion item or unverified nonzero fades.
+A native failure leaves an owned copy and a durable journal for inspection;
+it never retries a destructive step.
+"""
+import copy
+import json
+import math
+import os
+import tempfile
+import uuid
+
+import intrinsic_runtime as intrinsic
+from runtime_io import atomic_json, file_digest
+
+
+_MEDIA_PROPERTIES = ("File Path", "FPS", "Frames", "Resolution", "Start", "Audio Ch", "Proxy Media Path",
+                     "Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance", "Clip Name")
+_INTERPRETATION = ("Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance")
+_STATIC_EFFECTS = {"Transform", "Cropping", "Composite", "Lens Correction", "Retime and Scaling", "Video Faders"}
+_EMPTY_EFFECTS = {"Source Transform", "Source Cropping", "Source Looks", "Immersive Transform", "Immersive Output Transform"}
+# Ordinary video exposes these default sections; generators do not. Only their
+# exact no-op state is allowed to appear during conversion.
+_VIDEO_DEFAULTS = {"Distortion": 0, "RetimeProcess": 0, "MotionEstimation": 0, "Scaling": 0, "ResizeFilter": 0,
+                   "LensCorrectionEnabled": True, "RetimeAndScalingEnabled": True}
+_LIMITS = ["仅转换完整识别的自有旧生成器、原速、同帧率、整数帧裁切。",
+           "任何 Fusion 片段无法完整转换或未在本次范围内时，保留原时间线，不创建转换副本。",
+           "时间线含非零视频淡入淡出时，不自动转换：当前宿主的 SetFades 保存重开尚不能保证保留。",
+           "转换仅写入 DuplicateTimeline 副本；新视频使用独立媒体对象与关联。",
+           "结构读回不等于画面或宿主稳定性验收；当前旧生成器转换仍为实验性功能。"]
+
+
+def _json(value):
+    return json.loads(json.dumps(value, ensure_ascii=False, allow_nan=False))
+
+
+def _scratch(api):
+    path = os.environ.get("MH_BRIDGE_SCRATCH", "")
+    api["require"](os.path.isabs(path), "INVALID_REQUEST", "缺少桥接原生操作目录。")
+    os.makedirs(path, mode=0o700, exist_ok=True)
+    return os.path.realpath(path)
+
+
+def _media(media):
+    properties = media.GetClipProperty() or {}
+    return {"mediaPoolItemId": media.GetUniqueId(), "path": properties.get("File Path", ""),
+            "properties": {key: properties.get(key) for key in _MEDIA_PROPERTIES},
+            "metadata": media.GetThirdPartyMetadata() or {}}
+
+
+def _native(item, kind, track):
+    media = item.GetMediaPoolItem()
+    video = kind == "video"
+    result = {"id": item.GetUniqueId(), "trackType": kind, "track": track, "kind": item.GetType(), "name": item.GetName(),
+              "mediaPoolItemId": media.GetUniqueId() if media else None,
+              "startFrame": item.GetStart(True), "endFrame": item.GetEnd(True), "duration": item.GetDuration(True),
+              "sourceStart": item.GetSourceStartFrame(), "sourceEnd": item.GetSourceEndFrame(),
+              "sourceStartTime": item.GetSourceStartTime(), "sourceEndTime": item.GetSourceEndTime(),
+              "properties": item.GetProperties(), "speed": item.GetSpeed(), "fades": item.GetFades(),
+              "enabled": item.GetClipEnabled(), "markers": item.GetMarkers(),
+              "flags": sorted(item.GetFlagList() or []), "clipColor": item.GetClipColor(),
+              "fusionCount": item.GetFusionCompCount(), "takes": item.GetTakesCount(),
+              "linked": [other.GetUniqueId() for other in item.GetLinkedItems() or []]}
+    if video and result["kind"] != "transition":
+        graph = item.GetNodeGraph()
+        group = item.GetColorGroup()
+        result.update(gradeTools=[graph.GetToolsInNode(index) or [] for index in range(1, graph.GetNumNodes() + 1)] if graph else [],
+                      colorGroup=group.GetName() if group else None, version=item.GetCurrentVersion(),
+                      versions={"local": item.GetVersionNameList(0), "remote": item.GetVersionNameList(1)},
+                      outputBlanking=item.GetOutputBlanking(), timelineBlanking=item.GetUseTimelineForOutputBlanking(),
+                      stereo=[item.GetStereoConvergenceValues(), item.GetStereoLeftFloatingWindowParams(), item.GetStereoRightFloatingWindowParams()])
+    return _json(result)
+
+
+def _otio(resolve, timeline, api):
+    with tempfile.TemporaryDirectory(prefix="legacy-otio-", dir=_scratch(api)) as directory:
+        path = os.path.join(directory, "timeline.otio")
+        api["require"](timeline.Export(path, resolve.EXPORT_OTIO), "CAPABILITY_UNAVAILABLE", "无法读取完整时间线效果，未转换旧片段。")
+        with open(path, encoding="utf-8") as stream:
+            document = json.load(stream)
+    api["require"](str(document.get("OTIO_SCHEMA", "")).startswith("Timeline.")
+                   and str(document.get("tracks", {}).get("OTIO_SCHEMA", "")).startswith("Stack."),
+                   "CAPABILITY_UNAVAILABLE", "时间线交换结构不完整，未转换旧片段。")
+    # DuplicateTimeline legitimately changes the timeline name, not its contents.
+    document.pop("name", None)
+    return document
+
+
+def _capture(resolve, project, scope, timeline, api):
+    api["require_active_project"](resolve, project)
+    api["require"](not project.IsRenderingInProgress(), "RESOLVE_BUSY", "达芬奇正在渲染，未读取或转换生成器。")
+    with api["timeline_context"](resolve, timeline):
+        native, objects, tracks = [], {}, []
+        for kind in ("video", "audio", "subtitle"):
+            for track in range(1, timeline.GetTrackCount(kind) + 1):
+                tracks.append({"kind": kind, "index": track, "name": timeline.GetTrackName(kind, track),
+                               "enabled": timeline.GetIsTrackEnabled(kind, track), "locked": timeline.GetIsTrackLocked(kind, track)})
+                items = sorted(timeline.GetItemListInTrack(kind, track) or [], key=lambda item: (item.GetStart(True), item.GetEnd(True), item.GetType(), item.GetUniqueId()))
+                for item in items:
+                    value = _native(item, kind, track)
+                    value["slot"] = len(native)
+                    native.append(value)
+                    objects[value["id"]] = item
+        media_index = {item.GetUniqueId(): item for item in api["all_media"](project.GetMediaPool().GetRootFolder())}
+        entries, sources = {}, {}
+        for value in native:
+            item = objects[value["id"]]
+            if value["trackType"] == "video" and not value["mediaPoolItemId"] and value["fusionCount"]:
+                entry = intrinsic.read_entry(item, media_index)
+                if entry:
+                    entries[value["id"]] = entry
+                    media_id = entry["identity"]["mediaPoolItemId"]
+                    sources[media_id] = _media(media_index[media_id])
+            elif value["mediaPoolItemId"]:
+                sources[value["mediaPoolItemId"]] = _media(media_index[value["mediaPoolItemId"]])
+        settings = project.GetSettings() or {}
+        result = {"scope": scope, "timelineId": timeline.GetUniqueId(), "startFrame": timeline.GetStartFrame(),
+                  "endFrame": timeline.GetEndFrame(), "settings": timeline.GetSettings(), "markers": timeline.GetMarkers(),
+                  "outputBlanking": timeline.GetOutputBlanking(), "tracks": tracks, "items": native,
+                  "entries": entries, "sources": sources, "otio": _otio(resolve, timeline, api),
+                  "grades": api["grade_evidence"](resolve, timeline, list(objects.values()), set(entries)),
+                  "projectSettings": {key: value for key, value in settings.items() if key.startswith(("color", "timeline", "node", "perf")) and not key.startswith("colorGallery")}}
+        api["require_active_project"](resolve, project)
+        api["require"](all(_native(objects[value["id"]], value["trackType"], value["track"]) == {key: val for key, val in value.items() if key != "slot"} for value in native),
+                       "VERSION_CONFLICT", "读取过程中时间线被另一控制端改变。")
+        return _json(result), objects, media_index
+
+
+def _semantic(state):
+    value = copy.deepcopy(state)
+    value.pop("timelineId")
+    slots = {item["id"]: item["slot"] for item in value["items"]}
+    value["entries"] = {str(slots[key]): entry for key, entry in value["entries"].items()}
+    value["grades"] = {str(slots[key]): grade for key, grade in value["grades"].items()}
+    for item in value["items"]:
+        item.pop("id")
+        item["linked"] = sorted((slots.get(link, "outside:" + link) for link in item["linked"]), key=str)
+    return value
+
+
+def _clip(state, native, api):
+    rate = api["fps_value"](state["settings"]["timelineFrameRate"])
+    fps = rate["num"] / rate["den"]
+    video_track, found = 0, []
+    for track in state["otio"]["tracks"].get("children", []):
+        if track.get("kind") != "Video":
+            continue
+        video_track += 1
+        if video_track != native["track"]:
+            continue
+        cursor, children = state["startFrame"], track.get("children", [])
+        for index, child in enumerate(children):
+            kind = str(child.get("OTIO_SCHEMA", "")).split(".")[0]
+            duration = (child.get("source_range") or {}).get("duration")
+            frames = duration["value"] / duration["rate"] * fps if duration and duration.get("rate") else None
+            if kind == "Clip" and frames is not None and abs(cursor - native["startFrame"]) < .001 and abs(frames - native["duration"]) < .001:
+                adjacent = any(str(children[neighbor].get("OTIO_SCHEMA", "")).startswith("Transition.")
+                               for neighbor in (index - 1, index + 1) if 0 <= neighbor < len(children))
+                found.append({"value": child, "track": track, "index": index, "adjacentTransition": adjacent})
+            if kind != "Transition":
+                if frames is None or not math.isfinite(frames):
+                    return None
+                cursor += frames
+    return found[0] if len(found) == 1 else None
+
+
+def _effects_reasons(clip, source_in=0):
+    reasons = []
+    for effect in clip.get("effects", []):
+        data = effect.get("metadata", {}).get("Resolve_OTIO", {})
+        name, parameters = data.get("Effect Name"), data.get("Parameters", [])
+        if not str(effect.get("OTIO_SCHEMA", "")).startswith("Effect.") or effect.get("effect_name") != "Resolve Effect":
+            reasons.append(("legacy-retime-or-effect", "存在不能无损复制的时间效果或额外效果。")); continue
+        if name == "Dynamic Zoom":
+            if data.get("Enabled") is not False:
+                reasons.append(("legacy-dynamic-zoom", "动态缩放含原生曲线，当前保留旧结构。"))
+            else:
+                # The host exports default curve offsets relative to the trim.
+                left, right = str(-int(source_in)), str(1000 - int(source_in))
+                defaults = {"dynamicZoomCenter": {left: [0.0, 0.0], right: [0.0, 0.0]}, "dynamicZoomScale": {left: 0.8, right: 1.0}}
+                if any(parameter.get("Parameter ID") not in defaults or
+                       {str(key): frame.get("Value") for key, frame in parameter.get("Key Frames", {}).items()} != defaults[parameter["Parameter ID"]]
+                       for parameter in parameters):
+                    reasons.append(("legacy-disabled-animation", "已停用的动态缩放仍有自定义曲线，不能丢弃。"))
+            continue
+        if name in _EMPTY_EFFECTS and parameters:
+            reasons.append(("legacy-hidden-parameters", "源或沉浸式效果包含公开属性无法复制的参数。"))
+        elif name not in _STATIC_EFFECTS | _EMPTY_EFFECTS:
+            reasons.append(("legacy-extra-effect", "存在未支持的效果：" + str(name)))
+        if any(parameter.get("Key Frames") for parameter in parameters):
+            reasons.append(("legacy-inspector-keyframes", "检查器包含关键帧，公开静态属性不能完整迁移。"))
+    return reasons
+
+
+def _properties_match(before, after):
+    return (all(key in after and after[key] == value for key, value in before.items())
+            and all(key in _VIDEO_DEFAULTS and value == _VIDEO_DEFAULTS[key] for key, value in after.items() if key not in before))
+
+
+def _default_versions(item):
+    # 21.1 reports one default remote-version placeholder even for generators
+    # with no MediaPoolItem. The exported seed retains its English placeholder.
+    defaults = {"Version1", "Version 1", "版本1", "版本 1"}
+    current, versions = item.get("version") or {}, item.get("versions") or {}
+    local, remote = versions.get("local") or [], versions.get("remote") or []
+    return (current.get("versionType") == 0 and current.get("versionName") in defaults
+            and local == [current["versionName"]] and len(remote) <= 1 and all(name in defaults for name in remote))
+
+
+def _default_stereo(values, source_in):
+    if not isinstance(values, list) or len(values) != 3:
+        return False
+    offset = str(int(source_in))
+    window = {"left": 0, "right": 0, "top": 0, "bottom": 0}
+    return (values[0] in ({}, {offset: 0}) and values[1] in ({}, {offset: window})
+            and values[2] in ({}, {offset: window}))
+
+
+def _shifted_markers(markers, source_in):
+    # On the verified host generator marker keys are relative to its trim,
+    # whereas ordinary media marker keys are source-frame coordinates. OTIO
+    # uses the latter for both and independently verifies the conversion.
+    result = {}
+    for frame, marker in markers.items():
+        value = float(frame) + source_in
+        result[str(int(value)) if value.is_integer() else str(value)] = marker
+    return result
+
+
+def _clip_processing(value, original=None):
+    result = copy.deepcopy(value)
+    for key in ("media_reference", "media_references", "active_media_reference_key"):
+        result.pop(key, None)
+    if original is not None:
+        original_names = {effect.get("metadata", {}).get("Resolve_OTIO", {}).get("Effect Name") for effect in original.get("effects", [])}
+        def newly_exposed_default(effect):
+            metadata = effect.get("metadata", {}).get("Resolve_OTIO", {})
+            return (str(effect.get("OTIO_SCHEMA", "")).startswith("Effect.") and effect.get("effect_name") == "Resolve Effect"
+                    and metadata.get("Effect Name") in {"Lens Correction", "Retime and Scaling"} - original_names
+                    and metadata.get("Enabled") is True and metadata.get("Parameters") == [])
+        result["effects"] = [effect for effect in result.get("effects", []) if not newly_exposed_default(effect)]
+    return result
+
+
+def _copy_safety(state, convert_ids):
+    """A whole-timeline duplicate must preserve every item, including unselected ones."""
+    fusion_items, blockers = [], []
+    for item in state["items"]:
+        identity = {"itemId": item["id"], "name": item["name"], "trackType": item["trackType"], "track": item["track"]}
+        if item.get("fusionCount"):
+            fusion_items.append(identity)
+            if item["id"] not in convert_ids:
+                blockers.append({**identity, "code": "legacy-unconverted-fusion",
+                                 "message": "此 Fusion 片段不会在本次转换；尚不能保证副本保存重开后保留其时间映射，原时间线保持，不创建副本。"})
+        fades = item.get("fades") or {}
+        if item["trackType"] == "video" and any(fades.get(key, 0) != 0 for key in ("FadeIn", "FadeOut")):
+            blockers.append({**identity, "code": "legacy-fades-persistence-unverified", "fades": fades,
+                             "message": "此片段含非零视频淡入淡出；当前宿主 SetFades 的保存重开行为未通过验证，不自动复制转换或补写。"})
+    return {"supported": not blockers, "fusionItems": fusion_items, "blockers": blockers}
+
+
+def _plan(resolve, project, scope, params, api):
+    timeline = api["timeline_for"](project, params["timelineId"])
+    state, objects, media_index = _capture(resolve, project, scope, timeline, api)
+    selected = set(params.get("itemIds") or [])
+    api["require"](not selected or selected <= set(objects), "ITEM_MISSING", "预览指定的实例不存在，未按名称猜测。")
+    candidates = []
+    for item in state["items"]:
+        if item["trackType"] != "video" or (selected and item["id"] not in selected):
+            continue
+        entry = state["entries"].get(item["id"])
+        if not selected and (item["mediaPoolItemId"] or not item["fusionCount"]):
+            continue
+        reasons = []
+        if not entry:
+            reasons.append(("legacy-identity-unrecognized", "不是完整识别的 Hotion Harness 旧生成器，保持原结构。"))
+        candidate = {"itemId": item["id"], "name": item["name"], "track": item["track"], "startFrame": item["startFrame"], "endFrame": item["endFrame"]}
+        if entry:
+            identity = entry["identity"]
+            media = state["sources"][identity["mediaPoolItemId"]]
+            candidate.update(identity=identity, media={**media, "fingerprint": api["fingerprint"](media)})
+            comp = objects[item["id"]].GetFusionCompByIndex(1)
+            attrs = comp.GetAttrs()
+            start, end = attrs["COMPN_GlobalStart"], attrs["COMPN_GlobalEnd"] + 1
+            candidate.update(sourceIn=start, sourceOut=end)
+            if any(identity.get(key) != value for key, value in scope.items()):
+                reasons.append(("legacy-scope-conflict", "生成器身份不属于当前数据库和工程。"))
+            if not api["validated_host"](resolve):
+                reasons.append(("legacy-host-unverified", "当前宿主版本或平台未验证生成器帧边界。"))
+            props = media["properties"]
+            if (not all(isinstance(item.get(key), dict) for key in ("properties", "speed", "fades", "markers", "version"))
+                    or not isinstance(item.get("enabled"), bool) or not isinstance(item.get("timelineBlanking"), bool)):
+                reasons.append(("legacy-native-properties-unavailable", "生成器的静态属性或状态不能完整读取，未尝试删除替换。"))
+            if (item.get("speed") or {}).get("Percentage") != 100 or end - start != item["duration"]:
+                reasons.append(("legacy-time-map", "只支持原速且源区间与时间线时长一致的生成器。"))
+            if not all(isinstance(value, (int, float)) and math.isfinite(value) and int(value) == value for value in (start, end, item["startFrame"], item["endFrame"])):
+                reasons.append(("legacy-subframe", "包含尚未验证的亚帧边界。"))
+            if api["fps_value"](props["FPS"]) != api["fps_value"](state["settings"]["timelineFrameRate"]):
+                reasons.append(("legacy-cross-fps", "旧生成器与时间线帧率不同，保持原结构。"))
+            if str(props.get("Audio Ch", "0")) not in ("", "0") or item["linked"]:
+                reasons.append(("legacy-linked-audio", "存在源音频或联动实例，不能只替换视频。"))
+            if not os.path.isfile(media["path"]) or props.get("Proxy Media Path"):
+                reasons.append(("legacy-media-unavailable", "原视频离线或附带代理，无法核对真实源。"))
+            if item["takes"]:
+                reasons.append(("legacy-take-selector", "已有 Take 选择器，保持原结构。"))
+            if any(track["locked"] for track in state["tracks"] if track["kind"] == "video" and track["index"] == item["track"]):
+                reasons.append(("legacy-track-locked", "轨道已锁定，复制时间线也保持锁定。"))
+            if any(item.get("gradeTools", [])) or item.get("colorGroup") or str(state["projectSettings"].get("nodeStackLayers", "1")) != "1":
+                reasons.append(("legacy-color-processing", "存在调色节点、组或多层节点，无法完整核对其关键帧。"))
+            if not state["grades"].get(item["id"], {}).get("identity"):
+                reasons.append(("legacy-nonidentity-grade", "调色 LUT 不是恒等变换；当前保留旧结构，避免丢失主色轮或未可完整读取的调色。"))
+            if state["grades"].get(item["id"], {}).get("unsupported"):
+                reasons.append(("legacy-grade-unverified", "当前调色不能完整核对，保持旧结构。"))
+            if not _default_versions(item):
+                reasons.append(("legacy-color-versions", "包含多个或远程调色版本，不能丢弃版本。"))
+            if not _default_stereo(item.get("stereo"), start):
+                reasons.append(("legacy-stereo-animation", "包含立体窗口或汇聚设置，保持原结构。"))
+            if (item.get("properties") or {}).get("Distortion"):
+                reasons.append(("legacy-lens-correction", "非默认镜头校正尚未验证。"))
+            clip = _clip(state, item, api)
+            if not clip:
+                reasons.append(("legacy-otio-coverage", "无法将实例唯一对应到公开时间线结构。"))
+            else:
+                if clip["adjacentTransition"]:
+                    reasons.append(("legacy-adjacent-transition", "相邻转场不能通过当前替换方式完整保留，生成器与转场一起保留。"))
+                reasons.extend(_effects_reasons(clip["value"], start))
+        candidate["reasons"] = [{"code": code, "message": message} for code, message in sorted(set(reasons))]
+        candidate["status"] = "keep" if reasons else "convert"
+        candidates.append(candidate)
+    copy_safety = _copy_safety(state, {item["itemId"] for item in candidates if item["status"] == "convert"})
+    return {"scope": scope, "timelineId": timeline.GetUniqueId(), "name": timeline.GetName(),
+            "fingerprint": api["fingerprint"](state), "candidates": candidates, "copySafety": copy_safety, "limits": _LIMITS,
+            "originalPreserved": True}, state, objects, media_index
+
+
+def preview(resolve, project, scope, params, api):
+    return _plan(resolve, project, scope, params, api)[0]
+
+
+def _journal_path(params, api):
+    scratch = _scratch(api)
+    path = os.path.realpath(params.get("nativeJournal", ""))
+    api["require"](os.path.dirname(path) == scratch and isinstance(params.get("nativeToken"), str) and params["nativeToken"],
+                   "INVALID_REQUEST", "原生迁移记录必须位于当前桥接工作目录。")
+    return path
+
+
+def check(resolve, project, scope, params, api):
+    path = _journal_path(params, api)
+    if not os.path.exists(path):
+        current = preview(resolve, project, scope, params, api)
+        unchanged = current["fingerprint"] == params["expectedFingerprint"]
+        return {"completed": False, "canResume": unchanged, "originalPreserved": unchanged, "stage": "not-started", "imports": [], "mappings": []}
+    with open(path, encoding="utf-8") as stream:
+        record = json.load(stream)
+    api["require"](record.get("token") == params["nativeToken"] and record.get("scope") == scope and record.get("originalTimelineId") == params["timelineId"],
+                   "RECOVERY_CONFLICT", "迁移记录身份与当前任务不一致。")
+    original = api["timeline_for"](project, params["timelineId"])
+    original_state = _capture(resolve, project, scope, original, api)[0]
+    original_matches = api["fingerprint"](original_state) == record["originalFingerprint"]
+    copies = [timeline for timeline in api["timelines"](project) if timeline and timeline.GetUniqueId() == record.get("timelineId")]
+    copied = copies[0] if len(copies) == 1 else None
+    copy_matches = bool(copied and record.get("checkpoint") and _capture(resolve, project, scope, copied, api)[0] == record["checkpoint"])
+    completed = record.get("stage") == "completed" and original_matches and copy_matches
+    return {"completed": completed, "canResume": completed, "stage": record.get("stage"), "originalPreserved": original_matches,
+            "checkpointMatches": copy_matches, "timelineId": record.get("timelineId"), "result": record.get("result") if completed else None,
+            "imports": record.get("imports", []), "mappings": record.get("mappings", []),
+            "copyMissing": bool(record.get("timelineId") and not copied),
+            "unattributedTimelineIds": [timeline.GetUniqueId() for timeline in api["timelines"](project)
+                                        if timeline and timeline.GetUniqueId() not in record.get("previousTimelineIds", [])] if not record.get("timelineId") else [],
+            "nextStep": "原时间线保留；未完整结束的隔离副本需核对，不自动重放删除或插入。"}
+
+
+def convert(resolve, project, scope, params, api):
+    require, failure = api["require"], api["BridgeFailure"]
+    path = _journal_path(params, api)
+    if os.path.exists(path):
+        existing = check(resolve, project, scope, params, api)
+        require(existing["completed"], "RECOVERY_REQUIRED", "已有迁移记录，未创建第二个副本；请先检查原任务。", native=existing)
+        return existing["result"]
+    plan, original_state, _original_objects, media_index = _plan(resolve, project, scope, params, api)
+    require(plan["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "预览后的原时间线已改变，未创建副本。")
+    wanted = set(params.get("convertItemIds") or [])
+    candidates = {item["itemId"]: item for item in plan["candidates"] if item["itemId"] in wanted}
+    require(0 < len(wanted) <= 20 and len(candidates) == len(wanted) and all(item["status"] == "convert" for item in candidates.values()),
+            "UNSUPPORTED_TIMELINE_ITEM", "请求包含无法完整迁移的生成器，未创建副本。")
+    # Recheck the final request, not only the preview's eligible candidates:
+    # missing catalog records can remove an otherwise eligible Fusion item.
+    copy_safety = _copy_safety(original_state, wanted)
+    require(copy_safety["supported"], "UNSUPPORTED_TIMELINE_ITEM",
+            "整条时间线的副本无法保证保留，原时间线保持；未复制时间线或导入媒体。", copySafety=copy_safety)
+    replacements = {item["oldBindingId"]: item for item in params["replacements"]}
+    require(set(replacements) == {item["identity"]["bindingId"] for item in candidates.values()}, "INVALID_REQUEST", "新媒体清单与预览范围不一致。")
+    for replacement in replacements.values():
+        require(all(candidate["identity"]["mediaPoolItemId"] == replacement["oldMediaPoolItemId"]
+                    and candidate["identity"]["sourceId"] == replacement["sourceId"]
+                    for candidate in candidates.values() if candidate["identity"]["bindingId"] == replacement["oldBindingId"]),
+                "INVALID_REQUEST", "新媒体清单与旧生成器的源身份不一致。")
+        old = media_index[replacement["oldMediaPoolItemId"]]
+        props = old.GetClipProperty()
+        require(os.path.isabs(replacement["filePath"]) and os.path.realpath(props["File Path"]) != os.path.realpath(replacement["filePath"])
+                and file_digest(props["File Path"]) == replacement["sha256"] == file_digest(replacement["filePath"]),
+                "ARTIFACT_CHANGED", "新旧视频不是独立且相同的不可变内容，未转换。")
+        link = json.loads(replacement["metadata"]["motionharness.bridge"])
+        require(link == {"schemaVersion": 1, "sourceId": replacement["sourceId"], "bindingId": replacement["bindingId"], "artifactId": replacement["artifactId"]}
+                and replacement["bindingId"] != replacement["oldBindingId"], "INVALID_REQUEST", "新关联身份无效。")
+        require(not any(os.path.realpath(media.GetClipProperty("File Path") or "") == os.path.realpath(replacement["filePath"]) for media in media_index.values()),
+                "TARGET_OCCUPIED", "新媒体文件已有原生对象，未重复导入。")
+    original = api["timeline_for"](project, params["timelineId"])
+    names = {timeline.GetName() for timeline in api["timelines"](project) if timeline}
+    name = params.get("name")
+    if name:
+        require(name not in names, "TARGET_OCCUPIED", "隔离副本名称已经存在，请选择新名称；未调用 DuplicateTimeline。")
+    else:
+        base = plan["name"] + " · Hotion Harness 转换"
+        name, suffix = base, 2
+        while name in names:
+            name = base + " " + str(suffix)
+            suffix += 1
+    previous = project.GetCurrentTimeline()
+    record = {"schemaVersion": 1, "token": params["nativeToken"], "scope": scope, "originalTimelineId": original.GetUniqueId(),
+              "originalFingerprint": plan["fingerprint"], "stage": "duplicate-intent", "mappings": [], "imports": [],
+              "previousTimelineIds": [timeline.GetUniqueId() for timeline in api["timelines"](project) if timeline]}
+    atomic_json(path, record, allow_nan=False)
+    copied = None
+    try:
+        copied = original.DuplicateTimeline(name)
+        require(copied and copied.GetUniqueId() != original.GetUniqueId(), "APPLY_OUTCOME_UNKNOWN", "DuplicateTimeline 没有返回独立副本；原时间线未作为修改目标。")
+        record.update(timelineId=copied.GetUniqueId(), stage="duplicated")
+        atomic_json(path, record, allow_nan=False)
+        state, objects, _ = _capture(resolve, project, scope, copied, api)
+        require(_semantic(state) == _semantic(original_state), "APPLY_OUTCOME_UNKNOWN", "复制时间线的结构与原时间线不一致，未删除任何片段。")
+        copied_ids = {old["id"]: new["id"] for old, new in zip(original_state["items"], state["items"])}
+        record.update(checkpoint=state, copiedItemIds=copied_ids)
+        atomic_json(path, record, allow_nan=False)
+        require(project.SetCurrentTimeline(copied), "CAPABILITY_UNAVAILABLE", "无法选择隔离副本。")
+        api["await_timeline"](project, copied, resolve=resolve)
+        pool, imported = project.GetMediaPool(), {}
+
+        def guard():
+            api["require_active_project"](resolve, project)
+            require(project.GetCurrentTimeline().GetUniqueId() == copied.GetUniqueId() and not project.IsRenderingInProgress(),
+                    "VERSION_CONFLICT", "转换期间当前时间线或渲染状态改变，未继续修改。")
+            require(_capture(resolve, project, scope, original, api)[0] == original_state, "VERSION_CONFLICT", "原时间线被另一控制端改变，已停止转换。")
+            current = _capture(resolve, project, scope, copied, api)[0]
+            require(current == record["checkpoint"], "RECOVERY_CONFLICT", "隔离副本与操作记录不同，未覆盖其他修改。")
+
+        def step(label, action):
+            guard()
+            record.update(stage=label + "-intent")
+            atomic_json(path, record, allow_nan=False)
+            result = action()
+            record.update(stage=label, checkpoint=_capture(resolve, project, scope, copied, api)[0])
+            atomic_json(path, record, allow_nan=False)
+            require(result, "APPLY_OUTCOME_UNKNOWN", "原生转换步骤未确认成功，已保留原时间线及隔离副本。", stage=label, timelineId=copied.GetUniqueId())
+            return result
+
+        for old_binding, replacement in replacements.items():
+            result = step("import-" + replacement["bindingId"], lambda: pool.ImportMedia([replacement["filePath"]]))
+            require(isinstance(result, list) and len(result) == 1 and result[0].GetUniqueId() not in media_index,
+                    "APPLY_OUTCOME_UNKNOWN", "新视频没有得到独立媒体池身份。")
+            media = result[0]
+            imported[old_binding] = media
+            record["imports"].append({"bindingId": replacement["bindingId"], "mediaPoolItemId": media.GetUniqueId()})
+            atomic_json(path, record, allow_nan=False)
+            old_props = media_index[replacement["oldMediaPoolItemId"]].GetClipProperty()
+            def identify():
+                for key in _INTERPRETATION:
+                    value = old_props.get(key)
+                    # The individual Field Dominance getter reports resolved
+                    # "Progressive" while the full table preserves "Auto".
+                    if value is not None and (media.GetClipProperty() or {}).get(key) != value:
+                        require(media.SetClipProperty(key, value) and (media.GetClipProperty() or {}).get(key) == value,
+                                "APPLY_OUTCOME_UNKNOWN", "新视频解释属性没有完整保留。", property=key)
+                return media.SetThirdPartyMetadata(replacement["metadata"])
+            step("identify-" + replacement["bindingId"], identify)
+            require(media.GetThirdPartyMetadata() == replacement["metadata"], "APPLY_OUTCOME_UNKNOWN", "新媒体关联读回失败。")
+
+        for old_id, candidate in candidates.items():
+            original_item = next(item for item in original_state["items"] if item["id"] == old_id)
+            copied_id = copied_ids[old_id]
+            old_item = objects[copied_id]
+            replacement = replacements[candidate["identity"]["bindingId"]]
+            media = imported[replacement["oldBindingId"]]
+            step("delete-" + old_id, lambda: copied.DeleteClips([old_item], False))
+            require(copied.GetUniqueId() != original.GetUniqueId(), "APPLY_OUTCOME_UNKNOWN", "原时间线不能作为插入目标。")
+            inserted = step("append-" + old_id, lambda: pool.AppendToTimeline([{"mediaPoolItem": media,
+                # The verified 21.1 AppendToTimeline convention is half open;
+                # it differs from AddTake's inclusive end on the same host.
+                "startFrame": candidate["sourceIn"], "endFrame": candidate["sourceOut"],
+                "mediaType": 1, "trackIndex": candidate["track"], "recordFrame": candidate["startFrame"]}]))
+            require(isinstance(inserted, list) and len(inserted) == 1, "APPLY_OUTCOME_UNKNOWN", "原生插入没有返回唯一普通视频。")
+            new_item = inserted[0]
+            require(new_item.GetMediaPoolItem() and new_item.GetMediaPoolItem().GetUniqueId() == media.GetUniqueId()
+                    and new_item.GetFusionCompCount() == 0, "APPLY_OUTCOME_UNKNOWN", "转换结果不是普通媒体片段。")
+            mapping = {"oldItemId": old_id, "copiedItemId": copied_id, "newItemId": new_item.GetUniqueId(),
+                       "oldBindingId": replacement["oldBindingId"], "bindingId": replacement["bindingId"],
+                       "mediaPoolItemId": media.GetUniqueId(), "verified": False}
+            record["mappings"].append(mapping)
+            atomic_json(path, record, allow_nan=False)
+            def configure():
+                checkpoint = _native(new_item, "video", candidate["track"])
+                def write(label, action):
+                    nonlocal checkpoint
+                    api["require_active_project"](resolve, project)
+                    require(project.GetCurrentTimeline().GetUniqueId() == copied.GetUniqueId()
+                            and _native(new_item, "video", candidate["track"]) == checkpoint,
+                            "RECOVERY_CONFLICT", "配置普通片段期间实例或上下文被修改。")
+                    require(action(), "APPLY_OUTCOME_UNKNOWN", "普通片段属性写入没有确认。", property=label)
+                    checkpoint = _native(new_item, "video", candidate["track"])
+                if any(checkpoint["properties"].get(key) != value for key, value in original_item["properties"].items()):
+                    write("properties", lambda: new_item.SetProperties(original_item["properties"]))
+                if checkpoint["fades"] != original_item["fades"]:
+                    write("fades", lambda: new_item.SetFades(original_item["fades"]))
+                if checkpoint["name"] != original_item["name"]:
+                    write("name", lambda: new_item.SetName(original_item["name"]))
+                if checkpoint["enabled"] != original_item["enabled"]:
+                    write("enabled", lambda: new_item.SetClipEnabled(original_item["enabled"]))
+                if original_item.get("timelineBlanking") is not None:
+                    if checkpoint["timelineBlanking"] != original_item["timelineBlanking"]:
+                        write("blanking-mode", lambda: new_item.SetUseTimelineForOutputBlanking(original_item["timelineBlanking"]))
+                    if not original_item["timelineBlanking"] and checkpoint["outputBlanking"] != original_item["outputBlanking"]:
+                        write("blanking", lambda: new_item.SetOutputBlanking(original_item["outputBlanking"]))
+                for frame, marker in original_item["markers"].items():
+                    write("marker", lambda f=frame, m=marker: new_item.AddMarker(float(f) + candidate["sourceIn"], m["color"], m["name"], m.get("note", ""), m["duration"], m.get("customData", "")))
+                for flag in original_item["flags"]:
+                    write("flag", lambda value=flag: new_item.AddFlag(value))
+                if original_item["clipColor"]:
+                    write("clip-color", lambda: new_item.SetClipColor(original_item["clipColor"]))
+                return True
+            step("configure-" + old_id, configure)
+            actual = _native(new_item, "video", candidate["track"])
+            fixed = ("name", "startFrame", "endFrame", "duration", "fades", "enabled", "flags", "clipColor", "gradeTools", "colorGroup", "version", "outputBlanking", "timelineBlanking")
+            require(all(actual.get(key) == original_item.get(key) for key in fixed) and _properties_match(original_item["properties"], actual["properties"])
+                    and _default_versions(actual) and _default_stereo(actual["stereo"], candidate["sourceIn"])
+                    and actual["markers"] == _shifted_markers(original_item["markers"], candidate["sourceIn"]),
+                    "APPLY_OUTCOME_UNKNOWN", "普通视频的区间或支持属性没有完整保留。", itemId=old_id)
+            rate = api["fps_value"](media.GetClipProperty("FPS"))
+            fps = rate["num"] / rate["den"]
+            require(actual["speed"].get("Percentage") == 100 and not actual["linked"] and actual["takes"] == 0
+                    and abs(actual["sourceStartTime"] * fps - candidate["sourceIn"]) < .001
+                    and abs(actual["sourceEndTime"] * fps - candidate["sourceOut"]) < .001,
+                    "APPLY_OUTCOME_UNKNOWN", "普通视频源区间或采样读回不一致。", itemId=old_id)
+            mapping["verified"] = True
+            atomic_json(path, record, allow_nan=False)
+
+        final, final_objects, _ = _capture(resolve, project, scope, copied, api)
+        require(_capture(resolve, project, scope, original, api)[0] == original_state, "APPLY_OUTCOME_UNKNOWN", "原时间线的读回发生改变，已停止验收。")
+        expected = _semantic(original_state)
+        normalized = _semantic(final)
+        require(len(final["items"]) == len(original_state["items"]), "APPLY_OUTCOME_UNKNOWN", "转换后实例数量不一致。")
+        replaced_ids = {mapping["copiedItemId"] for mapping in record["mappings"]}
+        new_ids = {mapping["newItemId"] for mapping in record["mappings"]}
+        require({item["id"] for item in final["items"]} - new_ids == set(copied_ids.values()) - replaced_ids,
+                "APPLY_OUTCOME_UNKNOWN", "未转换的相邻实例身份发生变化。")
+        for mapping in record["mappings"]:
+            old_native = next(item for item in original_state["items"] if item["id"] == mapping["oldItemId"])
+            new_native = next(item for item in final["items"] if item["id"] == mapping["newItemId"])
+            require(new_native["slot"] == old_native["slot"], "APPLY_OUTCOME_UNKNOWN", "相邻实例顺序发生变化。")
+            slot = old_native["slot"]
+            normalized["items"][slot] = expected["items"][slot]
+            normalized["entries"][str(slot)] = expected["entries"][str(slot)]
+            before_clip, after_clip = _clip(original_state, old_native, api), _clip(final, new_native, api)
+            require(before_clip and after_clip, "APPLY_OUTCOME_UNKNOWN", "转换后无法唯一核对公开时间线结构。")
+            before_value, after_value = _clip_processing(before_clip["value"]), _clip_processing(after_clip["value"], before_clip["value"])
+            require(before_value == after_value, "APPLY_OUTCOME_UNKNOWN", "转换后的关键帧、效果、标记或公开源区间不一致。", itemId=mapping["oldItemId"])
+        # Compare every untouched track, clip, transition and source; only the
+        # acknowledged generator nodes and media references may differ.
+        normalized["sources"] = expected["sources"]
+        normalized["otio"] = copy.deepcopy(final["otio"])
+        normalized_state = {**final, "otio": normalized["otio"]}
+        for mapping in record["mappings"]:
+            old_native = next(item for item in original_state["items"] if item["id"] == mapping["oldItemId"])
+            new_native = next(item for item in final["items"] if item["id"] == mapping["newItemId"])
+            old_clip, new_clip = _clip(original_state, old_native, api), _clip(normalized_state, new_native, api)
+            new_clip["track"]["children"][new_clip["index"]] = copy.deepcopy(old_clip["value"])
+        require(normalized == expected, "APPLY_OUTCOME_UNKNOWN", "其他片段、轨道、转场或时间线设置没有完整保留。")
+        kept = [{"oldItemId": item["itemId"], "copiedItemId": copied_ids[item["itemId"]], "reasons": item["reasons"]}
+                for item in plan["candidates"] if item["itemId"] not in wanted]
+        native_media = []
+        for old_binding, media in imported.items():
+            props = media.GetClipProperty()
+            replacement = replacements[old_binding]
+            old_props = media_index[replacement["oldMediaPoolItemId"]].GetClipProperty()
+            require(all(props.get(key) == old_props.get(key) for key in _MEDIA_PROPERTIES if key not in ("File Path", "Clip Name"))
+                    and os.path.realpath(props["File Path"]) == os.path.realpath(replacement["filePath"])
+                    and file_digest(props["File Path"]) == replacement["sha256"] and not media.GetTimeline(),
+                    "APPLY_OUTCOME_UNKNOWN", "新视频的文件内容、规格或媒体解释不一致。")
+            uses = [api["item_snapshot"](final_objects[mapping["newItemId"]], copied.GetUniqueId(), candidates[mapping["oldItemId"]]["track"], True)
+                    for mapping in record["mappings"] if mapping["oldBindingId"] == old_binding]
+            value = {"scope": scope, "projectName": project.GetName(), "mediaPoolItemId": media.GetUniqueId(), "path": props["File Path"],
+                     "metadata": media.GetThirdPartyMetadata(), "uses": uses, "usageScanComplete": False,
+                     "clipProperties": {key: props.get(key) for key in _MEDIA_PROPERTIES}}
+            value["fingerprint"] = api["fingerprint"](value)
+            native_media.append(value)
+        result = {"originalTimelineId": original.GetUniqueId(), "timelineId": copied.GetUniqueId(), "name": copied.GetName(),
+                  "originalPreserved": True, "structuralVerified": True, "pictureValidation": "review-required",
+                  "sampleFrames": sorted({int(frame) for item in candidates.values() for frame in (item["startFrame"], (item["startFrame"] + item["endFrame"] - 1) // 2, item["endFrame"] - 1)}),
+                  "mappings": record["mappings"], "kept": kept, "media": native_media,
+                  "rollback": {"timelineId": original.GetUniqueId(), "method": "use-preserved-original", "overwritesLaterEdits": False}}
+        result = _json(result)
+        record.update(stage="completed", result=result, checkpoint=final)
+        atomic_json(path, record, allow_nan=False)
+        return result
+    except Exception as error:
+        if copied:
+            raise failure("APPLY_OUTCOME_UNKNOWN", "转换在隔离副本中停止；原时间线未作为修改目标，请核对原任务，勿重复创建。",
+                          originalTimelineId=original.GetUniqueId(), timelineId=copied.GetUniqueId(), stage=record.get("stage"),
+                          diagnostic=str(error), nativeDetails=getattr(error, "details", {})) from error
+        raise
+    finally:
+        active = resolve.GetProjectManager().GetCurrentProject()
+        current = project.GetCurrentTimeline() if active and active.GetUniqueId() == project.GetUniqueId() else None
+        if copied and current and current.GetUniqueId() == copied.GetUniqueId() and previous:
+            project.SetCurrentTimeline(previous)
+            api["await_timeline"](project, previous, resolve=resolve)