@hybridlabor-api/aos 4.4.1 → 4.4.2-beta.0

package/mcps/davinci-resolve-mcp/src/utils/edit_engine.py

@@ -1,737 +0,0 @@
-"""Edit-engine planning layer (Phase E of the analysis program).
-
-Pure evidence + planning: this module reads the DB-canonical analysis store
-and produces dry-run plans with a per-decision rationale. It never imports
-or touches Resolve — execution (timeline creation, lifts, swaps) lives in
-server.py behind the confirm-token gate and the destructive hook, which
-supplies versioning + brain_edits for free.
-
-Plans persist under ``memory/edit_plans/<plan_id>.json`` with a content
-fingerprint; execution revalidates the fingerprint so a stale plan cannot
-run against a changed project.
-
-Loops:
-- E1 selects  — rank shots by select potential / best moments (deep-tier
-  subjective rows, with description fallbacks), story-spine order, build a
-  NEW selects timeline (additive; failure costs nothing).
-- E2 tighten  — find dead air (transcript gaps within each timeline item's
-  source range) and propose lifts toward a stated goal, applied to a
-  DUPLICATE of the timeline, never the original.
-- E3 swap     — rank alternate shots for a timeline item via the
-  embeddings similarity index.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import time
-import uuid
-from typing import Any, Dict, List, Optional, Sequence, Tuple
-
-from src.utils import analysis_memory, analysis_store, timeline_brain_db
-
-PLAN_DIR_NAME = "edit_plans"
-DEFAULT_HANDLE_SECONDS = 0.25
-DEFAULT_MIN_PAUSE_SECONDS = 1.5
-
-_SELECT_RANK = {"high": 3, "medium": 2, "low": 1}
-
-
-def _now() -> str:
-    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
-
-
-def _plan_dir(project_root: str) -> str:
-    return os.path.join(analysis_memory.memory_dir(project_root), PLAN_DIR_NAME)
-
-
-def _plan_fingerprint(plan: Dict[str, Any]) -> str:
-    body = {k: v for k, v in plan.items() if k not in ("fingerprint", "saved_at")}
-    return hashlib.sha256(json.dumps(body, sort_keys=True, default=str).encode("utf-8")).hexdigest()[:16]
-
-
-def save_plan(project_root: str, plan: Dict[str, Any]) -> Dict[str, Any]:
-    analysis_memory.ensure_memory_structure(project_root)
-    os.makedirs(_plan_dir(project_root), exist_ok=True)
-    plan = dict(plan)
-    plan.setdefault("plan_id", uuid.uuid4().hex[:12])
-    plan["saved_at"] = _now()
-    plan["fingerprint"] = _plan_fingerprint(plan)
-    path = os.path.join(_plan_dir(project_root), f"{plan['plan_id']}.json")
-    tmp = path + ".tmp"
-    with open(tmp, "w", encoding="utf-8") as handle:
-        json.dump(plan, handle, indent=2, default=str)
-    os.replace(tmp, path)
-    return plan
-
-
-def load_plan(project_root: str, plan_id: str) -> Optional[Dict[str, Any]]:
-    path = os.path.join(_plan_dir(project_root), f"{str(plan_id)}.json")
-    try:
-        with open(path, "r", encoding="utf-8") as handle:
-            plan = json.load(handle)
-    except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(plan, dict):
-        return None
-    if plan.get("fingerprint") != _plan_fingerprint(plan):
-        return {"_corrupt": True, "plan_id": plan_id}
-    return plan
-
-
-def list_plans(project_root: str, *, limit: int = 20, include_corrupt: bool = False) -> Dict[str, Any]:
-    """List saved plans, newest first.
-
-    `include_corrupt=True` (panel browser) surfaces fingerprint-mismatched
-    plans as ``{"plan_id", "corrupt": True}`` warning rows instead of hiding
-    them; the default keeps the MCP-action shape unchanged.
-    """
-    directory = _plan_dir(project_root)
-    rows: List[Dict[str, Any]] = []
-    if os.path.isdir(directory):
-        for name in sorted(os.listdir(directory), reverse=True):
-            if not name.endswith(".json"):
-                continue
-            plan = load_plan(project_root, name[:-5])
-            if not plan or plan.get("_corrupt"):
-                if include_corrupt:
-                    rows.append({"plan_id": name[:-5], "corrupt": True})
-                continue
-            rows.append({
-                "plan_id": plan.get("plan_id"),
-                "kind": plan.get("kind"),
-                "saved_at": plan.get("saved_at"),
-                "executed_at": plan.get("executed_at"),
-                "summary": plan.get("summary"),
-            })
-    rows.sort(key=lambda r: str(r.get("saved_at") or ""), reverse=True)
-    return {"success": True, "plans": rows[: max(1, int(limit))]}
-
-
-def mark_plan_executed(project_root: str, plan_id: str, result_summary: Dict[str, Any]) -> None:
-    plan = load_plan(project_root, plan_id)
-    if not plan or plan.get("_corrupt"):
-        return
-    plan["executed_at"] = _now()
-    plan["execution_summary"] = result_summary
-    plan["fingerprint"] = _plan_fingerprint(plan)
-    path = os.path.join(_plan_dir(project_root), f"{plan_id}.json")
-    tmp = path + ".tmp"
-    with open(tmp, "w", encoding="utf-8") as handle:
-        json.dump(plan, handle, indent=2, default=str)
-    os.replace(tmp, path)
-
-
-# ── shared evidence helpers ──────────────────────────────────────────────────
-
-
-def _shot_groups(shot_row: Dict[str, Any]) -> Dict[str, Any]:
-    extra = shot_row.get("extra_json")
-    if not extra:
-        return {}
-    try:
-        groups = json.loads(extra)
-    except (TypeError, ValueError):
-        return {}
-    return groups if isinstance(groups, dict) else {}
-
-
-def _clip_fps(clip_row: Dict[str, Any]) -> float:
-    fps = clip_row.get("fps")
-    try:
-        fps = float(fps)
-    except (TypeError, ValueError):
-        fps = 0.0
-    return fps if fps > 0 else 24.0
-
-
-# ── E1: selects assembly ─────────────────────────────────────────────────────
-
-
-def plan_selects(
-    project_root: str,
-    *,
-    timeline_name: Optional[str] = None,
-    max_duration_seconds: Optional[float] = None,
-    min_select_potential: str = "medium",
-    handle_seconds: float = DEFAULT_HANDLE_SECONDS,
-    max_shots: int = 60,
-) -> Dict[str, Any]:
-    """Rank shots into a selects plan (story-spine order, additive)."""
-    conn = timeline_brain_db.connect(project_root)
-    clips = {str(r["clip_uuid"]): dict(r) for r in conn.execute(
-        "SELECT * FROM clips ORDER BY clip_name COLLATE NOCASE"
-    ).fetchall()}
-    if not clips:
-        return {"success": False, "error": "No analyzed clips in the DB — analyze (or db_ingest) first."}
-    min_rank = _SELECT_RANK.get(str(min_select_potential).lower(), 2)
-
-    candidates: List[Dict[str, Any]] = []
-    clip_order = {uuid_: i for i, uuid_ in enumerate(clips)}
-    for shot_row in conn.execute(
-        "SELECT * FROM shots ORDER BY clip_uuid, shot_index"
-    ).fetchall():
-        shot = dict(shot_row)
-        clip = clips.get(str(shot["clip_uuid"]))
-        if not clip or not clip.get("resolve_clip_id"):
-            continue
-        start = shot.get("time_seconds_start")
-        end = shot.get("time_seconds_end")
-        if start is None or end is None or float(end) - float(start) < 0.4:
-            continue
-        groups = _shot_groups(shot)
-        editorial = groups.get("editorial") if isinstance(groups.get("editorial"), dict) else {}
-        select_potential = str(editorial.get("select_potential") or "").lower()
-        best_moment = editorial.get("best_moment") if isinstance(editorial.get("best_moment"), dict) else None
-        rank = _SELECT_RANK.get(select_potential, 0)
-        evidence: List[str] = []
-        if rank:
-            evidence.append(f"editorial.select_potential={select_potential} (deep vision)")
-        if best_moment:
-            evidence.append(f"best_moment at {best_moment.get('time_seconds')}s: {best_moment.get('why')}")
-        if rank == 0:
-            # Standard-analyzed clips have no deep editorial fields — fall back
-            # to clip-level select potential so E1 works day one.
-            clip_sp = conn.execute(
-                """
-                SELECT value_json FROM subjective_fields
-                WHERE entity_type='clip' AND entity_uuid=? AND superseded_at IS NULL
-                  AND field_path='editorial_classification.select_potential'
-                """,
-                (shot["clip_uuid"],),
-            ).fetchone()
-            if clip_sp:
-                try:
-                    value = str(json.loads(clip_sp["value_json"])).lower()
-                    rank = _SELECT_RANK.get(value, 0)
-                    if rank:
-                        evidence.append(f"clip-level select_potential={value} (no per-shot deep pass yet)")
-                except (TypeError, ValueError):
-                    pass
-        if rank < min_rank:
-            continue
-        candidates.append({
-            "clip_uuid": shot["clip_uuid"],
-            "clip_name": clip.get("clip_name"),
-            "resolve_clip_id": clip.get("resolve_clip_id"),
-            "shot_uuid": shot["shot_uuid"],
-            "shot_index": shot["shot_index"],
-            "time_seconds_start": float(start),
-            "time_seconds_end": float(end),
-            "duration_seconds": round(float(end) - float(start), 3),
-            "fps": _clip_fps(clip),
-            "rank": rank,
-            "description": shot.get("description"),
-            "rationale": "; ".join(evidence) or "shot present in analysis",
-            "_order": (clip_order[str(shot["clip_uuid"])], int(shot["shot_index"])),
-        })
-
-    if not candidates:
-        return {
-            "success": False,
-            "error": (
-                f"No shots at select_potential >= {min_select_potential}. Run a deep pass "
-                "(media_analysis action='deepen') or lower min_select_potential."
-            ),
-        }
-
-    # Highest rank wins the budget; story-spine order for the final sequence.
-    candidates.sort(key=lambda c: (-c["rank"], c["_order"]))
-    chosen: List[Dict[str, Any]] = []
-    total = 0.0
-    for candidate in candidates[: max(1, int(max_shots) * 3)]:
-        duration = candidate["duration_seconds"] + 2 * float(handle_seconds)
-        if max_duration_seconds and total + duration > float(max_duration_seconds) and chosen:
-            continue
-        chosen.append(candidate)
-        total += duration
-        if len(chosen) >= int(max_shots):
-            break
-    chosen.sort(key=lambda c: c["_order"])
-
-    decisions = []
-    clip_infos = []
-    for candidate in chosen:
-        fps = candidate["fps"]
-        clip_row = clips.get(str(candidate["clip_uuid"])) or {}
-        clip_duration = clip_row.get("duration_seconds")
-        src_start = max(0.0, candidate["time_seconds_start"] - float(handle_seconds))
-        src_end = candidate["time_seconds_end"] + float(handle_seconds)
-        if isinstance(clip_duration, (int, float)) and clip_duration:
-            src_end = min(src_end, float(clip_duration))
-        start_frame = int(round(src_start * fps))
-        end_frame = max(start_frame + 1, int(round(src_end * fps)) - 1)
-        decision = {k: v for k, v in candidate.items() if not k.startswith("_")}
-        decision["source_frame_range"] = [start_frame, end_frame]
-        decisions.append(decision)
-        clip_infos.append({
-            "clip_id": candidate["resolve_clip_id"],
-            "start_frame": start_frame,
-            "end_frame": end_frame,
-        })
-
-    name = timeline_name or f"Selects — {_now()[:10]}"
-    plan = save_plan(project_root, {
-        "kind": "selects",
-        "timeline_name": name,
-        "decisions": decisions,
-        "clip_infos": clip_infos,
-        "estimated_duration_seconds": round(total, 2),
-        "summary": f"{len(decisions)} shots, ~{round(total, 1)}s → new timeline '{name}'",
-        "settings": {
-            "min_select_potential": min_select_potential,
-            "max_duration_seconds": max_duration_seconds,
-            "handle_seconds": handle_seconds,
-        },
-    })
-    return {
-        "success": True,
-        "status": "plan_ready",
-        "plan_id": plan["plan_id"],
-        "kind": "selects",
-        "timeline_name": name,
-        "decision_count": len(decisions),
-        "estimated_duration_seconds": plan["estimated_duration_seconds"],
-        "decisions": decisions,
-        "note": (
-            "Dry-run plan. Execute with edit_engine(action='execute_selects', "
-            "params={plan_id}) — a NEW timeline is created; nothing existing is touched."
-        ),
-    }
-
-
-# ── E2: tighten ──────────────────────────────────────────────────────────────
-
-
-def _speech_intervals(conn, clip_uuid: str) -> List[Tuple[float, float]]:
-    rows = conn.execute(
-        """
-        SELECT start_seconds, end_seconds FROM transcript_segments
-        WHERE clip_uuid = ? AND start_seconds IS NOT NULL AND end_seconds IS NOT NULL
-        ORDER BY start_seconds
-        """,
-        (clip_uuid,),
-    ).fetchall()
-    return [(float(r["start_seconds"]), float(r["end_seconds"])) for r in rows]
-
-
-def _gaps_in_range(
-    intervals: Sequence[Tuple[float, float]],
-    start: float,
-    end: float,
-    *,
-    min_gap: float,
-) -> List[Tuple[float, float]]:
-    """Sub-ranges of [start, end] not covered by any interval, >= min_gap."""
-    gaps: List[Tuple[float, float]] = []
-    cursor = start
-    for s, e in sorted(intervals):
-        if e <= start or s >= end:
-            continue
-        s, e = max(s, start), min(e, end)
-        if s - cursor >= min_gap:
-            gaps.append((cursor, s))
-        cursor = max(cursor, e)
-    if end - cursor >= min_gap:
-        gaps.append((cursor, end))
-    return gaps
-
-
-def plan_tighten(
-    project_root: str,
-    *,
-    items: Sequence[Dict[str, Any]],
-    timeline_name: str,
-    timeline_fps: float,
-    target_ratio: Optional[float] = None,
-    min_pause_seconds: float = DEFAULT_MIN_PAUSE_SECONDS,
-    handle_seconds: float = DEFAULT_HANDLE_SECONDS,
-    include_audio: bool = True,
-) -> Dict[str, Any]:
-    """Propose dead-air lifts for a timeline.
-
-    `items` rows come from the server (Resolve read): each needs
-    {timeline_start_frame, timeline_end_frame, source_start_frame,
-     media_ref (clip id / path / hash), item_name?}. Optionally each row may
-    carry {audio_track_indices: [int, ...]} naming the audio tracks that hold
-    the item's linked audio. Lifts are returned in timeline frames, latest-first
-    ready.
-
-    When ``include_audio`` (the default), each kept video range is mirrored onto
-    matching audio range(s) so the assembled variant carries sound — a
-    speech-driven cut would otherwise come out silent (see #67). Audio is
-    mirrored to the item's detected ``audio_track_indices``; absent that, it
-    falls back to audio track 1, which is where a single linked A/V clip's audio
-    lives.
-    """
-    if not items:
-        return {"success": False, "error": "No timeline items supplied"}
-    fps = float(timeline_fps) if timeline_fps and float(timeline_fps) > 0 else 24.0
-    conn = timeline_brain_db.connect(project_root)
-
-    lifts: List[Dict[str, Any]] = []
-    skipped: List[Dict[str, Any]] = []
-    item_specs: List[Dict[str, Any]] = []  # per usable item: source mapping for keep-range rebuild
-    timeline_total_frames = 0
-    for item_index, item in enumerate(items):
-        try:
-            tl_start = int(item["timeline_start_frame"])
-            tl_end = int(item["timeline_end_frame"])
-            src_start_frame = int(item.get("source_start_frame") or 0)
-        except (KeyError, TypeError, ValueError):
-            skipped.append({"item": item.get("item_name"), "reason": "missing frame fields"})
-            continue
-        timeline_total_frames += max(0, tl_end - tl_start)
-        clip_uuid = analysis_store.resolve_clip_uuid(
-            conn, item.get("media_ref")
-        ) or analysis_store.resolve_clip_uuid(conn, item.get("media_path"))
-        if not clip_uuid:
-            skipped.append({"item": item.get("item_name"), "reason": "no analysis for source media (db_ingest or analyze first)"})
-            item_specs.append({"item_index": item_index, "unanalyzed": True,
-                               "resolve_clip_id": None, "item": item})
-            continue
-        clip_row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
-        clip_fps = _clip_fps(dict(clip_row)) if clip_row else fps
-        src_start_sec = src_start_frame / clip_fps
-        src_end_sec = src_start_sec + (tl_end - tl_start) / fps
-        spec = {
-            "item_index": item_index,
-            "item": item,
-            "clip_uuid": clip_uuid,
-            "clip_fps": clip_fps,
-            "resolve_clip_id": dict(clip_row).get("resolve_clip_id") if clip_row else None,
-            "src_start_sec": src_start_sec,
-            "src_end_sec": src_end_sec,
-        }
-        item_specs.append(spec)
-        speech = _speech_intervals(conn, clip_uuid)
-        if not speech:
-            skipped.append({"item": item.get("item_name"), "reason": "no transcript segments — dead-air evidence unavailable"})
-            continue
-        for gap_start, gap_end in _gaps_in_range(speech, src_start_sec, src_end_sec, min_gap=float(min_pause_seconds)):
-            # Keep handles on both sides of the lift.
-            lift_start_sec = gap_start + float(handle_seconds)
-            lift_end_sec = gap_end - float(handle_seconds)
-            if lift_end_sec - lift_start_sec < 0.2:
-                continue
-            lift_start = tl_start + int(round((lift_start_sec - src_start_sec) * fps))
-            lift_end = tl_start + int(round((lift_end_sec - src_start_sec) * fps))
-            if lift_end <= lift_start:
-                continue
-            lifts.append({
-                "kind": "dead_air",
-                "action": "lift",
-                "timeline_start_frame": lift_start,
-                "timeline_end_frame": lift_end,
-                "duration_seconds": round((lift_end - lift_start) / fps, 3),
-                "item_name": item.get("item_name"),
-                "item_index": item_index,
-                "clip_uuid": clip_uuid,
-                "source_lift_seconds": [round(lift_start_sec, 3), round(lift_end_sec, 3)],
-                "rationale": (
-                    f"No speech from {round(gap_start, 2)}s to {round(gap_end, 2)}s in the source "
-                    f"transcript ({round(gap_end - gap_start, 2)}s pause; handles kept)."
-                ),
-                "evidence": {
-                    "source_gap_seconds": [round(gap_start, 3), round(gap_end, 3)],
-                    "basis": "transcript_segments",
-                },
-            })
-
-    if not lifts:
-        return {
-            "success": False,
-            "error": "No dead-air lifts found",
-            "skipped": skipped,
-            "note": f"min_pause_seconds={min_pause_seconds}; items without transcripts are skipped.",
-        }
-
-    lifts.sort(key=lambda l: -l["duration_seconds"])
-    if target_ratio:
-        target_frames = timeline_total_frames * float(target_ratio)
-        chosen: List[Dict[str, Any]] = []
-        removed = 0.0
-        for lift in lifts:
-            if removed >= target_frames:
-                break
-            chosen.append(lift)
-            removed += (lift["timeline_end_frame"] - lift["timeline_start_frame"])
-        lifts = chosen
-    # Latest-first application order so earlier spans stay valid.
-    lifts.sort(key=lambda l: -l["timeline_start_frame"])
-
-    # Keep ranges: per item, the complement of its selected lifts, expressed as
-    # media-pool SOURCE frame ranges. Execution assembles a tightened VARIANT
-    # timeline from these (true partial trims; the original is never mutated).
-    keep_ranges: List[Dict[str, Any]] = []
-    lifts_by_item: Dict[int, List[Dict[str, Any]]] = {}
-    for lift in lifts:
-        lifts_by_item.setdefault(int(lift["item_index"]), []).append(lift)
-    for spec in item_specs:
-        item = spec["item"]
-        if spec.get("unanalyzed") or not spec.get("resolve_clip_id"):
-            # Items we can't trim ride along whole when their clip is known;
-            # otherwise they were already reported in `skipped`.
-            continue
-        clip_fps = spec["clip_fps"]
-        cursor = spec["src_start_sec"]
-        segments: List[Tuple[float, float]] = []
-        for lift in sorted(lifts_by_item.get(spec["item_index"], []), key=lambda l: l["source_lift_seconds"][0]):
-            lift_start_sec, lift_end_sec = lift["source_lift_seconds"]
-            if lift_start_sec - cursor > 0.05:
-                segments.append((cursor, lift_start_sec))
-            cursor = max(cursor, lift_end_sec)
-        if spec["src_end_sec"] - cursor > 0.05:
-            segments.append((cursor, spec["src_end_sec"]))
-        audio_indices: List[int] = []
-        if include_audio:
-            audio_indices = [int(i) for i in (item.get("audio_track_indices") or []) if int(i) > 0]
-            if not audio_indices:
-                audio_indices = [1]
-        for seg_start, seg_end in segments:
-            start_frame = int(round(seg_start * clip_fps))
-            end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)) - 1)
-            keep_ranges.append({
-                "clip_id": spec["resolve_clip_id"],
-                "start_frame": start_frame,
-                "end_frame": end_frame,
-                "track_type": "video",
-                "track_index": int(item.get("track_index") or 1),
-            })
-            # Mirror each kept video range onto its linked audio track(s) with
-            # identical source frames so the variant stays frame-locked and
-            # audible. mediaType 2 pulls the same media-pool item's audio.
-            for audio_index in audio_indices:
-                keep_ranges.append({
-                    "clip_id": spec["resolve_clip_id"],
-                    "start_frame": start_frame,
-                    "end_frame": end_frame,
-                    "track_type": "audio",
-                    "media_type": 2,
-                    "track_index": audio_index,
-                })
-
-    removed_frames = sum(l["timeline_end_frame"] - l["timeline_start_frame"] for l in lifts)
-    audio_keep_range_count = sum(1 for r in keep_ranges if r.get("track_type") == "audio")
-    video_keep_range_count = len(keep_ranges) - audio_keep_range_count
-    plan = save_plan(project_root, {
-        "kind": "tighten",
-        "timeline_name": timeline_name,
-        "timeline_fps": fps,
-        "lifts": lifts,
-        "keep_ranges": keep_ranges,
-        "include_audio": bool(include_audio),
-        "skipped": skipped,
-        "summary": (
-            f"{len(lifts)} dead-air lifts, ~{round(removed_frames / fps, 1)}s removed "
-            f"from '{timeline_name}' (assembled as a tightened variant"
-            f"{', video + audio' if include_audio else ', video only'})"
-        ),
-        "settings": {
-            "target_ratio": target_ratio,
-            "min_pause_seconds": min_pause_seconds,
-            "handle_seconds": handle_seconds,
-            "include_audio": bool(include_audio),
-        },
-    })
-    return {
-        "success": True,
-        "status": "plan_ready",
-        "plan_id": plan["plan_id"],
-        "kind": "tighten",
-        "timeline_name": timeline_name,
-        "lift_count": len(lifts),
-        "estimated_removed_seconds": round(removed_frames / fps, 2),
-        "lifts": lifts,
-        "keep_range_count": len(keep_ranges),
-        "video_keep_range_count": video_keep_range_count,
-        "audio_keep_range_count": audio_keep_range_count,
-        "include_audio": bool(include_audio),
-        "skipped": skipped,
-        "note": (
-            "Dry-run plan. Execute with edit_engine(action='execute_tighten', "
-            "params={plan_id}) — a tightened VARIANT timeline is assembled from "
-            "the keep ranges; the original timeline is never mutated. "
-            + (
-                f"Audio is mirrored onto matching tracks ({audio_keep_range_count} "
-                "audio ranges) so the variant is audible."
-                if include_audio
-                else "include_audio=False: the variant will be VIDEO-ONLY (silent)."
-            )
-        ),
-    }
-
-
-# ── E3: swap alternates ──────────────────────────────────────────────────────
-
-
-def plan_swap(
-    project_root: str,
-    *,
-    item: Dict[str, Any],
-    timeline_name: str,
-    timeline_fps: float,
-    kind: str = "visual",
-    limit: int = 5,
-) -> Dict[str, Any]:
-    """Rank alternate shots for one timeline item via the similarity index.
-
-    `item` comes from the server: {timeline_start_frame, timeline_end_frame,
-    source_start_frame, media_ref, item_name?, track_index?}.
-    """
-    from src.utils import embeddings
-
-    conn = timeline_brain_db.connect(project_root)
-    clip_uuid = analysis_store.resolve_clip_uuid(
-        conn, item.get("media_ref")
-    ) or analysis_store.resolve_clip_uuid(conn, item.get("media_path"))
-    if not clip_uuid:
-        return {"success": False, "error": "No analysis for the item's source media (db_ingest or analyze first)"}
-    clip_row = conn.execute("SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)).fetchone()
-    clip_fps = _clip_fps(dict(clip_row)) if clip_row else 24.0
-    fps = float(timeline_fps) if timeline_fps and float(timeline_fps) > 0 else 24.0
-    try:
-        tl_start = int(item["timeline_start_frame"])
-        tl_end = int(item["timeline_end_frame"])
-        src_start_frame = int(item.get("source_start_frame") or 0)
-    except (KeyError, TypeError, ValueError):
-        return {"success": False, "error": "item requires timeline_start_frame/timeline_end_frame/source_start_frame"}
-    src_mid_sec = src_start_frame / clip_fps + ((tl_end - tl_start) / fps) / 2.0
-    shot_row = conn.execute(
-        """
-        SELECT * FROM shots
-        WHERE clip_uuid = ? AND time_seconds_start <= ? AND time_seconds_end > ?
-        """,
-        (clip_uuid, src_mid_sec, src_mid_sec),
-    ).fetchone()
-    if not shot_row:
-        return {"success": False, "error": f"No analyzed shot covers source time {round(src_mid_sec, 2)}s"}
-    shot = dict(shot_row)
-
-    found = embeddings.find_similar(
-        project_root,
-        shot_uuid=shot["shot_uuid"],
-        kind=kind,
-        entity_types=["shot"],
-        limit=int(limit) * 2,
-    )
-    if not found.get("success"):
-        return found
-    duration_frames = tl_end - tl_start
-    needed_seconds = duration_frames / fps
-
-    # Vision-confirmed alt takes outrank raw cosine similarity (spec §4).
-    from src.utils import shot_relationships as _shot_relationships
-    confirmed_alts = set(_shot_relationships.confirmed_alt_take_shot_uuids(conn, shot["shot_uuid"]))
-
-    def _viable_alternate(
-        *, clip_uuid: Any, shot_uuid_: Any, shot_index: Any, description: Any,
-        alt_start: Any, alt_end: Any, score: Any, rationale: str,
-    ) -> Optional[Dict[str, Any]]:
-        alt_clip = conn.execute(
-            "SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)
-        ).fetchone()
-        if not alt_clip or not alt_clip["resolve_clip_id"]:
-            return None
-        if alt_start is None or alt_end is None:
-            return None
-        if (float(alt_end) - float(alt_start)) < needed_seconds:
-            return None  # alternate too short to fill the slot
-        alt = dict(alt_clip)
-        alt_fps = _clip_fps(alt)
-        start_frame = int(round(float(alt_start) * alt_fps))
-        end_frame = start_frame + int(round(needed_seconds * alt_fps)) - 1
-        return {
-            "score": score,
-            "clip_uuid": clip_uuid,
-            "clip_name": alt.get("clip_name"),
-            "resolve_clip_id": alt["resolve_clip_id"],
-            "shot_uuid": shot_uuid_,
-            "shot_index": shot_index,
-            "description": description,
-            "source_frame_range": [start_frame, end_frame],
-            "confirmed_alt_take": str(shot_uuid_) in confirmed_alts,
-            "rationale": rationale,
-        }
-
-    alternates: List[Dict[str, Any]] = []
-    seen_shot_uuids: set = set()
-    for hit in found.get("results") or []:
-        hit_uuid = str(hit.get("entity_uuid"))
-        is_confirmed = hit_uuid in confirmed_alts
-        basis = (
-            f"vision-confirmed alt_take_of relationship (cosine {hit.get('score')} agrees)"
-            if is_confirmed
-            else f"cosine {hit.get('score')} to the current shot ({kind} embedding)"
-        )
-        alternate = _viable_alternate(
-            clip_uuid=hit.get("clip_uuid"), shot_uuid_=hit.get("entity_uuid"),
-            shot_index=hit.get("shot_index"), description=hit.get("description"),
-            alt_start=hit.get("time_seconds_start"), alt_end=hit.get("time_seconds_end"),
-            score=hit.get("score"),
-            rationale=f"{basis}; long enough to fill the slot exactly",
-        )
-        if alternate:
-            alternates.append(alternate)
-            seen_shot_uuids.add(hit_uuid)
-    # Confirmed alt takes the cosine search missed still belong in the list.
-    for alt_uuid in confirmed_alts - seen_shot_uuids:
-        alt_shot = conn.execute("SELECT * FROM shots WHERE shot_uuid = ?", (alt_uuid,)).fetchone()
-        if not alt_shot:
-            continue
-        alt_shot = dict(alt_shot)
-        alternate = _viable_alternate(
-            clip_uuid=alt_shot.get("clip_uuid"), shot_uuid_=alt_uuid,
-            shot_index=alt_shot.get("shot_index"), description=alt_shot.get("description"),
-            alt_start=alt_shot.get("time_seconds_start"), alt_end=alt_shot.get("time_seconds_end"),
-            score=None,
-            rationale="vision-confirmed alt_take_of relationship (not surfaced by the cosine search); long enough to fill the slot exactly",
-        )
-        if alternate:
-            alternates.append(alternate)
-    alternates.sort(key=lambda a: (not a.get("confirmed_alt_take"), -(a.get("score") or 0.0)))
-    alternates = alternates[: int(limit)]
-    if not alternates:
-        return {
-            "success": False,
-            "error": "No viable alternates (similar shots were too short or their clips are not in this Resolve project)",
-        }
-
-    plan = save_plan(project_root, {
-        "kind": "swap",
-        "timeline_name": timeline_name,
-        "timeline_fps": fps,
-        "item": {
-            "timeline_start_frame": tl_start,
-            "timeline_end_frame": tl_end,
-            "track_index": item.get("track_index") or 1,
-            "item_name": item.get("item_name"),
-            "current_shot_uuid": shot["shot_uuid"],
-            "current_description": shot.get("description"),
-        },
-        "alternates": alternates,
-        "summary": (
-            f"{len(alternates)} alternates for '{item.get('item_name') or 'item'}' "
-            f"on '{timeline_name}' (slot {tl_start}-{tl_end})"
-        ),
-    })
-    return {
-        "success": True,
-        "status": "plan_ready",
-        "plan_id": plan["plan_id"],
-        "kind": "swap",
-        "timeline_name": timeline_name,
-        "current_shot": {
-            "shot_uuid": shot["shot_uuid"],
-            "shot_index": shot["shot_index"],
-            "description": shot.get("description"),
-        },
-        "alternates": alternates,
-        "note": (
-            "Dry-run plan. Execute with edit_engine(action='execute_swap', "
-            "params={plan_id, alternate_index}) — the item is replaced on a "
-            "version-archived timeline (lift + positioned append, same slot)."
-        ),
-    }