@motionharness/bridge-davinci 0.0.0-stage → 0.0.23

package/dist/instance_runtime.py

@@ -0,0 +1,469 @@
+"""Detach one ordinary video instance through documented native Take APIs.
+
+This is a journaled sequence, not an atomic Resolve transaction. An interrupted
+host call without a matching persisted checkpoint requires inspection; recovery
+never assumes that a new native state belongs to this request.
+"""
+
+import copy
+import json
+import math
+import os
+import tempfile
+import uuid
+
+from runtime_io import atomic_json, file_digest
+
+
+_INTERPRETATION = ("Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance")
+_TARGET_VARIABLE = {"mediaId", "name", "speed", "sourceStart", "sourceEnd", "sourceStartTime", "sourceEndTime",
+                    "leftOffset", "rightOffset", "takes", "selectedTake"}
+
+
+def _native(item):
+    media = item.GetMediaPoolItem()
+    media_id = media.GetUniqueId() if media else None
+    takes = []
+    for index in range(1, item.GetTakesCount() + 1):
+        take = item.GetTakeByIndex(index)
+        takes.append({"mediaId": take["mediaPoolItem"].GetUniqueId(),
+                      "startFrame": take["startFrame"], "endFrame": take["endFrame"]})
+    selected = item.GetSelectedTakeIndex()
+    # Resolve 21.1 returns zero after leaving and returning to a timeline even
+    # while the take list and its chosen media remain intact. A durable snapshot
+    # uses that unique media identity; ambiguous lists never get an inferred index.
+    matching_takes = [index + 1 for index, take in enumerate(takes) if take["mediaId"] == media_id]
+    if selected == 0 and len(matching_takes) == 1:
+        selected = matching_takes[0]
+    return {"id": item.GetUniqueId(), "kind": item.GetType(), "name": item.GetName(),
+            "mediaId": media_id,
+            "start": item.GetStart(True), "end": item.GetEnd(True), "duration": item.GetDuration(True),
+            "sourceStart": item.GetSourceStartFrame(), "sourceEnd": item.GetSourceEndFrame(),
+            "sourceStartTime": item.GetSourceStartTime(), "sourceEndTime": item.GetSourceEndTime(),
+            "speed": item.GetSpeed(), "properties": item.GetProperties(), "fades": item.GetFades(),
+            "leftOffset": item.GetLeftOffset(True), "rightOffset": item.GetRightOffset(True),
+            "markers": item.GetMarkers(), "enabled": item.GetClipEnabled(),
+            "fusionCount": item.GetFusionCompCount(), "linkedIds": sorted(link.GetUniqueId() for link in item.GetLinkedItems() or []),
+            "takes": takes, "selectedTake": selected}
+
+
+def _media_native(media):
+    return {"id": media.GetUniqueId(), "properties": media.GetClipProperty() or {},
+            "metadata": media.GetThirdPartyMetadata() or {}}
+
+
+def _all_media(folder):
+    yield from folder.GetClipList() or []
+    for child in folder.GetSubFolderList() or []:
+        yield from _all_media(child)
+
+
+def _file_state(path):
+    stat = os.stat(path)
+    return {"device": stat.st_dev, "inode": stat.st_ino, "bytes": stat.st_size, "modifiedNs": stat.st_mtime_ns}
+
+
+class _Transaction:
+    def __init__(self, resolve, project, scope, params, api):
+        self.resolve, self.project, self.scope, self.params, self.api = resolve, project, scope, params, api
+        self.require, self.failure = api["require"], api["BridgeFailure"]
+        self.fingerprint = api["fingerprint"]
+        self.pool = project.GetMediaPool()
+        self.timeline = api["timeline_for"](project, params["timelineId"])
+        found = [(item, track) for track in range(1, self.timeline.GetTrackCount("video") + 1)
+                 for item in self.timeline.GetItemListInTrack("video", track) or [] if item.GetUniqueId() == params["itemId"]]
+        self.require(len(found) == 1, "ITEM_MISSING", "没有找到指定的视频实例，未按名称猜测。")
+        self.item, self.track = found[0]
+        self.old_media = api["media_for"](project, params["oldMediaPoolItemId"])
+        self.new_media = None
+        self.path = os.path.realpath(params["newFilePath"])
+        scratch = os.environ.get("MH_BRIDGE_SCRATCH", "")
+        self.require(os.path.isabs(scratch), "INVALID_REQUEST", "缺少桥接原生操作工作目录。")
+        self.scratch = os.path.realpath(scratch)
+        self.journal_path = params["nativeJournal"]
+        self.require(os.path.isabs(self.journal_path) and not os.path.islink(self.journal_path)
+                     and os.path.dirname(os.path.realpath(self.journal_path)) == self.scratch
+                     and os.path.basename(self.journal_path).startswith("native-instance-"),
+                     "INVALID_REQUEST", "独立实例记录必须位于桥接工作目录。")
+        try:
+            token = uuid.UUID(params["nativeToken"])
+        except (ValueError, TypeError, AttributeError):
+            token = None
+        self.require(token and token.version == 4, "INVALID_REQUEST", "原生操作令牌无效。")
+        self.identity = {"token": str(token), "scope": scope, "timelineId": params["timelineId"], "itemId": params["itemId"],
+                         "oldMediaPoolItemId": params["oldMediaPoolItemId"], "newFilePath": self.path,
+                         "newMetadata": params["newMetadata"], "sourceName": params["sourceName"], "outputSpec": params["outputSpec"],
+                         "expectedTimelineFingerprint": params["expectedTimelineFingerprint"],
+                         "expectedMediaFingerprint": params["expectedMediaFingerprint"]}
+        self.record = None
+
+    def _active(self):
+        self.api["require_active_project"](self.resolve, self.project)
+        current = self.project.GetCurrentTimeline()
+        self.require(current and current.GetUniqueId() == self.timeline.GetUniqueId(), "VERSION_CONFLICT", "当前时间线已改变，未继续修改实例。")
+        self.require(not self.project.IsRenderingInProgress(), "RESOLVE_BUSY", "达芬奇正在导出，未修改实例。")
+
+    def _otio(self, target):
+        with tempfile.TemporaryDirectory(prefix="native-instance-otio-", dir=self.scratch) as directory:
+            path = os.path.join(directory, "timeline.otio")
+            self.require(self.timeline.Export(path, self.resolve.EXPORT_OTIO), "CAPABILITY_UNAVAILABLE", "无法完整检查时间线效果。")
+            with open(path, encoding="utf-8") as stream:
+                value = json.load(stream)
+        shadow = copy.deepcopy(value)
+        matches, video_track = [], 0
+        for track in shadow.get("tracks", {}).get("children", []):
+            if track.get("kind") != "Video":
+                continue
+            video_track += 1
+            if video_track != self.track:
+                continue
+            cursor = 0.0
+            for index, child in enumerate(track.get("children", [])):
+                duration = (child.get("source_range") or {}).get("duration")
+                frames = duration["value"] / duration["rate"] * 30 if duration and duration.get("rate") else None
+                kind = str(child.get("OTIO_SCHEMA", "")).split(".")[0]
+                if (kind not in ("Gap", "Transition") and frames is not None
+                        and abs(cursor + self.timeline.GetStartFrame() - target["start"]) < .001
+                        and abs(frames - target["duration"]) < .001):
+                    matches.append(copy.deepcopy(child))
+                    track["children"][index] = {"HotionHarnessOwnedTarget": self.item.GetUniqueId()}
+                if kind != "Transition":
+                    self.require(frames is not None and math.isfinite(frames), "CAPABILITY_UNAVAILABLE", "时间线区间无法完整读回。")
+                    cursor += frames
+        self.require(len(matches) == 1, "CAPABILITY_UNAVAILABLE", "不能将原生实例唯一对应到时间线结构。")
+        return {"others": shadow, "target": matches[0]}
+
+    def capture(self):
+        self._active()
+        native = _native(self.item)
+        result = {"timeline": self.api["timeline_snapshot"](self.project, self.scope, self.timeline, self.resolve),
+                  "oldMedia": self.api["media_snapshot"](self.project, self.scope, self.old_media, self.resolve),
+                  "oldMediaNative": _media_native(self.old_media),
+                  "target": native, "otio": self._otio(native), "playhead": self.timeline.GetCurrentTimecode(),
+                  "newFile": _file_state(self.path), "oldFile": _file_state(self.old_media.GetClipProperty("File Path")),
+                  "fileCandidates": sorted(media.GetUniqueId() for media in _all_media(self.pool.GetRootFolder())
+                                           if os.path.realpath(media.GetClipProperty("File Path") or "") == self.path),
+                  "newMedia": _media_native(self.new_media) if self.new_media else None}
+        self._active()
+        after_native = _native(self.item)
+        self.require(after_native == native, "VERSION_CONFLICT", "读取期间实例发生变化。",
+                     beforeNative=native, afterNative=after_native)
+        # JSON normalizes numeric marker keys for persisted recovery comparisons.
+        return json.loads(json.dumps(result))
+
+    def save(self):
+        atomic_json(self.journal_path, self.record)
+
+    def guard(self):
+        actual = self.capture()
+        self.require(actual == self.record["checkpoint"], "RECOVERY_CONFLICT", "原生状态与本次操作记录不一致，未覆盖其他修改。")
+        return actual
+
+    def invariants(self, state):
+        original = self.record["original"]
+        self.require({k: v for k, v in state["target"].items() if k not in _TARGET_VARIABLE}
+                     == {k: v for k, v in original["target"].items() if k not in _TARGET_VARIABLE},
+                     "APPLY_OUTCOME_UNKNOWN", "实例的时长、位置、属性或标记发生了意外改变。")
+        self.require(state["otio"]["others"] == original["otio"]["others"], "APPLY_OUTCOME_UNKNOWN", "其他时间线片段或效果发生变化，未继续操作。")
+        ignored = {"items", "sources", "complete", "unsupported", "fingerprint"}
+        self.require({k: v for k, v in state["timeline"].items() if k not in ignored}
+                     == {k: v for k, v in original["timeline"].items() if k not in ignored},
+                     "APPLY_OUTCOME_UNKNOWN", "时间线结构或项目设置发生变化。")
+        def other_items(value):
+            return [{k: v for k, v in item.items() if k != "otioHash"} for item in value["timeline"]["items"] if item["id"] != self.item.GetUniqueId()]
+        self.require(other_items(state) == other_items(original), "APPLY_OUTCOME_UNKNOWN", "其他实例发生变化。")
+        before_target = next(item for item in original["timeline"]["items"] if item["id"] == self.item.GetUniqueId())
+        after_target = next(item for item in state["timeline"]["items"] if item["id"] == self.item.GetUniqueId())
+        changing = {"mediaPoolItemId", "sourceIn", "sourceOut", "sourceStartTime", "sourceEndTime", "leftOffset", "rightOffset", "speed", "otioHash", "unsupported"}
+        self.require({key: value for key, value in before_target.items() if key not in changing}
+                     == {key: value for key, value in after_target.items() if key not in changing},
+                     "RECOVERY_CONFLICT", "实例的调色或其他固定原生状态被改动。")
+        allowed_reasons = {"take-selector-or-multicam"} if state["target"]["takes"] else set()
+        self.require(set(after_target["unsupported"]) - set(before_target["unsupported"]) <= allowed_reasons,
+                     "RECOVERY_CONFLICT", "实例出现了不属于本次操作的效果或结构，未继续覆盖。")
+        media_ignored = {"fingerprint", "uses", "usageScanComplete"}
+        self.require({k: v for k, v in state["oldMedia"].items() if k not in media_ignored}
+                     == {k: v for k, v in original["oldMedia"].items() if k not in media_ignored},
+                     "APPLY_OUTCOME_UNKNOWN", "原媒体或其关联信息发生变化。")
+        def old_native(value):
+            media = value["oldMediaNative"]
+            return {**media, "properties": {key: entry for key, entry in media["properties"].items() if key != "Usage"}}
+        self.require(old_native(state) == old_native(original), "APPLY_OUTCOME_UNKNOWN", "原媒体的完整解释或元数据发生变化。")
+        def other_uses(value):
+            return [{k: v for k, v in use.items() if not (k == "otioHash" and use["timelineId"] == self.timeline.GetUniqueId())}
+                    for use in value["oldMedia"]["uses"] if use["id"] != self.item.GetUniqueId()]
+        self.require(other_uses(state) == other_uses(original), "APPLY_OUTCOME_UNKNOWN", "共享媒体的其他使用位置发生变化。")
+        old_id = self.old_media.GetUniqueId()
+        new_id = self.new_media.GetUniqueId() if self.new_media else None
+        def unrelated_sources(value):
+            return [source for source in value["timeline"]["sources"] if source["mediaPoolItemId"] not in (old_id, new_id)]
+        self.require(unrelated_sources(state) == unrelated_sources(original), "APPLY_OUTCOME_UNKNOWN", "其他素材解释发生变化。")
+        self.require(state["newFile"] == original["newFile"] and state["oldFile"] == original["oldFile"], "ARTIFACT_CHANGED", "操作期间视频文件发生改变。")
+        expected_candidates = [self.new_media.GetUniqueId()] if self.new_media else original["fileCandidates"]
+        self.require(state["fileCandidates"] == expected_candidates, "RECOVERY_CONFLICT", "同一副本文件出现了未确认的媒体对象，未猜测归属。")
+
+    def stage(self, name, mutate, expected, allow_playhead=False):
+        before = self.guard()
+        self.record["intent"] = name
+        self.save()
+        error, accepted = None, False
+        try:
+            accepted = bool(mutate())
+        except Exception as caught:
+            error = caught
+        after = self.capture()
+        self.invariants(after)
+        if before["newMedia"] and after["newMedia"]:
+            allowed_properties = {"Clip Name", "EDL Clip Name"} if name == "named" else {name[len("interpretation-"):]} if name.startswith("interpretation-") else set()
+            allowed_metadata = self.params["newMetadata"].keys() if name in ("identified", "rollback-identify-import") else ()
+            def stable_new(value):
+                media = value["newMedia"]
+                return {"id": media["id"], "properties": {key: entry for key, entry in media["properties"].items() if key != "Usage" and key not in allowed_properties},
+                        "metadata": {key: entry for key, entry in media["metadata"].items() if key not in allowed_metadata}}
+            self.require(stable_new(before) == stable_new(after), "RECOVERY_CONFLICT", "新副本媒体的其他属性被改动，未继续覆盖。")
+        self.require(allow_playhead or after["playhead"] == before["playhead"], "RECOVERY_CONFLICT", "播放头在操作期间改变，未覆盖新的选择。")
+        applied = expected(after)
+        self.require(applied or after == before, "APPLY_OUTCOME_UNKNOWN", "原生调用后的状态无法对应本次操作，停止自动恢复。", stage=name)
+        self.record.update(checkpoint=after, stage=name if applied else self.record["stage"], intent=None,
+                           newMediaPoolItemId=self.new_media.GetUniqueId() if self.new_media else None)
+        self.save()
+        if error or not accepted or not applied:
+            raise self.failure("NATIVE_INSTANCE_STEP_FAILED", "原生实例操作未完成。", stage=name, diagnostic=str(error) if error else None)
+        return after
+
+    def speed(self, percentage, stage):
+        return self.stage(stage, lambda: self.item.SetSpeed({"Percentage": percentage, "RippleTimeline": False}),
+                          lambda state: state["target"]["speed"].get("Percentage") == percentage and not state["target"]["takes"])
+
+    def seek(self, timecode, stage):
+        def mutate():
+            self.api["seek_timecode"](self.project, self.timeline, timecode, resolve=self.resolve)
+            return True
+        return self.stage(stage, mutate, lambda state: state["playhead"].replace(";", ":") == timecode.replace(";", ":"), True)
+
+    def extent(self):
+        state = self.record["checkpoint"]["target"]
+        start, end = state["sourceStartTime"] * 30, state["sourceEndTime"] * 30
+        self.require(abs(start - round(start)) < .001 and abs(end - round(end)) < .001 and 0 <= round(start) < round(end),
+                     "UNSUPPORTED_TIMELINE_ITEM", "实例源区间不能无损转换为原生 Take 帧边界。")
+        return round(start), round(end) - 1
+
+    def add_take(self, media, label):
+        start, end = self.extent()
+        expected_ids = [self.item.GetMediaPoolItem().GetUniqueId(), media.GetUniqueId()]
+        return self.stage(label, lambda: self.item.AddTake(media, start, end),
+                          lambda state: [take["mediaId"] for take in state["target"]["takes"]] == expected_ids)
+
+    def select(self, index, media, label):
+        return self.stage(label, lambda: self.item.SelectTakeByIndex(index),
+                          lambda state: state["target"]["selectedTake"] == index and state["target"]["mediaId"] == media.GetUniqueId())
+
+    def finalize(self, media, label):
+        return self.stage(label, self.item.FinalizeTake,
+                          lambda state: not state["target"]["takes"] and state["target"]["selectedTake"] == 0 and state["target"]["mediaId"] == media.GetUniqueId())
+
+    def restore_speed(self, label):
+        original = self.record["original"]["target"]
+        percentage = original["speed"]["Percentage"]
+        if percentage == 0:
+            timecode = self.api["frame_timecode"](int(original["start"]), {"num": 30, "den": 1}, False)
+            self.seek(timecode, label + "-seek-freeze")
+            self.record["playheadOwned"] = True
+            self.save()
+        if self.item.GetSpeed().get("Percentage") != percentage:
+            self.speed(percentage, label)
+        if self.item.GetName() != original["name"]:
+            self.stage(label + "-name", lambda: self.item.SetName(original["name"]), lambda state: state["target"]["name"] == original["name"])
+        if self.record.get("playheadOwned"):
+            self.seek(self.record["original"]["playhead"], label + "-playhead")
+
+    def verify_final(self, state, media_id):
+        self.invariants(state)
+        expected = copy.deepcopy(self.record["original"]["target"])
+        expected["mediaId"] = media_id
+        self.require(state["target"] == expected, "APPLY_OUTCOME_UNKNOWN", "独立实例的原生时间映射或属性没有完整保留。")
+        def clip(value):
+            return {k: v for k, v in value["otio"]["target"].items() if k not in ("media_references", "media_reference")}
+        self.require(clip(state) == clip(self.record["original"]), "APPLY_OUTCOME_UNKNOWN", "实例的时间线效果没有完整保留。")
+        self.require(state["oldMedia"]["usageScanComplete"], "APPLY_OUTCOME_UNKNOWN", "原媒体的使用位置未能完整读回。")
+        before = next(item for item in self.record["original"]["timeline"]["items"] if item["id"] == self.item.GetUniqueId())
+        after = next(item for item in state["timeline"]["items"] if item["id"] == self.item.GetUniqueId())
+        expected_item = {**before, "mediaPoolItemId": media_id}
+        self.require(after == expected_item, "APPLY_OUTCOME_UNKNOWN", "完整原生读回与原实例不一致。")
+
+    def rollback(self):
+        self.guard()
+        target = self.record["checkpoint"]["target"]
+        old_id = self.old_media.GetUniqueId()
+        new_id = self.new_media.GetUniqueId() if self.new_media else None
+        if target["takes"]:
+            self.require(len(target["takes"]) == 2 and {take["mediaId"] for take in target["takes"]} == {old_id, new_id},
+                         "RECOVERY_CONFLICT", "Take 列表不再属于本次操作，未删除任何 Take。")
+            old_index = next(index + 1 for index, take in enumerate(target["takes"]) if take["mediaId"] == old_id)
+            new_index = 3 - old_index
+            self.select(old_index, self.old_media, "rollback-select-original")
+            self.stage("rollback-delete-copy-take", lambda: self.item.DeleteTakeByIndex(new_index),
+                       lambda state: len(state["target"]["takes"]) == 1 and state["target"]["takes"][0]["mediaId"] == old_id)
+            self.finalize(self.old_media, "rollback-finalize-original")
+        elif target["mediaId"] != old_id:
+            self.require(target["mediaId"] == new_id, "RECOVERY_CONFLICT", "实例已引用其他媒体，未覆盖。")
+            if target["speed"].get("Percentage") != 100:
+                self.speed(100, "rollback-normalize-speed")
+            self.add_take(self.old_media, "rollback-add-original")
+            self.select(2, self.old_media, "rollback-select-original")
+            self.finalize(self.old_media, "rollback-finalize-original")
+        self.restore_speed("rollback-restore-speed")
+        final = self.guard()
+        self.verify_final(final, old_id)
+        self.require(final["oldMedia"] == self.record["original"]["oldMedia"], "APPLY_OUTCOME_UNKNOWN", "原共享素材没有完整恢复。")
+        if self.new_media and self.record["original"]["newMedia"] is None:
+            retained = self.api["media_snapshot"](self.project, self.scope, self.new_media, self.resolve)
+            wanted = self.params["newMetadata"]
+            self.require(retained["usageScanComplete"] and not retained["uses"]
+                         and os.path.realpath(retained["path"]) == self.path
+                         and all(key not in retained["metadata"] or retained["metadata"][key] == value for key, value in wanted.items()),
+                         "RECOVERY_CONFLICT", "保留副本的使用位置或归属已改变，未补写关联。")
+            combined = {**retained["metadata"], **wanted}
+            if retained["metadata"] != combined:
+                self.stage("rollback-identify-import", lambda: self.new_media.SetThirdPartyMetadata(combined),
+                           lambda state: state["newMedia"]["metadata"] == combined)
+        self.record.update(stage="rolled-back", intent=None)
+        self.save()
+        return {"rolledBack": True, "stage": "rolled-back", "retainedMediaPoolItemId": new_id}
+
+    def run(self):
+        self._active()
+        self.require(os.path.isfile(self.path), "ARTIFACT_MISSING", "独立副本视频不存在。")
+        self.require(os.path.isfile(self.old_media.GetClipProperty("File Path") or ""), "ARTIFACT_MISSING", "原视频离线，未复制实例。")
+        os.makedirs(self.scratch, mode=0o700, exist_ok=True)
+        if os.path.exists(self.journal_path):
+            with open(self.journal_path, encoding="utf-8") as stream:
+                self.record = json.load(stream)
+            self.require(self.record.get("schemaVersion") == 1 and self.record.get("identity") == self.identity, "RECOVERY_CONFLICT", "原生记录与当前请求身份不同。")
+            if self.record.get("newMediaPoolItemId"):
+                self.new_media = self.api["media_for"](self.project, self.record["newMediaPoolItemId"])
+            mode = self.params.get("recover")
+            self.require(mode in ("check", "rollback"), "RECOVERY_REQUIRED", "已有原生操作记录，请先检查或恢复，不能重复复制实例。")
+            current = self.capture()
+            matched = current == self.record["checkpoint"]
+            if mode == "check":
+                answer = {"stage": self.record["stage"], "canRollback": matched, "committed": matched and self.record["stage"] == "committed",
+                          "rolledBack": matched and self.record["stage"] == "rolled-back", "checkpointMatches": matched}
+                if answer["committed"]:
+                    answer.update(self.result())
+                return answer
+            return self.rollback()
+        self.require(not self.params.get("recover"), "RECOVERY_MISSING", "没有找到该操作的原生记录。")
+        original = self.capture()
+        self.require(original["timeline"]["fingerprint"] == self.params["expectedTimelineFingerprint"]
+                     and original["oldMedia"]["fingerprint"] == self.params["expectedMediaFingerprint"],
+                     "VERSION_CONFLICT", "时间线或原媒体在复制前已改变。")
+        target = next(item for item in original["timeline"]["items"] if item["id"] == self.item.GetUniqueId())
+        properties = self.old_media.GetClipProperty()
+        percentage = original["target"]["speed"].get("Percentage")
+        spec = self.params["outputSpec"]
+        self.require(original["timeline"].get("validatedHost") and original["timeline"]["fps"] == {"num": 30, "den": 1}
+                     and not original["timeline"].get("dropFrame") and float(properties.get("FPS", 0)) == 30
+                     and spec.get("fps") == {"num": 30, "den": 1}, "UNSUPPORTED_FPS", "独立实例原生操作当前仅验收了素材与时间线均为 30 fps。")
+        self.require(target.get("kind") == "video" and not target["unsupported"] and not target.get("trackLocked")
+                     and target["mediaPoolItemId"] == self.old_media.GetUniqueId() and original["oldMedia"]["usageScanComplete"]
+                     and not original["target"]["takes"] and not self.item.GetLinkedItems()
+                     and not properties.get("Proxy Media Path")
+                     and str(properties.get("Audio Ch", "0")) in ("0", "")
+                     and isinstance(percentage, (int, float)) and math.isfinite(percentage),
+                     "UNSUPPORTED_TIMELINE_ITEM", "此操作仅支持无联动音频、无已有 Take、可完整检查的普通恒速或冻结视频实例。")
+        self.require(all(isinstance(original["target"][key], (int, float)) and math.isfinite(original["target"][key])
+                         and original["target"][key] == int(original["target"][key]) for key in ("start", "end", "duration")),
+                     "UNSUPPORTED_TIMELINE_ITEM", "独立实例操作尚未验收亚帧边界。")
+        normalized_start = original["target"]["sourceStartTime"] * 30
+        self.require(math.isfinite(normalized_start) and abs(normalized_start - round(normalized_start)) < .001
+                     and 0 <= round(normalized_start) and round(normalized_start) + original["target"]["duration"] <= int(properties["Frames"]),
+                     "UNSUPPORTED_TIMELINE_ITEM", "该慢速或长冻结片段无法在临时归一速度时保留原时长，未修改实例。")
+        self.require(isinstance(self.params["sourceName"], str) and self.params["sourceName"].strip(), "INVALID_REQUEST", "副本工程名称不能为空。")
+        metadata = self.params["newMetadata"]
+        try:
+            link = json.loads(metadata["motionharness.bridge"])
+        except (ValueError, TypeError, KeyError):
+            link = None
+        self.require(isinstance(metadata, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in metadata.items())
+                     and isinstance(link, dict) and link.get("schemaVersion") == 1
+                     and all(isinstance(link.get(k), str) and link[k] for k in ("sourceId", "bindingId", "artifactId")),
+                     "INVALID_REQUEST", "新副本关联身份无效。")
+        try:
+            old_link = json.loads(original["oldMedia"]["metadata"].get("motionharness.bridge", "null"))
+        except (ValueError, TypeError):
+            old_link = None
+        self.require(isinstance(old_link, dict) and all(link[key] != old_link.get(key) for key in ("sourceId", "bindingId", "artifactId")),
+                     "INVALID_REQUEST", "副本必须使用独立的源工程、素材和绑定身份。")
+        matches = [media for media in _all_media(self.pool.GetRootFolder()) if os.path.realpath(media.GetClipProperty("File Path") or "") == self.path]
+        self.require(os.path.realpath(original["oldMedia"]["path"]) != self.path and len(matches) <= 1,
+                     "TARGET_OCCUPIED", "副本视频存在多个媒体对象或仍指向原文件，请先核对操作记录。")
+        if matches:
+            existing = self.api["media_snapshot"](self.project, self.scope, matches[0], self.resolve)
+            self.require(existing["metadata"] == metadata and existing["usageScanComplete"] and not existing["uses"],
+                         "TARGET_OCCUPIED", "已有副本媒体的归属或使用位置不符合恢复条件。")
+            self.new_media = matches[0]
+            original = self.capture()
+            self.require(original["timeline"]["fingerprint"] == self.params["expectedTimelineFingerprint"]
+                         and original["oldMedia"]["fingerprint"] == self.params["expectedMediaFingerprint"],
+                         "VERSION_CONFLICT", "复用副本媒体前原实例已改变。")
+        self.require(int(properties["Frames"]) == spec["frameCount"] and properties["Resolution"] == "%sx%s" % (spec["width"], spec["height"])
+                     and file_digest(original["oldMedia"]["path"]) == file_digest(self.path), "ARTIFACT_CHANGED", "独立副本必须先使用与原实例相同的完整视频。")
+        self.record = {"schemaVersion": 1, "identity": self.identity, "stage": "prepared", "intent": None,
+                       "original": original, "checkpoint": original, "newMediaPoolItemId": self.new_media.GetUniqueId() if self.new_media else None, "playheadOwned": False}
+        self.save()
+        try:
+            def import_copy():
+                imported = self.pool.ImportMedia([self.path])
+                if imported and len(imported) == 1:
+                    self.new_media = imported[0]
+                    return True
+                return False
+            if not self.new_media:
+                self.stage("imported", import_copy, lambda state: bool(state["newMedia"]) and os.path.realpath(state["newMedia"]["properties"].get("File Path", "")) == self.path)
+            if self.new_media.GetThirdPartyMetadata() != metadata:
+                self.stage("identified", lambda: self.new_media.SetThirdPartyMetadata(metadata),
+                           lambda state: all(state["newMedia"]["metadata"].get(k) == v for k, v in metadata.items()))
+            for key in ("FPS", "Frames", "Resolution", "Audio Ch"):
+                self.require(self.new_media.GetClipProperty().get(key) == properties.get(key), "ARTIFACT_CHANGED", "新媒体规格读回不同。", property=key)
+            for key in _INTERPRETATION:
+                expected = properties.get(key)
+                if expected is not None and self.new_media.GetClipProperty().get(key) != expected:
+                    self.stage("interpretation-" + key, lambda key=key, value=expected: self.new_media.SetClipProperty(key, value),
+                               lambda state, key=key, value=expected: state["newMedia"]["properties"].get(key) == value)
+            if self.new_media.GetName() != self.params["sourceName"]:
+                self.stage("named", lambda: self.new_media.SetName(self.params["sourceName"]),
+                           lambda state: state["newMedia"]["properties"].get("Clip Name") == self.params["sourceName"]
+                           and ("EDL Clip Name" not in state["newMedia"]["properties"] or state["newMedia"]["properties"]["EDL Clip Name"] == self.params["sourceName"]))
+            if percentage != 100:
+                self.speed(100, "normalized-speed")
+            self.add_take(self.new_media, "take-added")
+            self.select(2, self.new_media, "take-selected")
+            self.finalize(self.new_media, "take-finalized")
+            self.restore_speed("restored-speed")
+            final = self.guard()
+            self.verify_final(final, self.new_media.GetUniqueId())
+            self.record.update(stage="committed", intent=None)
+            self.save()
+            return self.result()
+        except Exception as error:
+            try:
+                rollback = self.rollback()
+            except Exception as recovery_error:
+                raise self.failure("APPLY_OUTCOME_UNKNOWN", "独立实例操作可能部分完成，原生状态不再允许安全自动恢复。",
+                                   rolledBack=False, nativeJournal=self.journal_path, diagnostic=str(error),
+                                   diagnosticDetails=getattr(error, "details", {}),
+                                   recoveryDiagnostic=str(recovery_error)) from error
+            raise self.failure(getattr(error, "code", "NATIVE_INSTANCE_STEP_FAILED"), "独立实例操作未完成，原时间线实例已恢复。",
+                               **rollback, nativeJournal=self.journal_path, diagnostic=str(error)) from error
+
+    def result(self):
+        current = self.guard()
+        self.verify_final(current, self.new_media.GetUniqueId())
+        return {"media": self.api["media_snapshot"](self.project, self.scope, self.new_media, self.resolve),
+                "item": next(item for item in current["timeline"]["items"] if item["id"] == self.item.GetUniqueId()),
+                "oldMedia": current["oldMedia"], "nativeJournal": self.journal_path, "unchangedOtherUses": True}
+
+
+def duplicate_instance(resolve, project, scope, params, api):
+    return _Transaction(resolve, project, scope, params, api).run()

package/dist/intrinsic_runtime.py

@@ -0,0 +1,125 @@
+"""Recognize and refresh owned legacy generators for existing projects.
+
+New clips use ordinary video; generator creation is no longer supported.
+"""
+import copy
+import json
+
+from inspector_runtime import callbacks, settings, signature, tool_id, tool_name, connected_to, canonical
+
+DATA_KEY = 'HotionHarness.Intrinsic.v1'
+TIME_INPUTS = ('GlobalIn', 'GlobalOut', 'ClipTimeStart', 'ClipTimeEnd')
+FIELDS = {'MHSchema': 'schemaVersion', 'MHWorkspaceKey': 'workspaceKey', 'MHSourceId': 'sourceId',
+          'MHBindingId': 'bindingId', 'MHMediaPoolItemId': 'mediaPoolItemId',
+          'MHDatabaseId': 'databaseId', 'MHProjectId': 'projectId'}
+
+
+def stable(value):
+    # Fusion reloads Lua numbers as floats and adds table flags. Neither changes
+    # the saved graph's meaning; preserve every substantive setting and value.
+    if isinstance(value, dict): return {k: stable(v) for k, v in canonical(value).items()}
+    if isinstance(value, list): return [stable(v) for v in value]
+    if isinstance(value, float) and value.is_integer(): return int(value)
+    return value
+
+
+def tools_for(comp):
+    tools = list((comp.GetToolList(False) or {}).values())
+    expected = {'MHBridge': 'MacroOperator', 'HotionHarnessBackground': 'Background',
+                'MediaOut1': 'MediaOut', 'HotionHarnessMedia': 'MediaIn'}
+    actual = {tool_name(t): tool_id(t) for t in tools}
+    if len(tools) != len(actual) or actual != expected:
+        raise ValueError('native generator graph contains unknown or missing tools')
+    by_name = {tool_name(t): t for t in tools}
+    macro = by_name['MHBridge']
+    children = list((macro.GetChildrenList(False) or {}).values())
+    if len(children) != 1 or tool_name(children[0]) != 'HotionHarnessBackground' or tool_id(children[0]) != 'Background':
+        raise ValueError('native generator controller children changed')
+    own = settings(macro)
+    if set(own.get('UserControls', {})) - {'__flags'} != set(FIELDS) | {'MHProjectName', 'MHEdit', 'MHMore'}:
+        raise ValueError('native generator controls changed')
+    for key, code in callbacks().items():
+        if own['UserControls'][key].get('BTNCS_Execute') != code:
+            raise ValueError('native generator button callback changed')
+    if own.get('Outputs', {}).get('MainOutput1', {}).get('SourceOp') != 'HotionHarnessBackground':
+        raise ValueError('native generator interface changed')
+    return by_name
+
+
+def graph(comp, identity, media):
+    by_name = tools_for(comp)
+    macro, image = by_name['MHBridge'], by_name['HotionHarnessMedia']
+    if any(macro.GetInput(key) != identity[field] for key, field in FIELDS.items()):
+        raise ValueError('native generator binding identity changed')
+    if image.GetInput('MediaSource') != 'MediaPool' or image.GetInput('MediaID') != media.GetMediaId():
+        raise ValueError('native generator no longer reads its bound media pool item')
+    if not connected_to(by_name['MediaOut1'], 'HotionHarnessMedia'):
+        raise ValueError('native generator image route changed')
+    values = {tool_name(t): copy.deepcopy(settings(t)) for t in by_name.values()}
+    # ReplaceClip updates Resolve's generated media cache. The referenced native
+    # MediaID and the independent media-pool readback remain mandatory above.
+    cache = values['HotionHarnessMedia'].get('CustomData', {})
+    cache.pop('MediaProps', None)
+    cache.pop('MEDIA_ID', None)
+    for name in ('HotionHarnessBackground', 'HotionHarnessMedia'):
+        time_keys = TIME_INPUTS if name == 'HotionHarnessMedia' else TIME_INPUTS[:2]
+        for key in time_keys:
+            value = values[name].get('Inputs', {}).pop(key, None)
+            if value and set(value) - {'__ctor', '__flags', 'Value'}:
+                raise ValueError('native generator has an animated or expressed time mapping')
+    child = values['MHBridge'].get('Tools', {}).get('HotionHarnessBackground', {})
+    for key in TIME_INPUTS[:2]:
+        child.get('Inputs', {}).pop(key, None)
+    return signature(stable(values))
+
+
+def read_entry(item, media_index):
+    try:
+        if item.GetMediaPoolItem() or item.GetFusionCompCount() != 1:
+            return None
+        comp = item.GetFusionCompByIndex(1)
+        receipt = stable(comp.GetData(DATA_KEY))
+        if not isinstance(receipt, dict) or receipt.get('schemaVersion') != 1:
+            return None
+        identity = receipt['identity']
+        media = media_index.get(identity['mediaPoolItemId'])
+        if not media:
+            return None
+        link = json.loads((media.GetThirdPartyMetadata() or {}).get('motionharness.bridge', 'null'))
+        if not isinstance(link, dict) or any(link.get(key) != identity[key] for key in ('sourceId', 'bindingId')):
+            return None
+        current = graph(comp, identity, media)
+        if current != receipt.get('graphFingerprint'):
+            return None
+        image = comp.FindTool('HotionHarnessMedia')
+        props, attrs = media.GetClipProperty(), comp.GetAttrs()
+        width, height = (int(v.strip()) for v in props['Resolution'].lower().split('x'))
+        fmt = comp.GetPrefs('Comp.FrameFormat')
+        if (fmt['Width'] != width or fmt['Height'] != height or abs(fmt['Rate'] - float(props['FPS'])) > 0.0001
+                or any(fmt[key] != 3 for key in ('DepthFull', 'DepthPreview', 'DepthInteractive'))
+                or fmt['AspectX'] != 1 or fmt['AspectY'] != 1):
+            return None
+        left, right = attrs['COMPN_GlobalStart'], attrs['COMPN_GlobalEnd'] + 1
+        a, b = image.GetInput('GlobalIn'), image.GetInput('GlobalOut')
+        if (a != image.GetInput('ClipTimeStart') or b != image.GetInput('ClipTimeEnd')
+                or not 0 <= a <= left < right <= b + 1 <= int(props['Frames'])
+                or left != item.GetLeftOffset() or right - left != item.GetEnd() - item.GetStart()):
+            return None
+        return {**receipt, 'graphFingerprint': current}
+    except (AttributeError, TypeError, KeyError, ValueError, RuntimeError):
+        return None
+
+
+def refresh_media(item, media):
+    """Refresh only our MediaIn reference, never the controller/macro."""
+    comp = item.GetFusionCompByIndex(1)
+    image = comp.FindTool('HotionHarnessMedia')
+    mapping = {key: image.GetInput(key) for key in TIME_INPUTS}
+    loop = image.GetInput('Loop')
+    image.SetInput('MediaID', '')
+    image.SetInput('MediaID', media.GetMediaId())
+    # Rebinding also restores Resolve's one-frame Loop default. Restore the
+    # proved loop state before restoring its range.
+    image.SetInput('Loop', loop)
+    for key, value in mapping.items():
+        image.SetInput(key, value)