davinci-resolve-mcp 2.48.1 → 2.49.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.49.0
+
+Cross-shot relationships (spec §4 — pattern recognition only): the shot
+page's Relationships group finally fills, and the edit engine can prefer
+vision-confirmed alternates.
+
+- **Added** schema v12 `shot_relationships` (same_setup_as / alt_take_of
+  symmetric, continues_from directional — the source shot continues from
+  the target) with supersede semantics (current rows have
+  `superseded_at IS NULL`).
+- **Added** `media_analysis` actions `detect_shot_relationships` /
+  `commit_shot_relationships` / `list_shot_relationships`: pairwise cosine
+  over the per-shot visual vectors (transcript continuity as a second
+  signal for continues_from) → a deferred confirmation payload with a
+  representative frame PAIR per candidate (caps pre-checked; candidates
+  live only in the detection-state stash until committed, so re-detect
+  never leaves ghosts) → vision-confirmed rows. Representative frames use
+  the shot's middle sample (first/last frames often catch fades).
+- **Added** the shot page's Relationships group now renders from the DB
+  (`continues_from` shows on the continuing shot; cross-clip targets are
+  clip-qualified).
+- **Changed** `plan_swap` prefers confirmed `alt_take_of` alternates over
+  raw cosine similarity — confirmed takes sort first (and are unioned in
+  even when the cosine search missed them); each alternate's rationale
+  states which basis ranked it.
+
 ## What's New in v2.48.1
 
 Bug fix surfaced by the first real-cut tighten pilot.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.48.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.49.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -497,7 +497,9 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `update_shot_field`, `get_field_history`, `revert_field`,
 `list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
 `build_embeddings`, `find_similar`, `detect_entities`, `commit_entities`,
-`list_entities`, `prepare_bin_briefing`, and `commit_bin_summary`.
+`list_entities`, `prepare_bin_briefing`, `commit_bin_summary`,
+`detect_shot_relationships`, `commit_shot_relationships`, and
+`list_shot_relationships`.
 
 **Cross-clip entities + bin briefing v2 (v2.44.0+).** Recurring
 people/places/props across a project's media, found cheaply and confirmed
@@ -518,6 +520,29 @@ with ONE vision call per cluster:
   calls `commit_bin_summary(briefing, briefing_token)`, which lands in
   `memory/bin_summary.md` above the v2.0 aggregate.
 
+**Cross-shot relationships (v2.49.0+).** Pattern recognition only (spec §4 —
+no editorial suggestions): `same_setup_as` / `alt_take_of` (symmetric) and
+`continues_from` (directional; the source shot continues from the target).
+- `detect_shot_relationships(setup_threshold?, alt_take_threshold?,
+  continues_band?, max_candidates?)` — pairwise cosine over the per-shot
+  visual vectors (build visual embeddings first; raise
+  `max_frames_per_clip` if shot coverage is partial), plus transcript
+  continuity as a second signal for `continues_from`. Returns a deferred
+  payload with a representative frame PAIR per candidate (caps pre-checked,
+  two frames per candidate). Candidates live only in the detection-state
+  stash until committed — re-detect replaces them.
+- The host chat reads BOTH frames of each pair and calls
+  `commit_shot_relationships(relationships=[{candidate_index, verdict:
+  confirm|reject, relationship_type?, confidence?}], vision_token)`.
+  Confirm only what the frames show; reject lookalikes. Overriding the
+  suggested type is allowed. Committed rows supersede prior machine rows
+  for the same pair.
+- `list_shot_relationships(clip_id?, shot_uuid?, relationship_type?)` —
+  current rows with clip/shot context on both ends. The shot page's
+  Relationships group fills from these rows, and `plan_swap` prefers
+  confirmed `alt_take_of` alternates over raw cosine (the rationale states
+  which basis ranked each alternate).
+
 **Embeddings + similarity (v2.43.0+).** Local-compute semantic search; no
 vendor tokens, so nothing here touches the caps ledger. Backends are
 detected, never installed (capabilities lists them with install guidance):

package/docs/guides/control-panel.md

@@ -120,7 +120,11 @@ future re-analysis so human notes survive fresh vision runs. `Open in Resolve`
 jumps straight to the clip in the source viewer with the shot's mark in/out
 set. The field groups (Visual, Content, Production, Editorial, Cuttability)
 are filled by the opt-in deep vision pass — `Deepen this shot` copies a chat
-prompt that runs it for just this shot, estimate first.
+prompt that runs it for just this shot, estimate first. The Relationships
+group (same_setup_as / continues_from / alt_take_of) fills from the
+cross-shot relationships pass (`detect_shot_relationships` →
+vision-confirm → `commit_shot_relationships`); `continues_from` is shown on
+the continuing shot.
 
 ### Media → History
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.48.1"
+VERSION = "2.49.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.48.1",
+  "version": "2.49.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -13144,6 +13144,30 @@ def get_analyzed_clip_shot(project_root: str, clip_id: str, shot_index: int) ->
         })
     corrections = _v2_read_corrections_for_dir(clip_dir)
     shot_corrections = _v2_filter_corrections_for_shot(corrections, matched.get("shot_uuid"), shot_index)
+    # Cross-shot relationships (spec §4) come from the DB, not the report —
+    # fill the shot page's Relationships group when confirmed rows exist.
+    # Exported reports don't carry shot_uuid, so derive it from the DB by
+    # clip + shot_index.
+    try:
+        from src.utils import analysis_store as _analysis_store
+        from src.utils import shot_relationships as _shot_rel
+        conn = _timeline_brain_db.connect(project_root)
+        shot_uuid = matched.get("shot_uuid")
+        if not shot_uuid:
+            clip_uuid = _analysis_store.resolve_clip_uuid(conn, clip_id)
+            if clip_uuid:
+                hit = conn.execute(
+                    "SELECT shot_uuid FROM shots WHERE clip_uuid = ? AND shot_index = ?",
+                    (clip_uuid, int(shot_index)),
+                ).fetchone()
+                shot_uuid = hit["shot_uuid"] if hit else None
+        if shot_uuid:
+            relationships = _shot_rel.relationships_for_shot(conn, str(shot_uuid))
+            if relationships:
+                matched = dict(matched)
+                matched["relationships"] = relationships
+    except Exception:  # noqa: BLE001 — panel reads fail soft
+        pass
     return {
         "success": True,
         "clip_id": clip_id,

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.48.1"
+VERSION = "2.49.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.48.1"
+VERSION = "2.49.0"
 
 import base64
 import os
@@ -15772,6 +15772,10 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "list_entities",
         "prepare_bin_briefing",
         "commit_bin_summary",
+        # Cross-shot relationships (spec §4).
+        "detect_shot_relationships",
+        "commit_shot_relationships",
+        "list_shot_relationships",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15916,6 +15920,40 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         if action == "list_entities":
             from src.utils import entities
             return entities.list_entities(project_root, kind=p.get("kind"))
+        # Cross-shot relationships (spec §4): detect → one bounded vision
+        # confirm (frame pairs) → commit; pattern recognition only.
+        if action == "detect_shot_relationships":
+            from src.utils import shot_relationships
+            band = p.get("continues_band") or p.get("continuesBand")
+            return shot_relationships.detect_shot_relationships(
+                project_root,
+                setup_threshold=float(p.get("setup_threshold") or p.get("setupThreshold")
+                                      or shot_relationships.DEFAULT_SETUP_THRESHOLD),
+                alt_take_threshold=float(p.get("alt_take_threshold") or p.get("altTakeThreshold")
+                                         or shot_relationships.DEFAULT_ALT_TAKE_THRESHOLD),
+                continues_band=tuple(band) if isinstance(band, (list, tuple)) and len(band) == 2
+                else shot_relationships.DEFAULT_CONTINUES_BAND,
+                max_candidates=int(p.get("max_candidates") or p.get("maxCandidates")
+                                   or shot_relationships.DEFAULT_MAX_CANDIDATES),
+                job_id=p.get("job_id") or p.get("jobId"),
+            )
+        if action == "commit_shot_relationships":
+            from src.utils import shot_relationships
+            return shot_relationships.commit_shot_relationships(
+                project_root,
+                relationships_payload=p.get("relationships"),
+                vision_token=p.get("vision_token") or p.get("visionToken"),
+                author=p.get("author") or "host_chat",
+            )
+        if action == "list_shot_relationships":
+            from src.utils import shot_relationships
+            return shot_relationships.list_shot_relationships(
+                project_root,
+                clip_ref=p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir"),
+                shot_uuid=p.get("shot_uuid") or p.get("shotUuid"),
+                relationship_type=p.get("relationship_type") or p.get("relationshipType"),
+                include_superseded=bool(p.get("include_superseded") or p.get("includeSuperseded")),
+            )
         if action == "prepare_bin_briefing":
             from src.utils import entities
             return entities.prepare_bin_briefing(project_root)
@@ -16348,6 +16386,9 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "list_entities",
         "prepare_bin_briefing",
         "commit_bin_summary",
+        "detect_shot_relationships",
+        "commit_shot_relationships",
+        "list_shot_relationships",
         "get_caps",
         "set_caps_preset",
         "get_usage",

package/src/utils/edit_engine.py

@@ -579,37 +579,79 @@ def plan_swap(
     if not found.get("success"):
         return found
     duration_frames = tl_end - tl_start
-    alternates: List[Dict[str, Any]] = []
-    for hit in found.get("results") or []:
+    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 = ?", (hit.get("clip_uuid"),)
+            "SELECT * FROM clips WHERE clip_uuid = ?", (clip_uuid,)
         ).fetchone()
         if not alt_clip or not alt_clip["resolve_clip_id"]:
-            continue
-        alt = dict(alt_clip)
-        alt_fps = _clip_fps(alt)
-        alt_start = hit.get("time_seconds_start")
-        alt_end = hit.get("time_seconds_end")
+            return None
         if alt_start is None or alt_end is None:
-            continue
-        needed_seconds = duration_frames / fps
+            return None
         if (float(alt_end) - float(alt_start)) < needed_seconds:
-            continue  # alternate too short to fill the slot
+            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
-        alternates.append({
-            "score": hit.get("score"),
-            "clip_uuid": hit.get("clip_uuid"),
+        return {
+            "score": score,
+            "clip_uuid": clip_uuid,
             "clip_name": alt.get("clip_name"),
             "resolve_clip_id": alt["resolve_clip_id"],
-            "shot_uuid": hit.get("entity_uuid"),
-            "shot_index": hit.get("shot_index"),
-            "description": hit.get("description"),
+            "shot_uuid": shot_uuid_,
+            "shot_index": shot_index,
+            "description": description,
             "source_frame_range": [start_frame, end_frame],
-            "rationale": f"cosine {hit.get('score')} to the current shot ({kind} embedding); long enough to fill the slot exactly",
-        })
-        if len(alternates) >= int(limit):
-            break
+            "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,

package/src/utils/shot_relationships.py

@@ -0,0 +1,544 @@
+"""Cross-shot relationships (spec §4 — pattern recognition only).
+
+Detect → one bounded vision confirm → commit, the Phase D entities pattern:
+the cheap part is local (pairwise cosine over the v10 per-shot visual
+vectors, plus transcript continuity as a second signal for continues_from);
+the expensive part is bounded (the host chat reviews a representative frame
+PAIR per candidate). NO editorial suggestions are stored — only the three
+spec §4 relationship types:
+
+- same_setup_as  (symmetric)  — same camera + framing of the same action
+- alt_take_of    (symmetric)  — different take of the same setup
+- continues_from (directional)— the SOURCE shot continues from the TARGET
+  shot (target precedes source)
+
+Symmetric rows are stored once with the pair canonically ordered by
+(clip_name, shot_index); readers must check both columns. Candidates live
+only in the detection-state stash until committed — re-detect overwrites
+the stash, so unconfirmed candidates can never linger as ghosts. Commit
+supersedes any current machine row for the same (pair, type) before
+inserting, so human corrections (a later C4-style author='human' row)
+always stay newest.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from src.utils import analysis_memory, embeddings, timeline_brain_db
+
+RELATIONSHIP_VISION_SOURCE = "vision_relationship_v1"
+RELATIONSHIP_SCHEMA_REFERENCE = "davinci_resolve_mcp.relationship_confirmation.v1"
+RELATIONSHIP_TYPES = ("same_setup_as", "continues_from", "alt_take_of")
+
+# Tuned on the sample root (34-shot montage) during Phase 4 live validation.
+DEFAULT_SETUP_THRESHOLD = 0.90      # same-clip non-adjacent or cross-clip: same_setup_as
+DEFAULT_ALT_TAKE_THRESHOLD = 0.88   # cross-clip + comparable duration: alt_take_of
+DEFAULT_CONTINUES_BAND = (0.70, 0.90)  # adjacent same-clip shots: continues_from
+DEFAULT_MAX_CANDIDATES = 24
+ALT_TAKE_DURATION_RATIO = 2.0       # durations within 2x of each other
+
+RELATIONSHIP_SCHEMA = {
+    "relationships": [
+        {
+            "candidate_index": "<int — from the payload's candidates list>",
+            "verdict": "confirm|reject",
+            "relationship_type": "same_setup_as|continues_from|alt_take_of (override the suggestion when the frames say otherwise)",
+            "confidence": "low|medium|high",
+        }
+    ]
+}
+
+RELATIONSHIP_PROMPT = (
+    "Each candidate below pairs two shots that the local heuristics think are "
+    "related. Look at BOTH frames of each pair and judge the suggested "
+    "relationship: same_setup_as = same camera setup + framing of the same "
+    "action; alt_take_of = a different take of the same setup; continues_from "
+    "= the first shot visibly continues the second shot's action across a "
+    "cut. Confirm only what the frames actually show — reject lookalikes "
+    "(similar palette or subject is NOT the same setup). You may override the "
+    "suggested type when the frames support a different one. Return strict "
+    "JSON matching `schema`."
+)
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _now_precise() -> str:
+    """Microsecond timestamps — `timestamp` is part of the row's UNIQUE key,
+    so two commits of the same pair within one second must not collide."""
+    now = time.time()
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(now)) + f".{int((now % 1) * 1e6):06d}Z"
+
+
+def _ma():
+    from src.utils import media_analysis
+
+    return media_analysis
+
+
+def _state_path(project_root: str) -> str:
+    return os.path.join(analysis_memory.memory_dir(project_root), "relationship_detection_state.json")
+
+
+def _write_state(project_root: str, token: str, candidates: List[Dict[str, Any]]) -> None:
+    analysis_memory.ensure_memory_structure(project_root)
+    path = _state_path(project_root)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        json.dump({"vision_token": token, "candidates": candidates, "written_at": _now()}, handle, indent=2)
+    os.replace(tmp, path)
+
+
+def _read_state(project_root: str) -> Optional[Dict[str, Any]]:
+    try:
+        with open(_state_path(project_root), "r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _shot_rows(conn) -> Dict[str, Dict[str, Any]]:
+    rows = conn.execute(
+        """
+        SELECT s.shot_uuid, s.clip_uuid, s.shot_index, s.time_seconds_start,
+               s.time_seconds_end, s.description, c.clip_name
+        FROM shots s LEFT JOIN clips c ON c.clip_uuid = s.clip_uuid
+        """
+    ).fetchall()
+    return {str(r["shot_uuid"]): dict(r) for r in rows}
+
+
+def _rep_frame_path(conn, shot_uuid: str) -> Optional[str]:
+    """The shot's MIDDLE sampled frame — first/last frames often catch fades
+    or transition black, which makes pair review impossible."""
+    rows = conn.execute(
+        """
+        SELECT frame_path FROM frames
+        WHERE shot_uuid = ? AND frame_path IS NOT NULL
+        ORDER BY frame_index
+        """,
+        (str(shot_uuid),),
+    ).fetchall()
+    if not rows:
+        return None
+    return str(rows[len(rows) // 2]["frame_path"])
+
+
+def _transcript_spans_boundary(conn, clip_uuid: str, boundary_seconds: float) -> bool:
+    """A transcript segment spanning the cut boundary is continuity evidence."""
+    row = conn.execute(
+        """
+        SELECT 1 FROM transcript_segments
+        WHERE clip_uuid = ? AND start_seconds < ? AND end_seconds > ?
+        LIMIT 1
+        """,
+        (clip_uuid, float(boundary_seconds), float(boundary_seconds)),
+    ).fetchone()
+    return row is not None
+
+
+def _canonical_pair(a: Dict[str, Any], b: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    key = lambda s: (str(s.get("clip_name") or ""), int(s.get("shot_index") or 0))  # noqa: E731
+    return (a, b) if key(a) <= key(b) else (b, a)
+
+
+def detect_shot_relationships(
+    project_root: str,
+    *,
+    setup_threshold: float = DEFAULT_SETUP_THRESHOLD,
+    alt_take_threshold: float = DEFAULT_ALT_TAKE_THRESHOLD,
+    continues_band: Tuple[float, float] = DEFAULT_CONTINUES_BAND,
+    max_candidates: int = DEFAULT_MAX_CANDIDATES,
+    job_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Pairwise heuristics over per-shot visual vectors → deferred
+    confirmation payload with a representative frame PAIR per candidate."""
+    ma = _ma()
+    conn = timeline_brain_db.connect(project_root)
+    vec_rows = conn.execute(
+        """
+        SELECT entity_uuid, vector FROM embeddings
+        WHERE embedding_kind = 'visual' AND entity_type = 'shot'
+        """
+    ).fetchall()
+    if not vec_rows:
+        return {
+            "success": False,
+            "error": (
+                "No per-shot visual embeddings yet — run "
+                "media_analysis(action='build_embeddings', params={'kinds': ['visual']}) first."
+            ),
+        }
+    shots = _shot_rows(conn)
+    uuids = [str(r["entity_uuid"]) for r in vec_rows if str(r["entity_uuid"]) in shots]
+    vectors = {u: embeddings.unpack_vector(r["vector"]) for u, r in zip(
+        [str(r["entity_uuid"]) for r in vec_rows], vec_rows) if u in shots}
+
+    low_cont, high_cont = float(continues_band[0]), float(continues_band[1])
+    candidates: List[Dict[str, Any]] = []
+    for i in range(len(uuids)):
+        for j in range(i + 1, len(uuids)):
+            a, b = shots[uuids[i]], shots[uuids[j]]
+            sim = embeddings.cosine_similarity(vectors[uuids[i]], vectors[uuids[j]])
+            same_clip = a["clip_uuid"] == b["clip_uuid"]
+            suggestion = None
+            evidence: List[str] = []
+            if same_clip:
+                index_gap = abs(int(a["shot_index"]) - int(b["shot_index"]))
+                if index_gap == 1 and low_cont <= sim < high_cont:
+                    suggestion = "continues_from"
+                    earlier, later = (a, b) if int(a["shot_index"]) < int(b["shot_index"]) else (b, a)
+                    boundary = earlier.get("time_seconds_end")
+                    if boundary is not None and _transcript_spans_boundary(
+                        conn, str(a["clip_uuid"]), float(boundary)
+                    ):
+                        evidence.append("a transcript segment spans the cut boundary")
+                elif index_gap > 1 and sim >= float(setup_threshold):
+                    suggestion = "same_setup_as"
+            else:
+                dur_a = (a.get("time_seconds_end") or 0) - (a.get("time_seconds_start") or 0)
+                dur_b = (b.get("time_seconds_end") or 0) - (b.get("time_seconds_start") or 0)
+                comparable = (
+                    dur_a > 0 and dur_b > 0
+                    and max(dur_a, dur_b) / max(min(dur_a, dur_b), 0.001) <= ALT_TAKE_DURATION_RATIO
+                )
+                if sim >= float(alt_take_threshold) and comparable:
+                    suggestion = "alt_take_of"
+                elif sim >= float(setup_threshold):
+                    suggestion = "same_setup_as"
+            if not suggestion:
+                continue
+            evidence.insert(0, f"visual cosine {round(float(sim), 3)} between per-shot vectors")
+            if suggestion == "continues_from":
+                # Directional: the LATER shot continues from the EARLIER one.
+                earlier, later = (a, b) if int(a["shot_index"]) < int(b["shot_index"]) else (b, a)
+                source, target = later, earlier
+            else:
+                source, target = _canonical_pair(a, b)
+            candidates.append({
+                "source_shot_uuid": source["shot_uuid"],
+                "target_shot_uuid": target["shot_uuid"],
+                "suggested_type": suggestion,
+                "similarity": round(float(sim), 4),
+                "evidence": evidence,
+                "_sim": float(sim),
+            })
+
+    candidates.sort(key=lambda c: -c["_sim"])
+    candidates = candidates[: max(1, int(max_candidates))]
+    for candidate in candidates:
+        candidate.pop("_sim", None)
+    if not candidates:
+        return {
+            "success": True,
+            "status": "no_candidates",
+            "shot_count": len(uuids),
+            "note": (
+                f"No relationship candidates at setup>={setup_threshold}, "
+                f"alt_take>={alt_take_threshold}, continues {continues_band}."
+            ),
+        }
+
+    # Caps: two frames per candidate go to the host.
+    estimated_tokens = len(candidates) * 2 * ma.AVG_VISION_TOKENS_PER_FRAME
+    refusal = ma._check_caps_pre_call(
+        project_root=project_root,
+        estimated_vision_tokens=estimated_tokens,
+        clip_id=None,
+        job_id=job_id,
+    )
+    if refusal is not None:
+        return refusal
+
+    payload: List[Dict[str, Any]] = []
+    state_rows: List[Dict[str, Any]] = []
+    for index, candidate in enumerate(candidates, 1):
+        src = shots[candidate["source_shot_uuid"]]
+        dst = shots[candidate["target_shot_uuid"]]
+        src_frame = _rep_frame_path(conn, candidate["source_shot_uuid"])
+        dst_frame = _rep_frame_path(conn, candidate["target_shot_uuid"])
+        payload.append({
+            "candidate_index": index,
+            "suggested_type": candidate["suggested_type"],
+            "similarity": candidate["similarity"],
+            "evidence": candidate["evidence"],
+            "source_shot": {
+                "clip_name": src.get("clip_name"), "shot_index": src.get("shot_index"),
+                "description": src.get("description"), "frame_path": src_frame,
+            },
+            "target_shot": {
+                "clip_name": dst.get("clip_name"), "shot_index": dst.get("shot_index"),
+                "description": dst.get("description"), "frame_path": dst_frame,
+            },
+        })
+        state_rows.append({
+            "candidate_index": index,
+            "source_shot_uuid": candidate["source_shot_uuid"],
+            "target_shot_uuid": candidate["target_shot_uuid"],
+            "suggested_type": candidate["suggested_type"],
+            "similarity": candidate["similarity"],
+        })
+
+    vision_token = ma.short_hash(
+        "relationships:" + ",".join(f"{r['source_shot_uuid']}>{r['target_shot_uuid']}" for r in state_rows), 16,
+    )
+    # Candidates live ONLY here until committed — re-detect overwrites the
+    # stash, so unconfirmed candidates never linger as ghost rows.
+    _write_state(project_root, vision_token, state_rows)
+    frame_paths = [
+        p for c in payload for p in (c["source_shot"]["frame_path"], c["target_shot"]["frame_path"]) if p
+    ]
+    return {
+        "success": True,
+        "status": "pending_host_analysis",
+        "provider": "host_chat_paths",
+        "mode": "relationship_confirmation",
+        "vision_token": vision_token,
+        "candidate_count": len(payload),
+        "estimate": {
+            "frames_to_review": len(frame_paths),
+            "estimated_vision_tokens": estimated_tokens,
+        },
+        "thresholds": {
+            "setup_threshold": setup_threshold,
+            "alt_take_threshold": alt_take_threshold,
+            "continues_band": list(continues_band),
+        },
+        "candidates": payload,
+        "frame_paths": frame_paths,
+        "schema": json.loads(json.dumps(RELATIONSHIP_SCHEMA)),
+        "schema_reference": RELATIONSHIP_SCHEMA_REFERENCE,
+        "prompt": RELATIONSHIP_PROMPT,
+        "commit_action": {
+            "tool": "media_analysis",
+            "action": "commit_shot_relationships",
+            "params": {
+                "vision_token": vision_token,
+                "relationships": "<host chat: fill per `schema`>",
+                "analysis_root": project_root,
+            },
+        },
+        "instructions": (
+            "For each candidate read BOTH frame paths as local images, judge "
+            "the suggested relationship, and return one entry per "
+            "candidate_index in `relationships` per the schema. Then call the "
+            "tool in commit_action. Reject anything the frames don't support."
+        ),
+    }
+
+
+def commit_shot_relationships(
+    project_root: str,
+    *,
+    relationships_payload: Any,
+    vision_token: Optional[str] = None,
+    author: str = "host_chat",
+) -> Dict[str, Any]:
+    """Write vision-confirmed relationship rows (machine source label).
+
+    Supersedes any current machine row for the same (pair, type) first, so
+    re-running the pass never duplicates and never outranks human rows added
+    later (human edits ride the same supersede semantics with author='human')."""
+    if isinstance(relationships_payload, str):
+        try:
+            relationships_payload = json.loads(relationships_payload)
+        except json.JSONDecodeError as exc:
+            return {"success": False, "error": f"relationships was a string but not valid JSON: {exc}"}
+    if isinstance(relationships_payload, dict) and isinstance(relationships_payload.get("relationships"), list):
+        relationships_payload = relationships_payload["relationships"]
+    if not isinstance(relationships_payload, list) or not relationships_payload:
+        return {"success": False, "error": "commit_shot_relationships requires `relationships`: a non-empty array"}
+
+    state = _read_state(project_root)
+    if not state:
+        return {"success": False, "error": "No relationship-detection state — run detect_shot_relationships first"}
+    expected = str(state.get("vision_token") or "")
+    if vision_token and str(vision_token) != expected:
+        return {
+            "success": False,
+            "error": (
+                "vision_token mismatch; candidates changed since the payload was "
+                "issued (re-run detect_shot_relationships)."
+            ),
+            "expected_vision_token": expected,
+        }
+    by_index = {int(c["candidate_index"]): c for c in state.get("candidates") or []}
+
+    now = _now_precise()
+    confirmed = 0
+    rejected = 0
+    skipped: List[Dict[str, Any]] = []
+    frames_reviewed = len(by_index) * 2
+    with timeline_brain_db.transaction(project_root) as txn:
+        for entry in relationships_payload:
+            if not isinstance(entry, dict):
+                continue
+            try:
+                candidate = by_index.get(int(entry.get("candidate_index")))
+            except (TypeError, ValueError):
+                candidate = None
+            if candidate is None:
+                skipped.append({"entry": entry, "reason": "unknown candidate_index"})
+                continue
+            verdict = str(entry.get("verdict") or "").strip().lower()
+            if verdict != "confirm":
+                rejected += 1
+                continue
+            rel_type = str(entry.get("relationship_type") or candidate["suggested_type"])
+            if rel_type not in RELATIONSHIP_TYPES:
+                skipped.append({"entry": entry, "reason": f"invalid relationship_type {rel_type!r}"})
+                continue
+            source_uuid = str(candidate["source_shot_uuid"])
+            target_uuid = str(candidate["target_shot_uuid"])
+            txn.execute(
+                """
+                UPDATE shot_relationships SET superseded_at = ?
+                WHERE relationship_type = ? AND superseded_at IS NULL
+                  AND source = ?
+                  AND ((source_shot_uuid = ? AND target_shot_uuid = ?)
+                       OR (source_shot_uuid = ? AND target_shot_uuid = ?))
+                """,
+                (now, rel_type, RELATIONSHIP_VISION_SOURCE,
+                 source_uuid, target_uuid, target_uuid, source_uuid),
+            )
+            txn.execute(
+                """
+                INSERT INTO shot_relationships
+                    (source_shot_uuid, target_shot_uuid, relationship_type,
+                     confidence, source, author, timestamp, superseded_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, NULL)
+                """,
+                (
+                    source_uuid,
+                    target_uuid,
+                    rel_type,
+                    entry.get("confidence"),
+                    RELATIONSHIP_VISION_SOURCE if author == "host_chat" else "human",
+                    author,
+                    now,
+                ),
+            )
+            confirmed += 1
+
+    ma = _ma()
+    ma._record_caps_usage(
+        project_root=project_root,
+        clip_id=None,
+        vision_tokens=frames_reviewed * ma.AVG_VISION_TOKENS_PER_FRAME,
+        frames_uploaded=frames_reviewed,
+    )
+    return {
+        "success": True,
+        "confirmed": confirmed,
+        "rejected": rejected,
+        "skipped": skipped,
+    }
+
+
+def list_shot_relationships(
+    project_root: str,
+    *,
+    clip_ref: Optional[str] = None,
+    shot_uuid: Optional[str] = None,
+    relationship_type: Optional[str] = None,
+    include_superseded: bool = False,
+) -> Dict[str, Any]:
+    """Current relationship rows, hydrated with clip/shot context on both ends."""
+    conn = timeline_brain_db.connect(project_root)
+    where = [] if include_superseded else ["r.superseded_at IS NULL"]
+    args: List[Any] = []
+    if relationship_type:
+        where.append("r.relationship_type = ?")
+        args.append(relationship_type)
+    if shot_uuid:
+        where.append("(r.source_shot_uuid = ? OR r.target_shot_uuid = ?)")
+        args.extend([str(shot_uuid), str(shot_uuid)])
+    if clip_ref:
+        from src.utils import analysis_store
+
+        clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
+        if not clip_uuid:
+            return {"success": False, "error": f"No analyzed clip found for {clip_ref!r}"}
+        where.append(
+            "(src.clip_uuid = ? OR dst.clip_uuid = ?)"
+        )
+        args.extend([clip_uuid, clip_uuid])
+    where_sql = (" WHERE " + " AND ".join(where)) if where else ""
+    rows = conn.execute(
+        f"""
+        SELECT r.*, src.clip_uuid AS source_clip_uuid, src.shot_index AS source_shot_index,
+               sc.clip_name AS source_clip_name,
+               dst.clip_uuid AS target_clip_uuid, dst.shot_index AS target_shot_index,
+               dc.clip_name AS target_clip_name
+        FROM shot_relationships r
+        LEFT JOIN shots src ON src.shot_uuid = r.source_shot_uuid
+        LEFT JOIN clips sc ON sc.clip_uuid = src.clip_uuid
+        LEFT JOIN shots dst ON dst.shot_uuid = r.target_shot_uuid
+        LEFT JOIN clips dc ON dc.clip_uuid = dst.clip_uuid
+        {where_sql}
+        ORDER BY r.relationship_type, r.id
+        """,
+        args,
+    ).fetchall()
+    return {"success": True, "count": len(rows), "relationships": [dict(r) for r in rows]}
+
+
+def relationships_for_shot(conn, shot_uuid: str) -> Dict[str, List[str]]:
+    """Panel block for one shot: {type: ["Clip · shot N", ...]} from current
+    rows, reading both directions of the symmetric types. continues_from is
+    shown only on the SOURCE shot (the one that continues)."""
+    out: Dict[str, List[str]] = {}
+    rows = conn.execute(
+        """
+        SELECT r.relationship_type, r.source_shot_uuid, r.target_shot_uuid,
+               src.shot_index AS source_shot_index, sc.clip_name AS source_clip_name,
+               src.clip_uuid AS source_clip_uuid,
+               dst.shot_index AS target_shot_index, dc.clip_name AS target_clip_name,
+               dst.clip_uuid AS target_clip_uuid
+        FROM shot_relationships r
+        LEFT JOIN shots src ON src.shot_uuid = r.source_shot_uuid
+        LEFT JOIN clips sc ON sc.clip_uuid = src.clip_uuid
+        LEFT JOIN shots dst ON dst.shot_uuid = r.target_shot_uuid
+        LEFT JOIN clips dc ON dc.clip_uuid = dst.clip_uuid
+        WHERE r.superseded_at IS NULL
+          AND (r.source_shot_uuid = ? OR r.target_shot_uuid = ?)
+        """,
+        (str(shot_uuid), str(shot_uuid)),
+    ).fetchall()
+    me = str(shot_uuid)
+    for row in rows:
+        rel_type = str(row["relationship_type"])
+        is_source = str(row["source_shot_uuid"]) == me
+        if rel_type == "continues_from" and not is_source:
+            continue  # shown on the continuing shot only
+        other_index = row["target_shot_index"] if is_source else row["source_shot_index"]
+        other_clip = row["target_clip_name"] if is_source else row["source_clip_name"]
+        same_clip = (row["source_clip_uuid"] == row["target_clip_uuid"])
+        label = f"shot {other_index}" if same_clip else f"{other_clip} · shot {other_index}"
+        out.setdefault(rel_type, []).append(label)
+    return out
+
+
+def confirmed_alt_take_shot_uuids(conn, shot_uuid: str) -> List[str]:
+    """Shot uuids confirmed as alt takes of `shot_uuid` (either direction)."""
+    rows = conn.execute(
+        """
+        SELECT source_shot_uuid, target_shot_uuid FROM shot_relationships
+        WHERE relationship_type = 'alt_take_of' AND superseded_at IS NULL
+          AND (source_shot_uuid = ? OR target_shot_uuid = ?)
+        """,
+        (str(shot_uuid), str(shot_uuid)),
+    ).fetchall()
+    me = str(shot_uuid)
+    out: List[str] = []
+    for row in rows:
+        other = str(row["target_shot_uuid"]) if str(row["source_shot_uuid"]) == me else str(row["source_shot_uuid"])
+        if other != me and other not in out:
+            out.append(other)
+    return out

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 11
+SCHEMA_VERSION = 12
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -766,6 +766,44 @@ def _migrate_v11_entities(conn: sqlite3.Connection) -> None:
     )
 
 
+@register_migration(12)
+def _migrate_v12_shot_relationships(conn: sqlite3.Connection) -> None:
+    """Cross-shot relationships (spec §4 — pattern recognition only).
+
+    Three types: same_setup_as / alt_take_of (symmetric — stored once with
+    the canonically-ordered pair) and continues_from (directional — the
+    SOURCE shot continues from the TARGET shot, i.e. target precedes source).
+    Rows are append-only with supersede semantics: current rows have
+    superseded_at IS NULL.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS shot_relationships (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_shot_uuid TEXT NOT NULL,
+            target_shot_uuid TEXT NOT NULL,
+            relationship_type TEXT NOT NULL CHECK(relationship_type IN
+                ('same_setup_as', 'continues_from', 'alt_take_of')),
+            confidence TEXT,
+            source TEXT NOT NULL,
+            author TEXT NOT NULL,
+            timestamp TEXT NOT NULL,
+            superseded_at TEXT,
+            UNIQUE(source_shot_uuid, target_shot_uuid, relationship_type, timestamp),
+            FOREIGN KEY (source_shot_uuid) REFERENCES shots(shot_uuid) ON DELETE CASCADE,
+            FOREIGN KEY (target_shot_uuid) REFERENCES shots(shot_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_relationships_source
+            ON shot_relationships(source_shot_uuid) WHERE superseded_at IS NULL;
+        CREATE INDEX IF NOT EXISTS idx_relationships_target
+            ON shot_relationships(target_shot_uuid) WHERE superseded_at IS NULL;
+        CREATE INDEX IF NOT EXISTS idx_relationships_type
+            ON shot_relationships(relationship_type) WHERE superseded_at IS NULL;
+        """
+    )
+
+
 def latest_version(conn: sqlite3.Connection, timeline_name: str) -> Optional[int]:
     """Return the highest archived version number for `timeline_name`, or None."""
     row = conn.execute(