davinci-resolve-mcp 2.78.0 → 2.79.0

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.78.0"
+VERSION = "2.79.0"
 
 import base64
 import os
@@ -50,6 +50,7 @@ from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
     color_page_for_thumbnails as _color_page_for_thumbnails,
+    edit_page_for_timeline_edits as _edit_page_for_timeline_edits,
     open_page_serialized as _open_page_serialized,
     page_lock as _page_lock,
 )
@@ -3918,12 +3919,31 @@ def _timeline_items_presence(tl, items):
     return "absent"
 
 
-def _timeline_delete_clips_verified(tl, items, ripple):
-    """Timeline.DeleteClips with readback-and-retry.
+def _timeline_delete_clips_verified(tl, items, ripple, *, resolve=None):
+    """Timeline.DeleteClips with a page guard and readback-and-retry.
 
-    api_truth 'Timeline.DeleteClips (flaky first attempt)': the call can
-    return False while every item is still present, and an identical retry
-    then succeeds. On a False, read the tracks back:
+    api_truth 'Timeline.DeleteClips (requires the Edit page; flaky first
+    attempt)' records two distinct failures behind this one call.
+
+    Wrong page (deterministic): with the UI on some pages (verified:
+    Fairlight) the call returns False and deletes nothing, retries included —
+    retrying cannot help. When a `resolve` handle is supplied, the guard
+    switches to the Edit page for the call and restores the caller's page
+    after. Guard failures are swallowed: the delete attempt itself stays the
+    source of truth. `resolve` is an explicit parameter, not an internal
+    get_resolve(), so offline tests calling this helper directly can never
+    touch a live Resolve UI.
+
+    The guard is page_lock's edit_page_for_timeline_edits, not a local
+    OpenPage pair, because the switch has to be serialized against every other
+    page-switching operation (thumbnail capture takes the Color page the same
+    way). Unlocked, a concurrent switch lands this delete on some other page —
+    reintroducing the very failure the guard prevents. Callers deleting in a
+    loop should hold that guard around the loop; nesting it here is free.
+
+    Flaky first attempt: the call can return False while every item is still
+    present, and an identical retry then succeeds. On a False, read the
+    tracks back:
 
       absent  -> the delete landed despite the False; report success.
       present -> retry the identical call once, then read back again.
@@ -3938,14 +3958,20 @@ def _timeline_delete_clips_verified(tl, items, ripple):
     handles to already-deleted items included. That could not be made to
     misbehave against a fake; it is recorded, not resolved.
     """
-    if bool(tl.DeleteClips(items, ripple)):
-        return True
-    presence = _timeline_items_presence(tl, items)
-    if presence != "present":
-        return presence == "absent"
-    if bool(tl.DeleteClips(items, ripple)):
-        return True
-    return _timeline_items_presence(tl, items) == "absent"
+    def _delete_with_readback():
+        if bool(tl.DeleteClips(items, ripple)):
+            return True
+        presence = _timeline_items_presence(tl, items)
+        if presence != "present":
+            return presence == "absent"
+        if bool(tl.DeleteClips(items, ripple)):
+            return True
+        return _timeline_items_presence(tl, items) == "absent"
+
+    if resolve is None:
+        return _delete_with_readback()
+    with _edit_page_for_timeline_edits(resolve):
+        return _delete_with_readback()
 
 
 def _timeline_items_by_ids(tl, ids, track_types=("video", "audio", "subtitle")):
@@ -4110,7 +4136,7 @@ def _append_and_recover_timeline_item(
     return result, duplicate_item, None
 
 
-def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_sources: bool = False):
+def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_sources: bool = False, resolve=None):
     ids = p.get("clip_ids") or p.get("ids")
     selected = bool(p.get("selected", False))
     if ids is not None and not isinstance(ids, list):
@@ -4321,7 +4347,7 @@ def _timeline_duplicate_clips_impl(proj, tl, p: Dict[str, Any], *, delete_source
                 seen_delete_ids.add(item_id)
         if delete_items:
             try:
-                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)))
+                out["deleted_sources"] = _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)), resolve=resolve)
                 out["deleted_source_ids"] = _timeline_item_ids(delete_items)
             except Exception as exc:
                 out["deleted_sources"] = False
@@ -4399,7 +4425,7 @@ def _collect_timeline_items_in_range(tl, p: Dict[str, Any]):
     return start, end, items, None
 
 
-def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool = False):
+def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool = False, resolve=None):
     start, end, items, err = _collect_timeline_items_in_range(tl, p)
     if err:
         return err
@@ -4436,7 +4462,7 @@ def _timeline_copy_range_impl(proj, tl, p: Dict[str, Any], *, overwrite: bool =
                     if existing_start < dest_end and existing_end > dest_start:
                         delete_targets.append(existing)
         if delete_targets:
-            deleted = _timeline_delete_clips_verified(tl, delete_targets, False)
+            deleted = _timeline_delete_clips_verified(tl, delete_targets, False, resolve=resolve)
 
     results = []
     for track_type, source_track, item, overlap_start, overlap_end in items:
@@ -4499,7 +4525,7 @@ def _apply_cuts_skip_reason(cut):
     return None
 
 
-def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
+def _timeline_lift_range_impl(tl, p: Dict[str, Any], *, resolve=None):
     start, end, items, err = _collect_timeline_items_in_range(tl, p)
     if err:
         return err
@@ -4529,7 +4555,7 @@ def _timeline_lift_range_impl(tl, p: Dict[str, Any]):
         return {"success": True, "deleted": 0, "range": {"start": start, "end": end}}
     deleted_ids = _timeline_item_ids(delete_items)
     return {
-        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False))),
+        "success": _timeline_delete_clips_verified(tl, delete_items, bool(p.get("ripple", False)), resolve=resolve),
         "deleted": len(delete_items),
         "deleted_ids": deleted_ids,
         "range": {"start": start, "end": end},
@@ -5973,7 +5999,10 @@ _PRPROJ_REFUSAL = (
     "advanced MCP — editorial.list_sequences / editorial.parse_interchange (format 'prproj'); "
     "(2) convert it to an importable interchange — editorial.convert_to_interchange "
     "(target 'otio'|'edl'|'drt') — then import that here with import_timeline_checked. "
-    "Editorial timing/cuts/transitions/speed carry over; per-clip effects/Lumetri color do not. "
+    "Editorial timing/cuts/transitions carry over; per-clip effects/Lumetri color do not. "
+    "Speed/reverse carry on 'otio' and 'edl' ONLY — the DRT clip schema has no per-clip "
+    "speed field, so 'drt' flattens every retime to 100% forward and reports them in "
+    "`flattened`. Prefer 'otio' or 'edl' for a cut that carries retimes. "
     "Alternatively export FCP7 XML / AAF / FCPXML from Premiere and conform that."
 )
 
@@ -5982,6 +6011,12 @@ _PRPROJ_REFUSAL = (
 # pool after import, not by rewriting the file.
 _BINARY_INTERCHANGE_EXTS = {".aaf"}
 
+# Interchange that is not XML at all. `.otio` is JSON, so the sanitize/relink pass —
+# which parses the file as XML and rewrites <pathurl> elements — cannot run on it, and
+# the missing-media / generator-clip advice it exists to give is not the diagnosis for
+# an .otio that fails to import.
+_JSON_INTERCHANGE_EXTS = {".otio"}
+
 
 def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     path = p.get("path")
@@ -5992,12 +6027,50 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     ext = os.path.splitext(path)[1].lower()
     if ext == ".prproj":
         return _err(_PRPROJ_REFUSAL, category="invalid_input")
+    # ImportTimelineFromFile silently no-ops on the never-saved default project: it returns
+    # nothing, creates no timeline, and reports no cause. The generic "Resolve created no
+    # timeline" error that came back instead sent people to source-clip resolution and
+    # sanitize_media — the wrong road entirely, because the file is fine.
+    #
+    # This is the last unrecorded member of a family the repo already documents: SaveProject
+    # returns False here (and blocks forever headless), CreateProject fails against a dirty
+    # untitled project, and DeleteProject's workaround warns against leaving the session on
+    # this fallback. Refusing early is what makes the cause visible.
+    #
+    # The refusal is HARD — no override flag. An override would reintroduce exactly the
+    # silent no-op this exists to kill, since the call cannot succeed either way.
+    #
+    # Resolve exposes no "is this project unsaved" predicate (no IsModified / IsSaved), so
+    # the test is the literal fallback name. Known hole, stated rather than hidden: a
+    # localized Resolve may not name it "Untitled Project", and this guard will miss it —
+    # such a session gets the old generic error, not a wrong answer.
+    from src.utils.project_cleanup import UNSAVED_DEFAULT_PROJECT
+    try:
+        _current_name = proj.GetName()
+    except Exception:
+        _current_name = None
+    if _current_name == UNSAVED_DEFAULT_PROJECT:
+        return _err(
+            f"Cannot import a timeline into the never-saved default project "
+            f"('{UNSAVED_DEFAULT_PROJECT}') — Resolve accepts the call and creates no "
+            f"timeline, with no error naming the cause.",
+            category="invalid_input",
+            remediation=(
+                "The project state is the problem, not the file. Save this project under a "
+                "name, or load an existing named project (project_manager.load), then retry "
+                "the import unchanged."
+            ),
+        )
     # AAF (and any binary interchange) is read natively by Resolve. The XML
     # sanitize/relink path parses the file as text, so it must be SKIPPED for AAF
     # even when sanitize_media / relink_search_roots is passed; fuzzy XML relink is
     # N/A (media links through the media pool). We still detect the created
     # (possibly offline) timeline via the before/after id diff.
     is_binary = ext in _BINARY_INTERCHANGE_EXTS
+    # .otio is JSON. The sanitize/relink pass parses the file as XML, so it cannot run here
+    # any more than it can on an AAF — and its advice (missing media, generator clips) is
+    # not the diagnosis for an .otio that fails to import.
+    is_json = ext in _JSON_INTERCHANGE_EXTS
     # sanitize_media (alias: relink_media) rewrites the XML to drop clipitems that
     # reference missing media or are generators (slug/solid w/ no pathurl) — both
     # abort Resolve's scripting-API import and leave the timeline fully offline.
@@ -6017,7 +6090,13 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             "relinks via the media pool. Imported the file as-is; pass relink_search_roots to "
             "auto-relink after import."
         )
-    sanitize = sanitize_requested and not is_binary
+    elif is_json and (sanitize_requested or _binary_has_roots):
+        binary_relink_note = (
+            f"sanitize_media / XML path-rewrite relink are N/A for {ext} (JSON, not XML) — "
+            "imported as-is. Media links by the target_url recorded in the file; relink via "
+            "the media pool afterward (see `relink`)."
+        )
+    sanitize = sanitize_requested and not is_binary and not is_json
     if not sanitize and p.get("require_temp_path", True) and not _render_temp_path_ok(path):
         return _err(
             "path must be under the system temp directory unless require_temp_path=False",
@@ -6114,6 +6193,26 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
                     "Otherwise verify it exports/opens in Resolve directly, or convert to "
                     "FCP7 XML / FCPXML upstream and import that."
                 )
+            elif is_json:
+                # Measured on 19.1.3: Resolve DOES import OTIO through the scripting API —
+                # its own EXPORT_OTIO output re-imports cleanly. What it refuses is a
+                # document that is valid OTIO but not Resolve-shaped, and the shape it cares
+                # about most is the source frame ORIGIN: a clip's source_range must sit
+                # inside the media's real timecode range, so 0-based source offsets against
+                # media that starts at 01:00:00:00 produce no timeline at all. Missing media
+                # and sanitize_media are not the diagnosis here and pointing at them wastes
+                # the caller's time on a file whose media is online.
+                remediation = (
+                    f"Resolve created no timeline from this {ext}. This is usually the "
+                    "document's shape, not its media: Resolve expects Clip.2 with a "
+                    "media_references map, an available_range on each reference, and "
+                    "source_range frames expressed against the media's own timecode origin "
+                    "(0-based source offsets fail when the media does not start at "
+                    "00:00:00:00). Author it with editorial.convert_to_interchange "
+                    "(target 'otio'), supplying each event's media start timecode, and check "
+                    "the returned mediaOriginAssumed list. To compare against a known-good "
+                    "file, export any timeline with timeline.export EXPORT_OTIO."
+                )
             elif sanitize:
                 remediation = None
             else:
@@ -6154,6 +6253,9 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             if is_binary:
                 msg += (" Relink via the media pool (right-click → Relink Clips) or point Resolve "
                         "at the media roots — AAF media links there, not by rewriting the file.")
+            elif is_json:
+                msg += (" Relink via the media pool — .otio is JSON, so sanitize_media cannot "
+                        "rewrite its paths; check each clip's target_url instead.")
             elif not sanitize:
                 msg += (" Retry with sanitize_media=True to drop missing-media/generator "
                         "clips so the remaining media links automatically.")
@@ -20499,7 +20601,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             "track_indices": [target_track],
             "allow_partial_item_delete": True,
             "ripple": False,
-        })
+        }, resolve=_r)
         if not lift.get("success"):
             return {"success": False, "error": f"lift failed: {lift.get('error')}", "lift": lift}
         audio_lift = None
@@ -20511,7 +20613,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 "track_indices": linked_audio_indices,
                 "allow_partial_item_delete": True,
                 "ripple": False,
-            })
+            }, resolve=_r)
             if not audio_lift.get("success"):
                 return {
                     "success": False,
@@ -21005,7 +21107,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
             blocked = _consume_confirm_token(action="timeline.delete_clips_ripple", params=p)
             if blocked:
                 return blocked
-        return {"success": _timeline_delete_clips_verified(tl, found, ripple)}
+        return {"success": _timeline_delete_clips_verified(tl, found, ripple, resolve=get_resolve())}
     elif action == "set_clips_linked":
         ids_set = set(p["clip_ids"])
         found = []
@@ -21023,13 +21125,13 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     elif action == "copy_clips":
         return _timeline_duplicate_clips_impl(proj, tl, p)
     elif action == "move_clips":
-        return _timeline_duplicate_clips_impl(proj, tl, p, delete_sources=True)
+        return _timeline_duplicate_clips_impl(proj, tl, p, delete_sources=True, resolve=get_resolve())
     elif action in {"copy_range", "duplicate_range"}:
         return _timeline_copy_range_impl(proj, tl, p)
     elif action == "overwrite_range":
-        return _timeline_copy_range_impl(proj, tl, p, overwrite=True)
+        return _timeline_copy_range_impl(proj, tl, p, overwrite=True, resolve=get_resolve())
     elif action == "lift_range":
-        return _timeline_lift_range_impl(tl, p)
+        return _timeline_lift_range_impl(tl, p, resolve=get_resolve())
     elif action == "story_spine_report":
         return _timeline_story_spine_report(tl, p)
     elif action == "create_variant_from_ranges":
@@ -21184,15 +21286,21 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
 
         allow_partial = bool(p.get("allow_partial_item_delete", True))
         results = []
-        for c in applicable:
-            sp = c["span"]
-            res = _timeline_lift_range_impl(tl, {
-                "start_frame": sp["start"],
-                "end_frame": sp["end"],
-                "ripple": c["action"] == "ripple_delete",
-                "allow_partial_item_delete": allow_partial,
-            })
-            results.append({"action": c["action"], "span": sp, "result": res})
+        resolve_obj = get_resolve()
+        # Hold the Edit page once for the whole run. The per-delete guard nests
+        # harmlessly inside (it finds the page already on edit), but without this
+        # each cut would switch and restore on its own: from Fairlight, N cuts
+        # cost 2N page flips instead of 2.
+        with _edit_page_for_timeline_edits(resolve_obj):
+            for c in applicable:
+                sp = c["span"]
+                res = _timeline_lift_range_impl(tl, {
+                    "start_frame": sp["start"],
+                    "end_frame": sp["end"],
+                    "ripple": c["action"] == "ripple_delete",
+                    "allow_partial_item_delete": allow_partial,
+                }, resolve=resolve_obj)
+                results.append({"action": c["action"], "span": sp, "result": res})
         applied = sum(1 for r in results
                       if isinstance(r["result"], dict) and r["result"].get("success"))
         return {"success": True, "applied": applied, "total": len(applicable),

package/src/utils/api_truth.py

@@ -181,7 +181,14 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "five consecutive imports with no media duplicated. Use DRT "
                        "for one-shot hand-offs only. For OTIO, pass "
                        "importSourceClips=True with a sourceClipsPath. See "
-                       "docs/guides/headless-edit-loop.md.",
+                       "docs/guides/headless-edit-loop.md. For a consolidated Avid "
+                       "AAF specifically, do NOT expect this call (or Reconform "
+                       "from Bins, or the UI's 'Link to source camera files') to "
+                       "conform it to camera originals — all three were measured "
+                       "against a real turnover and all three fail, the UI option "
+                       "linking 878 of 882 items with only 144 correct while "
+                       "rendering as a fully conformed timeline. See "
+                       "docs/guides/conforming-an-avid-aaf.md.",
         "tags": ["timeline", "import", "interchange", "silent-failure", "conform"],
         "submit": "bug",
     },
@@ -274,11 +281,119 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "— naming nothing actionable — when the Media Pool's CURRENT "
                    "folder is not the folder holding the clips, even though every "
                    "clip_id passed is valid and resolvable. Reported against "
-                   "Resolve Studio in PR #99.",
+                   "Resolve Studio in PR #99. "
+                   "SEPARATELY, its clipInfo HAS NO TRACK FIELD: there is no way "
+                   "to say which video or audio track a clip should land on, so "
+                   "this call cannot build a multi-track timeline. The asymmetry "
+                   "is the surprise — MediaPool.AppendToTimeline's clipInfo DOES "
+                   "take `trackIndex`, so the two clipInfo shapes are not the same "
+                   "shape, and code that works against one silently loses track "
+                   "assignment against the other.",
         "recommended": "Call MediaPool.SetCurrentFolder() to the clips' bin "
                        "before creating the timeline (media_pool "
-                       "set_current_folder). Valid ids are not sufficient.",
-        "tags": ["media-pool", "timeline", "unhelpful-error"],
+                       "set_current_folder). Valid ids are not sufficient. "
+                       "For multi-track placement do not use this call at all: "
+                       "create an EMPTY timeline (media_pool create_timeline), add "
+                       "the tracks you need (timeline add_track), then place each "
+                       "clip with MediaPool.AppendToTimeline passing clipInfo "
+                       "`trackIndex` (media_pool append_to_timeline with "
+                       "track_index).",
+        "tags": ["media-pool", "timeline", "unhelpful-error", "missing-method", "conform"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline (overlapping records — earlier item wins)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, "
+                     "trackIndex, mediaType}]) -> [TimelineItem]",
+        "reality": "AppendToTimeline does NOT overwrite an overlapping record. "
+                   "When two clipInfos resolve to record ranges that overlap on "
+                   "the same track, the EARLIER item wins and the later append is "
+                   "dropped — measured while placing a real turnover. There is no "
+                   "overwrite edit mode to reach for either: AppendToTimeline is "
+                   "the only programmatic placement the API offers, so a consumer "
+                   "that assumes overwrite semantics gets a timeline that is "
+                   "silently SHORT by the number of colliding events, with no "
+                   "error to say which ones lost.",
+        "recommended": "Resolve collisions BEFORE appending — the API will not do "
+                       "it for you. Cap each event's placed duration at the next "
+                       "event's recordFrame on the same track, or place the "
+                       "colliding events on separate tracks. Verify by comparing "
+                       "the timeline's item count against the number of clipInfos "
+                       "you sent, per track, and finish with detect_gaps_overlaps; "
+                       "a count that matches is the only evidence nothing was "
+                       "dropped.",
+        "tags": ["timeline", "edit", "silent-failure", "conform", "media-pool"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline (errored-chunk placements are not durable across a save)",
+        "object": "MediaPool",
+        "signature": "([clipInfos]) -> [TimelineItem]",
+        "reality": "Placements made by an append call whose response ERRORED are "
+                   "not durable: they appear in the timeline, every in-session "
+                   "read agrees they are there, and THE SAVE DISCARDS THEM. "
+                   "Measured on a real turnover — a timeline verified at 573 items "
+                   "immediately after construction held 500 after the save, a loss "
+                   "of exactly one errored append chunk's worth. The API reported "
+                   "the failure, the items appeared anyway, and nothing between "
+                   "construction and the save disagreed with the wrong number. "
+                   "This is the dangerous shape: the witness is derived from the "
+                   "same unsaved state as the thing it is checking, so it cannot "
+                   "contradict it. Only a POST-SAVE read can.",
+        "recommended": "Treat the save as the verification boundary, not the end "
+                       "of the job. Save, RE-READ the timeline's item count from "
+                       "the saved project, and re-append whatever is missing "
+                       "(bounded — two rounds is enough in practice); only then "
+                       "report success. A timeline that is still short after that, "
+                       "or that will not save, is a FAILURE — report it as one "
+                       "rather than returning the in-session count. Never claim a "
+                       "construction succeeded on a pre-save read alone, and treat "
+                       "any errored append chunk as suspect even when its items "
+                       "are visibly present.",
+        "tags": ["timeline", "edit", "silent-failure", "data-loss", "conform",
+                 "unreliable-return", "media-pool"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile (.otio document shape)",
+        "object": "MediaPool",
+        "signature": "(filePath, {importOptions}) -> Timeline",
+        "reality": "Resolve DOES import OTIO through the scripting API — but only "
+                   "a Resolve-shaped document, and it rejects anything else by "
+                   "creating NO timeline and returning None, with no error naming "
+                   "a cause. Established on 19.1.3.7 by exporting a timeline with "
+                   "Timeline.Export(..., EXPORT_OTIO) and feeding Resolve's own "
+                   "file straight back: it re-imports cleanly (3 items, 3 linked), "
+                   "while a valid hand-authored OTIO of the same cut, same project, "
+                   "same session, same three online media files, produced nothing. "
+                   "So a refusal is a SHAPE problem, not a media problem. "
+                   "The requirement that actually decides it is the SOURCE FRAME "
+                   "ORIGIN: a clip's source_range must be expressed against the "
+                   "media's own timecode range. Media carrying an embedded start "
+                   "TC of 01:00:00:00 gets an available_range starting at frame "
+                   "86400, and the clip's source_range must start there too — "
+                   "0-based source offsets, the natural reading of 'source in "
+                   "point', put the clip outside the media's real range and the "
+                   "import dies. Isolated by bisection: 0-based fails and absolute "
+                   "succeeds whether or not the stack/track source_range is null. "
+                   "Resolve also writes (and expects) Clip.2 with a "
+                   "`media_references` MAP plus `active_media_reference_key`, not "
+                   "Clip.1 with a singular `media_reference`; an `available_range` "
+                   "on each reference; a BARE path in `target_url`, not a file:// "
+                   "URL; `enabled` and `metadata` throughout; `global_start_time`; "
+                   "and track names in its own form ('Video 1').",
+        "recommended": "Author OTIO for Resolve by mirroring what Resolve itself "
+                       "exports, and give every event its media timecode origin. "
+                       "editorial.convert_to_interchange (target 'otio') does this "
+                       "and reports any event whose origin had to be assumed in "
+                       "`mediaOriginAssumed` — a non-empty list means the file will "
+                       "only import if that media really starts at 00:00:00:00. To "
+                       "debug a refusal, export any timeline with EXPORT_OTIO and "
+                       "diff your document against it; do NOT chase missing media "
+                       "or reach for sanitize_media, which cannot even parse a "
+                       ".otio (it is JSON, not XML).",
+        "tags": ["timeline", "import", "interchange", "otio", "silent-failure", "conform"],
         "submit": "bug",
     },
     {
@@ -554,10 +669,62 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "against the documented SetProperty key list AND by live "
                    "mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'"
                    "|'RetimeSpeed'|'ClipSpeed', 50) all return False, while "
-                   "SetProperty('RetimeProcess', 1) returns True.",
+                   "SetProperty('RetimeProcess', 1) returns True. "
+                   "THE READ SIDE IS AS DEAD AS THE WRITE SIDE, which is easy to "
+                   "miss: re-measured on Studio 19.1.3.7 against a placed item, "
+                   "GetProperty('Speed'), GetProperty('PlaybackSpeed'), "
+                   "GetProperty('RetimeSpeed') and GetProperty('ClipSpeed') ALL "
+                   "return None, and the keyless GetProperty() dict (26 keys on "
+                   "that item) carries no speed value at all — its only retime key "
+                   "is RetimeProcess, which is quality, not ratio. SetProperty("
+                   "'Speed', 1.75) returned False on 19.1.3.7 too, so the write "
+                   "refusal is not specific to 21.0.0. Note the 21.0.0 stamp above "
+                   "covers the SetProperty measurements only. "
+                   "THE INTERCHANGE ROUTE IS ALSO CLOSED — carrying a retime in "
+                   "through FCP7 XML does not work either, measured on 19.1.3 with "
+                   "three real files, clips at 100/200/50% on V1, each variant "
+                   "imported as its own timeline: (a) the importer IGNORES the "
+                   "scalar Time Remap speed filter and the clips arrive at 100%; "
+                   "(b) `graphdict` is dead in FOUR separate shapes — the full "
+                   "Premiere form (variablespeed=0 + speed + reverse=FALSE + "
+                   "frameblending + 4-keyframe graphdict + FCPCurve), graphdict "
+                   "alone with no <speed> param, a 100% REVERSE (reverse=TRUE plus "
+                   "a descending graphdict, the exact shape a real Premiere export "
+                   "carries), and variablespeed=1 + graphdict — 0 of 2 retimes "
+                   "landed in every one; (c) `reverse` did not survive either; "
+                   "(d) any <in>/<pproTicksIn> inconsistency is silently REJECTED, "
+                   "measured in BOTH orientations. The emitted maps were verified "
+                   "constant-slope against real Premiere exports before importing, "
+                   "and every imported clip came back consuming exactly its record "
+                   "span of source (a 200% clip emitted in 200 / out 296 was "
+                   "clamped to out 248 — 48 source frames over a 48-frame record "
+                   "span). Placement is NOT the problem: the same route imported "
+                   "573 clips with 572 of 573 matching by track and record position "
+                   "with source frames exact, and the importer BUILT a 59-frame "
+                   "dissolve. The retime gap is specific, not general. "
+                   "TRAP: Resolve's own FCP7 export cannot witness a speed. It "
+                   "writes a DEGENERATE Time Remap on every clip — `speed` value 0 "
+                   "(not 100) and a graphdict whose keyframe `value`s are all 0 "
+                   "while its `when`s carry the clip's source in/out — so anyone "
+                   "verifying a retime by round-tripping through EXPORT_FCP_7_XML "
+                   "is reading furniture, and the identity Time Remap blocks "
+                   "present on every clip are what make the route look like it "
+                   "should work.",
         "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
-                       "equivalent exists.",
-        "tags": ["missing-method", "timeline", "retime", "speed"],
+                       "equivalent exists, and no interchange route carries one "
+                       "in. Do NOT read speed back with GetProperty (None) or "
+                       "witness it via EXPORT_FCP_7_XML (degenerate). Read the "
+                       "clip's GEOMETRY instead — GetLeftOffset / GetRightOffset, "
+                       "which on the 200% clip read 200 / 248 and agreed with the "
+                       "export's in/out. Caveat worth stating: no positive control "
+                       "has been run — no clip KNOWN to be retimed has been read "
+                       "back through those two witnesses, because there is no "
+                       "scripting path to create one. So the geometry witness is "
+                       "the best available, not a proven one. Either way the "
+                       "interchange route is rejected: no retime was built, and "
+                       "none could have been verified.",
+        "tags": ["missing-method", "timeline", "retime", "speed", "interchange",
+                 "silent-failure", "unreliable-return"],
         "submit": "missing",
     },
     {
@@ -951,30 +1118,53 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["timeline", "edit", "off-by-one", "readback"],
     },
     {
-        "symbol": "Timeline.DeleteClips (flaky first attempt)",
+        "symbol": "Timeline.DeleteClips (requires the Edit page; flaky first attempt)",
         "object": "Timeline",
         "signature": "([TimelineItem], ripple) -> bool",
-        "reality": "Can return False on the first call even when every item in "
-                   "the list is a valid, present TimelineItem; an identical "
-                   "immediate retry succeeds. Observed once, on Studio 21.0 "
-                   "during a cut-video edit session (items confirmed still "
-                   "present after the False, deleted cleanly on retry). Cause "
-                   "unknown — do NOT read this as the ProjectManager."
-                   "DeleteProject shape: that one has an identified mechanism "
-                   "(the project being, or recently having been, current) that "
-                   "retrying does not clear, whereas a single retry cleared "
-                   "this in the one instance seen. One observation is not a "
-                   "mechanism; if a retry is ever seen to fail repeatedly here, "
-                   "this entry needs revisiting.",
-        "recommended": "Treat a False return as advisory: re-list the track and "
-                       "check whether the items are actually gone; if still "
-                       "present, retry the identical call once before failing. "
-                       "A readback that raised, enumerated nothing, or covered "
-                       "items whose unique ID cannot be read is UNKNOWN, not "
-                       "gone — never report an unverifiable delete as success, "
-                       "and do not spend a second destructive call on an "
-                       "outcome you equally cannot read.",
-        "tags": ["unreliable-return", "flaky", "timeline", "edit"],
+        "reality": "Two distinct failures share this call.\n"
+                   "\n"
+                   "  **1. Wrong page (deterministic, has a mechanism).** With "
+                   "the UI on the Fairlight page, DeleteClips returns False and "
+                   "deletes nothing, no matter how many times it is retried. "
+                   "Verified 2026-08-04 on Studio 21.0: three identical retries "
+                   "against 132 valid, unlocked, present TimelineItems all "
+                   "returned False with all 132 still on the track; a single "
+                   "`Resolve.OpenPage(\"edit\")` followed by the same call "
+                   "returned True and left 0 items. Track lock and enable state "
+                   "were confirmed clear before and after, so this is a page "
+                   "gate, not a lock. This is the case the previous entry's "
+                   "falsification condition anticipated — a retry seen to fail "
+                   "repeatedly — and revisiting it found the mechanism.\n"
+                   "\n"
+                   "  **2. Flaky first attempt (one observation, no "
+                   "mechanism).** Independently of the page, the call has been "
+                   "seen once to return False with every item still present, "
+                   "where an identical immediate retry succeeded (Studio 21.0, "
+                   "cut-video edit session). Whether the UI was on the Edit "
+                   "page at the time was not recorded, so it cannot be ruled "
+                   "in or out as failure 1 in disguise. Do NOT read this as "
+                   "the ProjectManager.DeleteProject shape: that one has an "
+                   "identified mechanism (the project being, or recently "
+                   "having been, current) that retrying does not clear. One "
+                   "observation is still not a mechanism; if an immediate "
+                   "retry is ever seen to fail repeatedly while the UI is "
+                   "confirmed on the Edit page, this sub-entry needs "
+                   "revisiting.",
+        "recommended": "Open the Edit page first (`Resolve.OpenPage(\"edit\")`) "
+                       "— a caller that deletes clips from a script must not "
+                       "assume the user left the UI on Edit, and a Fairlight or "
+                       "Color session is a completely ordinary place for them "
+                       "to be. Then treat a False return as advisory: re-list "
+                       "the track and check whether the items are actually "
+                       "gone; if still present, retry the identical call once "
+                       "before failing. A readback that raised, enumerated "
+                       "nothing, or covered items whose unique ID cannot be "
+                       "read is UNKNOWN, not gone — never report an "
+                       "unverifiable delete as success, and do not spend a "
+                       "second destructive call on an outcome you equally "
+                       "cannot read.",
+        "tags": ["unreliable-return", "flaky", "silent-failure",
+                 "page-dependent", "timeline", "edit"],
         "submit": "bug",
         "mitigation": ["_timeline_delete_clips_verified", "_timeline_items_presence"],
     },