davinci-resolve-mcp 2.43.0 → 2.44.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.44.0
+
+Cross-clip entities + bin briefing v2 — Phase D of the analysis +
+edit-engine program. Recurring people/places/props found by clustering the
+visual embeddings, confirmed with one vision call per cluster.
+
+- **Added** schema v11 (`entities` + `entity_appearances`) and
+  `src/utils/entities.py`: union-find clustering over the v10 CLIP frame
+  vectors (cosine threshold, no new deps), representative-frame selection,
+  ghost pruning across re-runs (labeled entities persist), and a
+  detection-state stash so `entity_index` always resolves against the exact
+  ordering the payload was issued with.
+- **Added** `media_analysis` actions: `detect_entities` (clusters + deferred
+  one-frame-per-cluster confirmation payload, caps pre-checked),
+  `commit_entities` (kind/label/description with conservative-label rules;
+  `merge_with` collapses duplicate clusters), `list_entities`,
+  `prepare_bin_briefing` (entities + per-clip summaries, text-only), and
+  `commit_bin_summary` (host-synthesized briefing written above the v2.0
+  aggregate in `memory/bin_summary.md`).
+- **Added** a "Recurring across this bin" card on the panel's Review page
+  (`/api/entities`), shown once labeled entities exist.
+- **Validation**: full offline suite (1105 tests; 10 new). Live on the real
+  sample root: 3 clusters detected from 16 CLIP vectors; host-chat
+  confirmation labeled the shattered-windshield POV and the white rental
+  sedan and merged the sedan's two clusters; bin briefing synthesized and
+  committed; panel card verified and screenshots regenerated.
+
 ## What's New in v2.43.0
 
 Embeddings + similarity search — Phase C of the analysis + edit-engine

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.43.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.44.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-33%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -496,7 +496,27 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `set_panel_state`, `session_start_context`, `update_clip_field`,
 `update_shot_field`, `get_field_history`, `revert_field`,
 `list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
-`build_embeddings`, and `find_similar`.
+`build_embeddings`, `find_similar`, `detect_entities`, `commit_entities`,
+`list_entities`, `prepare_bin_briefing`, and `commit_bin_summary`.
+
+**Cross-clip entities + bin briefing v2 (v2.44.0+).** Recurring
+people/places/props across a project's media, found cheaply and confirmed
+with ONE vision call per cluster:
+- `detect_entities(threshold?, min_cluster_size?)` clusters the v10 CLIP
+  frame vectors (build visual embeddings first), writes provisional entity
+  rows + appearances, and returns a deferred payload with one
+  representative frame per cluster (caps pre-checked, estimate inlined).
+  The host chat reads those frames and calls
+  `commit_entities(entities=[{entity_index, kind, label, description,
+  confidence, merge_with?}], vision_token)` — conservative labels only
+  (describe what's visible; never guess names). `merge_with` collapses
+  clusters that show the same entity.
+- `list_entities` returns labeled entities with per-clip/shot appearances;
+  the panel's Review page shows a "Recurring across this bin" card.
+- `prepare_bin_briefing` returns entities + per-clip summaries (text-only,
+  no vision cost); the host writes a colleague-style markdown briefing and
+  calls `commit_bin_summary(briefing, briefing_token)`, which lands in
+  `memory/bin_summary.md` above the v2.0 aggregate.
 
 **Embeddings + similarity (v2.43.0+).** Local-compute semantic search; no
 vendor tokens, so nothing here touches the caps ledger. Backends are

package/docs/guides/control-panel.md

@@ -82,7 +82,10 @@ transcripts once the search index is built. When a local text-embedding
 backend is detected (ollama with `nomic-embed-text`, or
 sentence-transformers), a `Semantic` toggle appears next to the search box —
 it searches by meaning instead of exact words, ranking clips, shots, and
-transcript lines by similarity to your query.
+transcript lines by similarity to your query. Once cross-clip entity
+detection has run (`detect_entities` + a one-frame-per-cluster confirmation
+in chat), a `Recurring across this bin` card lists the labeled people,
+places, and objects with their shot counts.
 
 ### Clip detail
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.43.0"
+VERSION = "2.44.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.43.0",
+  "version": "2.44.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -2114,6 +2114,30 @@ HTML = r"""<!doctype html>
       margin-bottom: var(--space-3);
       flex-wrap: wrap;
     }
+    .review-semantic-toggle {
+      display: inline-flex;
+      gap: 6px;
+      align-items: center;
+      color: var(--text-secondary);
+      font-size: var(--ops-text-label);
+      white-space: nowrap;
+    }
+    .review-entities {
+      margin-bottom: var(--space-3);
+      padding: var(--space-2) var(--space-3);
+      border: 1px solid var(--border-default);
+      border-radius: var(--radius-md);
+    }
+    .review-entities-title {
+      color: var(--text-secondary);
+      font-size: var(--ops-text-label);
+      margin-bottom: 6px;
+    }
+    .review-entities-chips {
+      display: flex;
+      gap: var(--space-2);
+      flex-wrap: wrap;
+    }
     .review-bin-filters input[type="search"] {
       flex: 1 1 280px;
       min-width: 200px;
@@ -4077,6 +4101,7 @@ HTML = r"""<!doctype html>
           </div>
         </div>
         <div id="reviewBinSummary" class="review-bin-summary">Loading analyzed clips…</div>
+        <div id="reviewEntitiesCard" class="review-entities" style="display:none"></div>
         <div id="reviewBinGrid" class="review-grid"></div>
         <div id="reviewSearchResults" class="review-search-results" style="display:none"></div>
       </div>
@@ -8093,6 +8118,22 @@ HTML = r"""<!doctype html>
       renderReviewBin();
       // Coverage runs in parallel — failures here must not block the clip grid.
       refreshReadinessCard().catch(() => {});
+      refreshEntitiesCard().catch(() => {});
+    }
+
+    // Recurring people/places/props detected across the bin (Phase D).
+    // Hidden until at least one labeled entity exists.
+    async function refreshEntitiesCard() {
+      const card = $('reviewEntitiesCard');
+      if (!card) return;
+      const data = await api('/api/entities').catch(() => null);
+      const labeled = (data?.entities || []).filter(e => e.label);
+      if (!labeled.length) { card.style.display = 'none'; return; }
+      card.style.display = '';
+      card.innerHTML = `<div class="review-entities-title">Recurring across this bin</div>
+        <div class="review-entities-chips">${labeled.map(e =>
+          `<span class="review-chip" title="${escapeHtml(e.description || '')}">${escapeHtml(e.label)} · ${e.kind || 'unknown'} · ${e.shot_count || e.cluster_size || 0} shots</span>`
+        ).join('')}</div>`;
     }
 
     async function refreshReadinessCard() {
@@ -14386,6 +14427,14 @@ class Handler(BaseHTTPRequestHandler):
                 payload["results"] = _v2_enrich_search_results(self.state.project_root, payload["results"])
             self._json(payload)
             return
+        if path == "/api/entities":
+            try:
+                from src.utils import entities as _entities
+
+                self._json(_entities.list_entities(self.state.project_root))
+            except Exception as exc:  # noqa: BLE001 — panel reads fail soft
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path == "/api/search/semantic":
             q = (query.get("q") or [""])[0]
             try:

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.43.0"
+VERSION = "2.44.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.43.0"
+VERSION = "2.44.0"
 
 import base64
 import os
@@ -15027,6 +15027,12 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         # Phase C — embeddings + similarity.
         "build_embeddings",
         "find_similar",
+        # Phase D — cross-clip entities + bin briefing v2.
+        "detect_entities",
+        "commit_entities",
+        "list_entities",
+        "prepare_bin_briefing",
+        "commit_bin_summary",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15150,6 +15156,38 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                 entity_types=entity_types,
                 limit=int(p.get("limit") or 10),
             )
+        # Phase D — cross-clip entities + bin briefing v2.
+        if action == "detect_entities":
+            from src.utils import entities
+            return entities.detect_entities(
+                project_root,
+                threshold=float(p.get("threshold") or entities.DEFAULT_CLUSTER_THRESHOLD),
+                min_cluster_size=int(p.get("min_cluster_size") or p.get("minClusterSize") or entities.DEFAULT_MIN_CLUSTER_SIZE),
+                max_clusters=int(p.get("max_clusters") or p.get("maxClusters") or 24),
+                job_id=p.get("job_id") or p.get("jobId"),
+            )
+        if action == "commit_entities":
+            from src.utils import entities
+            return entities.commit_entities(
+                project_root,
+                entities_payload=p.get("entities"),
+                vision_token=p.get("vision_token") or p.get("visionToken"),
+                author=p.get("author") or "host_chat",
+            )
+        if action == "list_entities":
+            from src.utils import entities
+            return entities.list_entities(project_root, kind=p.get("kind"))
+        if action == "prepare_bin_briefing":
+            from src.utils import entities
+            return entities.prepare_bin_briefing(project_root)
+        if action == "commit_bin_summary":
+            from src.utils import entities
+            return entities.commit_bin_summary(
+                project_root,
+                briefing=p.get("briefing") or p.get("summary"),
+                briefing_token=p.get("briefing_token") or p.get("briefingToken"),
+                author=p.get("author") or "host_chat",
+            )
         if action in {"build_index", "rebuild_index"}:
             return build_analysis_index(project_root, index_path=p.get("index_path") or p.get("indexPath"))
         if action == "index_status":
@@ -15566,6 +15604,11 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "vision_pending_sweep",
         "build_embeddings",
         "find_similar",
+        "detect_entities",
+        "commit_entities",
+        "list_entities",
+        "prepare_bin_briefing",
+        "commit_bin_summary",
         "get_caps",
         "set_caps_preset",
         "get_usage",

package/src/utils/entities.py

@@ -0,0 +1,579 @@
+"""Cross-clip entities (Phase D of the analysis program).
+
+Recurring people/places/props across a project's analyzed media. The cheap
+part is local: union-find clustering over the v10 CLIP frame vectors with a
+cosine threshold. The expensive part is bounded: ONE host-vision call per
+cluster representative (the deferred-payload pattern), committed via
+``commit_entities`` with kind/label/description per cluster — conservative
+labels, per the trust-by-default rule (hedge identity when evidence is thin).
+
+Bin briefing v2 rides the same pattern at bin level: ``prepare_bin_briefing``
+returns entities + per-clip summaries for the host chat to synthesize, and
+``commit_bin_summary`` writes the result into memory/bin_summary.md (the v2.0
+aggregate stays below as an appendix).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from src.utils import analysis_memory, embeddings, timeline_brain_db
+
+ENTITY_VISION_SOURCE = "vision_entity_v1"
+ENTITY_SCHEMA_REFERENCE = "davinci_resolve_mcp.entity_confirmation.v1"
+DEFAULT_CLUSTER_THRESHOLD = 0.78
+DEFAULT_MIN_CLUSTER_SIZE = 2
+
+ENTITY_SCHEMA = {
+    "entities": [
+        {
+            "entity_index": "<int — from the payload's clusters list>",
+            "entity_uuid": "<echo the cluster's entity_uuid when convenient>",
+            "kind": "person|place|object|unknown",
+            "label": "<short conservative label — 'man in dark hooded jacket', not a name unless visibly slated>",
+            "description": "<1-2 sentences of what recurs across these frames>",
+            "confidence": "low|medium|high",
+            "merge_with": "<optional int entity_index this duplicates, else omit>",
+        }
+    ]
+}
+
+ENTITY_PROMPT = (
+    "Each cluster below groups frames that look visually similar across the "
+    "project's clips. Look at each cluster's representative frame and decide "
+    "what recurring entity it shows (a person, place, or object). Use "
+    "conservative labels — describe what is visible, never guess identity or "
+    "names unless text on screen states them. If two clusters clearly show "
+    "the same entity, point the duplicate at the original with merge_with. "
+    "Return strict JSON matching `schema`."
+)
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _ma():
+    from src.utils import media_analysis
+
+    return media_analysis
+
+
+class _UnionFind:
+    def __init__(self, n: int) -> None:
+        self.parent = list(range(n))
+
+    def find(self, i: int) -> int:
+        while self.parent[i] != i:
+            self.parent[i] = self.parent[self.parent[i]]
+            i = self.parent[i]
+        return i
+
+    def union(self, a: int, b: int) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[rb] = ra
+
+
+def _cluster_vectors(
+    vectors: List[List[float]], threshold: float
+) -> List[List[int]]:
+    """Union-find over pairwise cosine similarity. O(n²) — fine at this scale."""
+    n = len(vectors)
+    uf = _UnionFind(n)
+    try:
+        import numpy as np
+
+        matrix = np.asarray(vectors, dtype="float32")
+        norms = np.linalg.norm(matrix, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        normalized = matrix / norms
+        sims = normalized @ normalized.T
+        for i in range(n):
+            row = sims[i]
+            for j in range(i + 1, n):
+                if row[j] >= threshold:
+                    uf.union(i, j)
+    except ImportError:
+        for i in range(n):
+            for j in range(i + 1, n):
+                if embeddings.cosine_similarity(vectors[i], vectors[j]) >= threshold:
+                    uf.union(i, j)
+    groups: Dict[int, List[int]] = {}
+    for i in range(n):
+        groups.setdefault(uf.find(i), []).append(i)
+    return sorted(groups.values(), key=len, reverse=True)
+
+
+def _representative(vectors: List[List[float]], members: List[int]) -> Tuple[int, Dict[int, float]]:
+    """Member with the highest mean similarity to its cluster, plus each
+    member's similarity to that representative."""
+    best_index = members[0]
+    best_mean = -1.0
+    for i in members:
+        mean = sum(embeddings.cosine_similarity(vectors[i], vectors[j]) for j in members if j != i)
+        mean = mean / max(1, len(members) - 1)
+        if mean > best_mean:
+            best_mean, best_index = mean, i
+    sims = {
+        j: (1.0 if j == best_index else embeddings.cosine_similarity(vectors[best_index], vectors[j]))
+        for j in members
+    }
+    return best_index, sims
+
+
+def _entity_uuid_for(frame_refs: Sequence[str]) -> str:
+    return _ma().short_hash("entity:" + ",".join(sorted(frame_refs)), 12)
+
+
+def _detection_state_path(project_root: str) -> str:
+    return os.path.join(analysis_memory.memory_dir(project_root), "entity_detection_state.json")
+
+
+def _write_detection_state(project_root: str, token: str, ordering: List[str]) -> None:
+    analysis_memory.ensure_memory_structure(project_root)
+    path = _detection_state_path(project_root)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        json.dump({"vision_token": token, "ordering": ordering, "written_at": _now()}, handle, indent=2)
+    os.replace(tmp, path)
+
+
+def _read_detection_state(project_root: str) -> Optional[Dict[str, Any]]:
+    try:
+        with open(_detection_state_path(project_root), "r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def detect_entities(
+    project_root: str,
+    *,
+    threshold: float = DEFAULT_CLUSTER_THRESHOLD,
+    min_cluster_size: int = DEFAULT_MIN_CLUSTER_SIZE,
+    max_clusters: int = 24,
+    job_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Cluster visual frame vectors into provisional entities and return the
+    deferred host-vision confirmation payload (one frame per cluster)."""
+    ma = _ma()
+    conn = timeline_brain_db.connect(project_root)
+    rows = conn.execute(
+        """
+        SELECT entity_uuid, vector FROM embeddings
+        WHERE embedding_kind = 'visual' AND entity_type = 'frame'
+        """
+    ).fetchall()
+    if not rows:
+        return {
+            "success": False,
+            "error": (
+                "No visual frame embeddings yet — run "
+                "media_analysis(action='build_embeddings', params={'kinds': ['visual']}) first."
+            ),
+        }
+    frame_refs = [str(r["entity_uuid"]) for r in rows]
+    vectors = [embeddings.unpack_vector(r["vector"]) for r in rows]
+
+    clusters = [
+        members for members in _cluster_vectors(vectors, float(threshold))
+        if len(members) >= int(min_cluster_size)
+    ][: int(max_clusters)]
+    if not clusters:
+        return {
+            "success": True,
+            "status": "no_clusters",
+            "frame_count": len(rows),
+            "note": f"No clusters of size >= {min_cluster_size} at threshold {threshold}.",
+        }
+
+    # Hydrate frame rows once: frame_ref -> (clip_uuid, frame_index, path, shot_uuid).
+    frame_info: Dict[str, Dict[str, Any]] = {}
+    for ref in frame_refs:
+        clip_uuid, _, frame_index = ref.rpartition(":")
+        row = conn.execute(
+            "SELECT frame_path, shot_uuid FROM frames WHERE clip_uuid = ? AND frame_index = ?",
+            (clip_uuid, int(frame_index) if frame_index.lstrip("-").isdigit() else -1),
+        ).fetchone()
+        frame_info[ref] = {
+            "clip_uuid": clip_uuid,
+            "frame_index": frame_index,
+            "frame_path": str(row["frame_path"]) if row and row["frame_path"] else None,
+            "shot_uuid": str(row["shot_uuid"]) if row and row["shot_uuid"] else None,
+        }
+
+    # Caps: one frame per cluster goes to the host.
+    estimated_tokens = len(clusters) * 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
+
+    now = _now()
+    cluster_payload: List[Dict[str, Any]] = []
+    entity_uuids: List[str] = []
+    with timeline_brain_db.transaction(project_root) as txn:
+        for index, members in enumerate(clusters, 1):
+            refs = [frame_refs[i] for i in members]
+            rep_i, sims = _representative(vectors, members)
+            rep_ref = frame_refs[rep_i]
+            rep = frame_info[rep_ref]
+            entity_uuid = _entity_uuid_for(refs)
+            entity_uuids.append(entity_uuid)
+            existing = txn.execute(
+                "SELECT created_at, kind, label, description, confidence, source FROM entities WHERE entity_uuid = ?",
+                (entity_uuid,),
+            ).fetchone()
+            txn.execute(
+                """
+                INSERT OR REPLACE INTO entities
+                    (entity_uuid, kind, label, description, confidence, source,
+                     representative_frame_ref, representative_frame_path,
+                     cluster_size, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    entity_uuid,
+                    existing["kind"] if existing else "unknown",
+                    existing["label"] if existing else None,
+                    existing["description"] if existing else None,
+                    existing["confidence"] if existing else None,
+                    existing["source"] if existing else "clustering",
+                    rep_ref,
+                    rep["frame_path"],
+                    len(members),
+                    str(existing["created_at"]) if existing else now,
+                    now,
+                ),
+            )
+            txn.execute("DELETE FROM entity_appearances WHERE entity_uuid = ?", (entity_uuid,))
+            for i in members:
+                ref = frame_refs[i]
+                info = frame_info[ref]
+                txn.execute(
+                    """
+                    INSERT OR IGNORE INTO entity_appearances
+                        (entity_uuid, clip_uuid, shot_uuid, frame_ref, similarity)
+                    VALUES (?, ?, ?, ?, ?)
+                    """,
+                    (entity_uuid, info["clip_uuid"], info["shot_uuid"], ref, round(float(sims[i]), 4)),
+                )
+            clip_count = len({frame_info[r]["clip_uuid"] for r in refs})
+            shot_count = len({frame_info[r]["shot_uuid"] for r in refs if frame_info[r]["shot_uuid"]})
+            cluster_payload.append({
+                "entity_index": index,
+                "entity_uuid": entity_uuid,
+                "frame_count": len(members),
+                "clip_count": clip_count,
+                "shot_count": shot_count,
+                "already_labeled": bool(existing and existing["label"]),
+                "current_label": existing["label"] if existing else None,
+                "representative_frame_path": rep["frame_path"],
+            })
+
+    # Prune unlabeled provisional ghosts from earlier runs (a different
+    # threshold re-shapes clusters → new uuids). Labeled entities persist.
+    with timeline_brain_db.transaction(project_root) as txn:
+        placeholders = ",".join("?" for _ in entity_uuids)
+        txn.execute(
+            f"""
+            DELETE FROM entity_appearances WHERE entity_uuid IN (
+                SELECT entity_uuid FROM entities
+                WHERE source = 'clustering' AND label IS NULL
+                  AND entity_uuid NOT IN ({placeholders})
+            )
+            """,
+            entity_uuids,
+        )
+        txn.execute(
+            f"""
+            DELETE FROM entities
+            WHERE source = 'clustering' AND label IS NULL
+              AND entity_uuid NOT IN ({placeholders})
+            """,
+            entity_uuids,
+        )
+
+    vision_token = _ma().short_hash("entities:" + ",".join(sorted(entity_uuids)), 16)
+    _write_detection_state(project_root, vision_token, entity_uuids)
+    return {
+        "success": True,
+        "status": "pending_host_analysis",
+        "provider": "host_chat_paths",
+        "mode": "entity_confirmation",
+        "vision_token": vision_token,
+        "threshold": threshold,
+        "frame_count": len(rows),
+        "cluster_count": len(clusters),
+        "estimate": {
+            "frames_to_review": len(clusters),
+            "estimated_vision_tokens": estimated_tokens,
+        },
+        "clusters": cluster_payload,
+        "frame_paths": [c["representative_frame_path"] for c in cluster_payload if c["representative_frame_path"]],
+        "schema": json.loads(json.dumps(ENTITY_SCHEMA)),
+        "schema_reference": ENTITY_SCHEMA_REFERENCE,
+        "prompt": ENTITY_PROMPT,
+        "commit_action": {
+            "tool": "media_analysis",
+            "action": "commit_entities",
+            "params": {
+                "vision_token": vision_token,
+                "entities": "<host chat: fill per `schema`>",
+                "analysis_root": project_root,
+            },
+        },
+        "instructions": (
+            "Read each cluster's representative_frame_path as a local image and "
+            "produce one entry per entity_index in `entities` per the schema. "
+            "Then call the tool in commit_action. Clusters marked "
+            "already_labeled keep their label unless you provide a better one."
+        ),
+    }
+
+
+def commit_entities(
+    project_root: str,
+    *,
+    entities_payload: Any,
+    vision_token: Optional[str] = None,
+    author: str = "host_chat",
+) -> Dict[str, Any]:
+    """Apply host-vision labels to provisional entity clusters."""
+    if isinstance(entities_payload, str):
+        try:
+            entities_payload = json.loads(entities_payload)
+        except json.JSONDecodeError as exc:
+            return {"success": False, "error": f"entities was a string but not valid JSON: {exc}"}
+    if isinstance(entities_payload, dict) and isinstance(entities_payload.get("entities"), list):
+        entities_payload = entities_payload["entities"]
+    if not isinstance(entities_payload, list) or not entities_payload:
+        return {"success": False, "error": "commit_entities requires `entities`: a non-empty array"}
+
+    state = _read_detection_state(project_root)
+    if not state:
+        return {"success": False, "error": "No entity-detection state — run detect_entities first"}
+    expected = str(state.get("vision_token") or "")
+    if vision_token and str(vision_token) != expected:
+        return {
+            "success": False,
+            "error": "vision_token mismatch; entity clusters changed since the payload was issued (re-run detect_entities).",
+            "expected_vision_token": expected,
+        }
+
+    # entity_index resolution uses the exact ordering detect_entities issued.
+    by_index = {i + 1: uuid for i, uuid in enumerate(state.get("ordering") or [])}
+    now = _now()
+    updated = 0
+    merged = 0
+    with timeline_brain_db.transaction(project_root) as txn:
+        merges: List[Tuple[str, str]] = []
+        for entry in entities_payload:
+            if not isinstance(entry, dict):
+                continue
+            uuid = entry.get("entity_uuid") or by_index.get(_safe_int(entry.get("entity_index")))
+            if not uuid:
+                continue
+            merge_target = entry.get("merge_with")
+            if merge_target is not None:
+                target_uuid = by_index.get(_safe_int(merge_target))
+                if target_uuid and target_uuid != uuid:
+                    merges.append((str(uuid), target_uuid))
+                    continue
+            txn.execute(
+                """
+                UPDATE entities
+                SET kind = ?, label = ?, description = ?, confidence = ?,
+                    source = ?, updated_at = ?
+                WHERE entity_uuid = ?
+                """,
+                (
+                    str(entry.get("kind") or "unknown"),
+                    entry.get("label"),
+                    entry.get("description"),
+                    entry.get("confidence"),
+                    ENTITY_VISION_SOURCE if author == "host_chat" else "human",
+                    now,
+                    str(uuid),
+                ),
+            )
+            updated += 1
+        for duplicate, target in merges:
+            txn.execute(
+                "UPDATE OR IGNORE entity_appearances SET entity_uuid = ? WHERE entity_uuid = ?",
+                (target, duplicate),
+            )
+            txn.execute("DELETE FROM entity_appearances WHERE entity_uuid = ?", (duplicate,))
+            txn.execute("DELETE FROM entities WHERE entity_uuid = ?", (duplicate,))
+            size = txn.execute(
+                "SELECT COUNT(*) FROM entity_appearances WHERE entity_uuid = ?", (target,)
+            ).fetchone()[0]
+            txn.execute(
+                "UPDATE entities SET cluster_size = ?, updated_at = ? WHERE entity_uuid = ?",
+                (int(size), now, target),
+            )
+            merged += 1
+
+    ma = _ma()
+    ma._record_caps_usage(
+        project_root=project_root,
+        clip_id=None,
+        vision_tokens=updated * ma.AVG_VISION_TOKENS_PER_FRAME,
+        frames_uploaded=updated,
+    )
+    return {"success": True, "entities_updated": updated, "entities_merged": merged}
+
+
+def _safe_int(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def list_entities(project_root: str, *, kind: Optional[str] = None) -> Dict[str, Any]:
+    conn = timeline_brain_db.connect(project_root)
+    where = " WHERE kind = ?" if kind else ""
+    args: Tuple[Any, ...] = (kind,) if kind else ()
+    rows = conn.execute(
+        f"SELECT * FROM entities{where} ORDER BY cluster_size DESC, label", args
+    ).fetchall()
+    entities: List[Dict[str, Any]] = []
+    for row in rows:
+        entity = dict(row)
+        appearances = conn.execute(
+            """
+            SELECT a.clip_uuid, c.clip_name, a.shot_uuid, s.shot_index, a.frame_ref, a.similarity
+            FROM entity_appearances a
+            LEFT JOIN clips c ON c.clip_uuid = a.clip_uuid
+            LEFT JOIN shots s ON s.shot_uuid = a.shot_uuid
+            WHERE a.entity_uuid = ?
+            ORDER BY a.clip_uuid, s.shot_index
+            """,
+            (entity["entity_uuid"],),
+        ).fetchall()
+        entity["appearances"] = [dict(a) for a in appearances]
+        entity["clip_count"] = len({a["clip_uuid"] for a in appearances})
+        entity["shot_count"] = len({a["shot_uuid"] for a in appearances if a["shot_uuid"]})
+        entities.append(entity)
+    return {"success": True, "count": len(entities), "entities": entities}
+
+
+# ── bin briefing v2 ──────────────────────────────────────────────────────────
+
+
+def prepare_bin_briefing(project_root: str) -> Dict[str, Any]:
+    """Deferred payload for a host-synthesized bin briefing: labeled entities
+    + per-clip summaries. Text-only — no frames, no vision cost."""
+    conn = timeline_brain_db.connect(project_root)
+    clips = [dict(r) for r in conn.execute(
+        "SELECT clip_uuid, clip_name, summary, duration_seconds, shot_count, overall_motion_level FROM clips ORDER BY clip_name"
+    ).fetchall()]
+    if not clips:
+        return {"success": False, "error": "No analyzed clips in the DB — analyze (or db_ingest) first."}
+    for clip in clips:
+        row = conn.execute(
+            """
+            SELECT value_json FROM subjective_fields
+            WHERE entity_type='clip' AND entity_uuid=? AND field_path='clip_summary'
+              AND superseded_at IS NULL
+            """,
+            (clip["clip_uuid"],),
+        ).fetchone()
+        if row:
+            try:
+                clip["clip_summary"] = json.loads(row["value_json"])
+            except (TypeError, ValueError):
+                pass
+    listed = list_entities(project_root)
+    entity_lines = [
+        {
+            "label": e.get("label") or "(unlabeled cluster)",
+            "kind": e.get("kind"),
+            "description": e.get("description"),
+            "clip_count": e.get("clip_count"),
+            "shot_count": e.get("shot_count"),
+            "frame_count": e.get("cluster_size"),
+        }
+        for e in listed.get("entities") or []
+    ]
+    token = _ma().short_hash(
+        "briefing:" + ",".join(sorted(c["clip_uuid"] for c in clips)), 16
+    )
+    return {
+        "success": True,
+        "status": "pending_host_synthesis",
+        "briefing_token": token,
+        "clips": clips,
+        "entities": entity_lines,
+        "prompt": (
+            "Write a colleague-style bin briefing in markdown: 2-4 paragraphs "
+            "covering what this media is, who/what recurs (use the entities "
+            "list), the strongest material, and anything an editor should know "
+            "before cutting. Conservative claims only — describe, don't guess. "
+            "Then call the tool in commit_action with `briefing` set to the markdown."
+        ),
+        "commit_action": {
+            "tool": "media_analysis",
+            "action": "commit_bin_summary",
+            "params": {
+                "briefing": "<host chat: markdown briefing>",
+                "briefing_token": token,
+                "analysis_root": project_root,
+            },
+        },
+    }
+
+
+def commit_bin_summary(
+    project_root: str,
+    *,
+    briefing: Any,
+    briefing_token: Optional[str] = None,
+    author: str = "host_chat",
+) -> Dict[str, Any]:
+    """Write the host-synthesized briefing above the v2.0 aggregate."""
+    if not isinstance(briefing, str) or not briefing.strip():
+        return {"success": False, "error": "commit_bin_summary requires `briefing` (markdown text)"}
+    conn = timeline_brain_db.connect(project_root)
+    clips = [str(r["clip_uuid"]) for r in conn.execute("SELECT clip_uuid FROM clips ORDER BY clip_name").fetchall()]
+    expected = _ma().short_hash("briefing:" + ",".join(sorted(clips)), 16)
+    if briefing_token and str(briefing_token) != expected:
+        return {
+            "success": False,
+            "error": "briefing_token mismatch; the clip set changed since the payload was issued (re-run prepare_bin_briefing).",
+        }
+    analysis_memory.ensure_memory_structure(project_root)
+    path = analysis_memory.bin_summary_path(project_root)
+    appendix = ""
+    if os.path.isfile(path):
+        try:
+            with open(path, "r", encoding="utf-8") as handle:
+                existing = handle.read()
+            # Keep only the aggregate section as an appendix (drop a previous
+            # synthesized briefing if present).
+            marker = "# Bin summary —"
+            idx = existing.find(marker)
+            if idx >= 0:
+                appendix = existing[idx:]
+        except OSError:
+            appendix = ""
+    content = (
+        f"# Bin briefing\n\n_Synthesized {_now()} by {author} "
+        f"(entities + per-clip summaries)._\n\n{briefing.strip()}\n"
+    )
+    if appendix:
+        content += f"\n\n---\n\n{appendix}"
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        handle.write(content)
+    os.replace(tmp, path)
+    return {"success": True, "path": path, "bytes": len(content)}

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 = 10
+SCHEMA_VERSION = 11
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -719,6 +719,53 @@ def _migrate_v10_embeddings(conn: sqlite3.Connection) -> None:
     )
 
 
+@register_migration(11)
+def _migrate_v11_entities(conn: sqlite3.Connection) -> None:
+    """C5 — cross-clip entities (Phase D of the analysis program).
+
+    `entities` rows start as provisional clusters over the v10 visual
+    embeddings (source='clustering', label NULL) and are enriched by one
+    host-vision call per cluster representative (source='vision_entity_v1')
+    or by humans. `entity_appearances` records every frame an entity was
+    seen in, with the clip/shot derivation and the match similarity.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS entities (
+            entity_uuid TEXT PRIMARY KEY,
+            kind TEXT,                            -- person|place|object|unknown
+            label TEXT,
+            description TEXT,
+            confidence TEXT,
+            source TEXT NOT NULL,
+            representative_frame_ref TEXT,        -- 'clip_uuid:frame_index'
+            representative_frame_path TEXT,
+            cluster_size INTEGER,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_entities_kind ON entities(kind);
+
+        CREATE TABLE IF NOT EXISTS entity_appearances (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            entity_uuid TEXT NOT NULL,
+            clip_uuid TEXT NOT NULL,
+            shot_uuid TEXT,
+            frame_ref TEXT NOT NULL,              -- 'clip_uuid:frame_index'
+            similarity REAL,
+            UNIQUE(entity_uuid, frame_ref),
+            FOREIGN KEY (entity_uuid) REFERENCES entities(entity_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_entity_appearances_entity
+            ON entity_appearances(entity_uuid);
+        CREATE INDEX IF NOT EXISTS ix_entity_appearances_clip
+            ON entity_appearances(clip_uuid);
+        """
+    )
+
+
 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(