davinci-resolve-mcp 2.60.0 → 2.61.1

package/CHANGELOG.md

@@ -2,6 +2,131 @@
 
 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.61.1
+
+The strata cleanup batch deferred from the v2.61.0 review — behavior-neutral
+consolidation and hot-path efficiency. No new actions or parameters.
+
+### Changed
+
+- **One clip resolver** — `strata.resolve_clip()` replaces the four drifting
+  per-module wrappers, and rides the pre-v9 auto-ingest fallback hoisted out
+  of deep_vision into `analysis_store.resolve_clip_uuid_ingesting()`: a clip
+  ref that resolves for `deepen` now resolves identically for every strata
+  action, including on older analysis roots.
+- **One float32 codec** — `pack_curve`/`unpack_curve` delegate to
+  `embeddings.pack_vector`/`unpack_vector` instead of duplicating the BLOB
+  convention.
+- **Decode once** — `strata_run` decodes the media file a single time when
+  several audio analyzers run (prosody + beat_grid previously each ran a full
+  ffmpeg decode); the shared `_audio_context` preamble also collapses their
+  duplicated require/resolve/decode blocks.
+- **Registry-derived capabilities** — `ANALYZERS` carries run function plus
+  requires/writes metadata; `capabilities()` derives from it, so adding an
+  analyzer is one entry.
+- **Query-layer caching** — word-find hits clustering in one clip unpack each
+  curve blob once, and `timeline_strata` resolves + bundles a source clip
+  reused across many placements once.
+- **Sargable event windows (schema v15)** — windowed `read_events` bounds its
+  span-overlap lower edge by the track's `MAX(duration_seconds)` (a b-tree
+  descent via the new `ix_events_clip_track_span` index) so
+  `ix_events_clip_track` range-seeks instead of scanning the track.
+- `backfill_words` iterates report blobs lazily with a transcription
+  prefilter instead of loading every blob into memory; `detect_breaths`
+  drops its unreachable non-numpy fallbacks.
+
+### Validation
+
+- Full offline suite: 1,431 tests green (13 new covering the shared resolver
+  + pre-v9 fallback, codec identity, decode-once, per-clip caching, long-span
+  window overlap, and the index range-seek query plan). No Resolve behavior
+  changed; live test not required.
+
+## What's New in v2.61.0
+
+Perception strata — a timecoded track model over every analyzed clip, plus the
+query layer that turns it into editorial answers. Ten new `media_analysis`
+actions, all local compute (ffmpeg + numpy; the face tier detects opencv +
+mediapipe and degrades honestly when absent). Everything measures, compares,
+flags, or aims — nothing decides; the cut is the editor's.
+
+### Added
+
+- **Schema v13: perception strata** — two generic track shapes instead of a
+  table per sensor: `events` (point/span occurrences: pause, breath,
+  hesitation, blink, beat, downbeat, …) and `curves` (float32 time series:
+  pitch, vocal_energy, speech_rate, motion_energy, face curves), plus two
+  promotions out of the report blob: `transcript_words` (per-word timestamps
+  as queryable rows) and `story_beats` (units of meaning over the transcript).
+  Machine re-runs replace their own rows; `source='human'` rows are append-only
+  and always win.
+- **Local analyzers (`strata_run`)** — prosody (pitch/energy/speech-rate curves
+  + pause/breath/hesitation events), beat grid (beat/downbeat + tempo), motion
+  energy (per-frame luma difference), and face strata (blink/gaze/expression
+  via opencv + mediapipe when installed). `strata_status` reports the per-clip
+  track inventory and what this machine can run; `backfill_words` promotes
+  word timestamps already sitting in stored report blobs — no re-analysis.
+- **`take_diff(clip_a, clip_b, text?)`** — align two deliveries of the same
+  line on transcript words and diff pace, pauses, pitch, and energy. Deltas
+  only; it never picks a winner.
+- **`cut_candidates(clip_id, time_seconds)`** — the joint solver: scores every
+  frame around an intended cut on the cut-point grammar (cut on the blink,
+  don't cut mid-word, don't bisect a breath, pauses are doors, land on the
+  beat, cut inside movement) with human-readable reasons per candidate and
+  honest reporting of missing tracks.
+- **`strata_query`** — the strata as one queryable surface: windowed
+  cross-track bundles per clip, or project-wide word find with a joined
+  ±context bundle per hit. **`timeline_strata`** projects clip strata through
+  a versioned timeline's recorded placements.
+- **Story beats (host-LLM pass)** — `plan_story_beats` assembles a timecoded
+  digest + JSON schema (the server never calls an LLM), the host chat produces
+  the beats, `commit_story_beats` validates and persists them append-only;
+  `list_story_beats` reads them back.
+- **Schema v14: timeline timebase snapshot** — `timeline_versions` now records
+  the timeline's fps and start frame at archive time, so `timeline_strata`
+  returns timeline-relative frames/seconds instead of assuming 24fps against
+  absolute (start-timecode-inclusive) snapshot frames.
+
+### Fixed
+
+Pre-release review (multi-agent, 8 finder angles + adversarial verification)
+caught and fixed before anything shipped:
+
+- **Re-ingest cascade wipe** — the ingest `INSERT OR REPLACE` on the clips row
+  cascade-deleted every clip-child table under `PRAGMA foreign_keys=ON`. The
+  legacy children are rebuilt during ingest, so this was invisible until the
+  strata tables (which ingest does NOT rebuild — human annotations included)
+  landed on the same cascade. The clips row is now a true upsert and is never
+  deleted.
+- **Words-less re-analysis wiped word rows** — `ingest_transcript_words`
+  deleted before validating; a re-analysis without transcription (or a mixed
+  report whose words lived only at the top level) silently destroyed
+  previously backfilled rows. Now parses first, preserves existing rows when
+  the incoming report has no words, and falls back per-segment to the
+  top-level words list.
+- **Machine story-beat commits could replace human rows** — the content-hash
+  `beat_uuid` let `INSERT OR REPLACE` overwrite a human beat sharing the same
+  span+label and erased supersede history on identical recommits. Beat rows
+  now get random UUIDs and plain INSERTs; duplicate spans within one commit
+  are skipped and reported.
+- **Dispatch hardening** — stringified numbers from LLM clients no longer
+  crash `strata_query` (TypeError in curve slicing) or silently redirect
+  `timeline_strata` to the latest version; `cut_candidates` rejects
+  non-positive fps instead of ZeroDivisionError; word matches escape SQL LIKE
+  metacharacters; clip bundles fetch every recorded track (gesture_boundary,
+  loudness, custom human tracks) instead of a hardcoded subset; analyzer
+  ffmpeg calls go through the stdio-safe `proc.safe_run`; a broken
+  mediapipe/protobuf install degrades to "face unavailable" instead of
+  crashing `strata_status`.
+
+### Validation
+
+- Full offline suite: 1,418 tests green (17 new regression tests covering the
+  fixes above). Static checks, drift guards, npm pack, and API-parity audit
+  all pass. No live Resolve behavior changed beyond two defensive getter reads
+  (`GetSetting("timelineFrameRate")`, `GetStartFrame()`) at archive time, both
+  try/except-guarded and unit-tested against mock timelines.
+
 ## What's New in v2.60.0
 
 A community bug-fix bundle — three external contributions plus the three issues

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.60.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.61.1-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)
@@ -12,7 +12,7 @@
 
 A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
 
-[![Local control panel](docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
+[![Local control panel](https://raw.githubusercontent.com/samuelgursky/davinci-resolve-mcp/main/docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
 
 A local browser control panel ships with the server for inspecting Resolve state, running source-safe analysis, drilling into analyzed clips and shots, and editing analysis output inline. See the [Control Panel Guide](docs/guides/control-panel.md) for the full tour.
 

package/docs/SKILL.md

@@ -551,8 +551,10 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
 `build_embeddings`, `find_similar`, `detect_entities`, `commit_entities`,
 `list_entities`, `prepare_bin_briefing`, `commit_bin_summary`,
-`detect_shot_relationships`, `commit_shot_relationships`, and
-`list_shot_relationships`.
+`detect_shot_relationships`, `commit_shot_relationships`,
+`list_shot_relationships`, `strata_status`, `backfill_words`, `strata_run`,
+`take_diff`, `cut_candidates`, `strata_query`, `timeline_strata`,
+`plan_story_beats`, `commit_story_beats`, and `list_story_beats`.
 
 **Cross-clip entities + bin briefing v2 (v2.44.0+).** Recurring
 people/places/props across a project's media, found cheaply and confirmed
@@ -596,6 +598,40 @@ no editorial suggestions): `same_setup_as` / `alt_take_of` (symmetric) and
   confirmed `alt_take_of` alternates over raw cosine (the rationale states
   which basis ranked each alternate).
 
+**Perception strata (v2.61.0+, schema v13/v14).** A timecoded track model over
+each analyzed clip — events (pause/breath/hesitation/blink/beat/downbeat/…),
+sampled curves (pitch/vocal_energy/speech_rate/motion_energy/face curves),
+per-word transcript rows, and story beats. Local compute only (ffmpeg + numpy;
+face tier needs opencv + mediapipe); machine re-runs replace their own rows,
+human rows are append-only and always win. These measure and rank — they never
+decide; the editor picks.
+- `strata_status(clip_id?)` — project or per-clip track inventory plus what
+  this machine can run (`analyzer_capabilities`).
+- `strata_run(clip_id, analyzers?)` — run prosody / beat_grid / motion_energy
+  / face on one clip (default: whatever is available locally).
+- `backfill_words()` — promote word timestamps already inside stored report
+  blobs into queryable `transcript_words` rows; idempotent, no re-analysis.
+- `take_diff(clip_a, clip_b, text?)` — align two takes on transcript words
+  and diff their delivery (pace, pauses, pitch, energy). Deltas only, no
+  winner.
+- `cut_candidates(clip_id, time_seconds, window_seconds?, fps?, limit?)` —
+  rank cut frames around an intended joint with human-readable reasons
+  (blink / word-gap / pause / breath / beat / motion); missing tracks are
+  reported, never treated as "no signal".
+- `strata_query(clip_id?, start_seconds?, end_seconds?, match_word?, …)` —
+  one queryable surface: a windowed cross-track bundle for a clip, or a
+  project-wide word find with a joined ±context bundle per hit.
+- `timeline_strata(timeline_name, timeline_version?, …)` — project clip
+  strata through a versioned timeline's recorded placements. Snapshot frames
+  are absolute record frames (start-timecode-inclusive); snapshots from
+  schema v14+ carry the timeline's fps/start frame so placements also get
+  timeline-relative frames and seconds.
+- `plan_story_beats(clip_id)` / `commit_story_beats(clip_id, beats)` /
+  `list_story_beats(clip_id)` — host-LLM pass over the transcript digest
+  (the server never calls an LLM): beats are units of meaning with types
+  (topic/claim/revelation/emotional/anecdote/question/callback), links, and
+  supersede semantics.
+
 **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/install.md

@@ -64,6 +64,14 @@ The installer can automatically configure any of these clients:
 
 You can configure multiple clients at once, or use `--clients manual` to get copy-paste config snippets.
 
+For [Autohand Code](https://github.com/autohandai/code-cli/), register the managed launcher after setup:
+
+```bash
+autohand mcp add davinci-resolve npx davinci-resolve-mcp server
+```
+
+Autohand adds npx's `-y` flag automatically. Add `--scope project` after `mcp add` to keep the registration in the current workspace.
+
 ### Installer Options
 
 ```bash

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 18 missing capabilities, 11 bugs / unreliable behaviors.
+**Totals:** 19 missing capabilities, 11 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -134,6 +134,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Position clips with AppendToTimeline clipInfo recordFrame, or perform insert/overwrite/replace edits in the Resolve UI.
 - **Tags:** missing-method, timeline, edit
 
+### Render in Place / bake a timeline clip to new media
+
+- **Object:** `Timeline / TimelineItem / MediaPool`
+- **Behavior:** There is no scripting method for the Edit-page clip context-menu action 'Render in Place', which bakes a clip (including its Fusion composition and effects) into a NEW rendered media file and drops that file back on the timeline at the same position, replacing the source clip. No Render*/Bake*/Freeze* method exists on Timeline, TimelineItem or MediaPool in the Resolve scripting API reference (BMD docs) or a dir() audit. NOTE the frequently-confused-but-distinct sibling: the render *cache* (a temporary, non-destructive cache of a clip's Color/Fusion output that reduces playback load WITHOUT creating a new media file) IS scriptable — TimelineItem.SetColorOutputCache / SetFusionOutputCache ('Render Cache Color/Fusion Output' menu actions) and Graph.SetNodeCacheMode. Render in Place is the permanent, media-producing bake; the render cache is the transient one.
+- **Workaround / current handling:** If the goal is only to reduce playback/render load, use the render cache — exposed as timeline_item get_color_cache/set_color_cache/get_fusion_cache/set_fusion_cache and the Color-page graph node cache_mode (no new media, fully reversible). If you genuinely need a baked media file, render the clip's in/out range from the Deliver page (proj.AddRenderJob with MarkIn/MarkOut) and relink/append the result yourself, or run Render in Place from the Resolve UI. There is no one-call API equivalent. See issue #86.
+- **Reference:** [issue #86](https://github.com/samuelgursky/davinci-resolve-mcp/issues/86)
+- **Tags:** missing-method, timeline, render, cache, render-in-place, bake
+
 ### Smart Bins / Power Bins creation
 
 - **Object:** `MediaPool`

package/install.py

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

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.60.0"
+VERSION = "2.61.1"
 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.60.0"
+VERSION = "2.61.1"
 
 import base64
 import os
@@ -16680,6 +16680,40 @@ def media_pool_item_markers(action: str, params: Optional[Dict[str, Any]] = None
 # TOOL 15: media_analysis
 # ═══════════════════════════════════════════════════════════════════════════════
 
+_STRATA_CLIP_REF_KEYS = (
+    "clip_id", "clipId", "clip_uuid", "clipUuid",
+    "clip_dir", "clipDir", "file_path", "filePath",
+)
+
+
+def _strata_clip_ref(p: Dict[str, Any]) -> Any:
+    """The clip ref from any accepted alias — one place, so aliases can't drift
+    between action handlers."""
+    for key in _STRATA_CLIP_REF_KEYS:
+        value = p.get(key)
+        if value:
+            return value
+    return None
+
+
+def _opt_number(value: Any) -> Optional[float]:
+    """Coerce int/float/numeric-string to float; anything else → None.
+
+    LLM clients routinely stringify numbers; params must not crash (or be
+    silently dropped) because "12.5" arrived instead of 12.5.
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
 @mcp.tool()
 async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, ctx: Optional[Context] = None) -> Dict[str, Any]:
     """Project-scoped media analysis and guarded metadata publishing.
@@ -16745,6 +16779,16 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       cancel_batch_job(job_id) -> stop future slices
       resume_batch_job(job_id) -> requeue a canceled or interrupted job
       cleanup_artifacts(frames_only=true) -> remove generated frame artifacts only
+      strata_status(clip_id?) -> perception-strata inventory (events/curves/words/story beats) for the project or one clip
+      backfill_words(analysis_root?) -> promote word timestamps from stored report blobs into transcript_words rows
+      strata_run(clip_id, analyzers?) -> run local strata analyzers (prosody | beat_grid | motion_energy | face) on one clip; default = whatever this machine can run
+      take_diff(clip_a, clip_b, text?) -> align two takes on transcript words and diff their delivery (pace, pauses, pitch, energy) — measures only, never picks
+      cut_candidates(clip_id, time_seconds, window_seconds?, fps?, limit?) -> rank cut frames around an intended joint with reasons (blink/pause/word-gap/breath/beat/motion) — aims, never decides
+      strata_query(clip_id?, start_seconds?, end_seconds?, match_word?, context_seconds?, include_curve_values?, limit?) -> cross-track window bundle for a clip, or project-wide word find with joined context per hit
+      timeline_strata(timeline_name, timeline_version?, record_start_frame?, record_end_frame?, fps?) -> project clip strata through a timeline's recorded placements (whole-clip bundles; frames are absolute record frames incl. start-timecode offset; fps defaults to the snapshot's stored value; source-offset mapping needs the live item)
+      plan_story_beats(clip_id) -> timecoded transcript digest + prosody evidence + JSON schema for the host model to segment into story beats (no LLM call server-side)
+      commit_story_beats(clip_id, beats, source_model?) -> validate + persist host-produced story beats; machine commits supersede machine rows only, human rows always win
+      list_story_beats(clip_id) -> current (non-superseded) story beats for a clip
 
     Analysis outputs stay under a davinci-resolve-mcp-analysis project root
     and are validated so they are never written beside source media. Executed
@@ -17043,6 +17087,17 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "detect_shot_relationships",
         "commit_shot_relationships",
         "list_shot_relationships",
+        # Perception strata (schema v13) — timecoded track model.
+        "strata_status",
+        "backfill_words",
+        "strata_run",
+        "take_diff",
+        "cut_candidates",
+        "strata_query",
+        "timeline_strata",
+        "plan_story_beats",
+        "commit_story_beats",
+        "list_story_beats",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -17102,6 +17157,119 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         if action == "db_ingest":
             from src.utils import analysis_store
             return analysis_store.ingest_project(project_root)
+        # Perception strata (schema v13).
+        if action == "strata_status":
+            from src.utils import strata, strata_analyzers
+            clip_ref = _strata_clip_ref(p)
+            status = strata.strata_status(project_root, clip_ref)
+            if status.get("success") and clip_ref is None:
+                status["analyzer_capabilities"] = strata_analyzers.capabilities()
+            return status
+        if action == "backfill_words":
+            from src.utils import strata
+            return strata.backfill_transcript_words(project_root)
+        if action == "strata_run":
+            from src.utils import strata_analyzers
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("strata_run requires clip_id (or clip_uuid / clip_dir / file_path)")
+            analyzers = p.get("analyzers") or p.get("analyzer")
+            if isinstance(analyzers, str):
+                analyzers = [analyzers]
+            return strata_analyzers.run_analyzers(project_root, clip_ref, analyzers)
+        if action == "take_diff":
+            from src.utils import strata_queries
+            clip_a = p.get("clip_a") or p.get("clipA") or p.get("take_a") or p.get("takeA")
+            clip_b = p.get("clip_b") or p.get("clipB") or p.get("take_b") or p.get("takeB")
+            if not clip_a or not clip_b:
+                return _err("take_diff requires clip_a and clip_b")
+            return strata_queries.take_diff(project_root, clip_a, clip_b, text=p.get("text") or p.get("line"))
+        if action == "cut_candidates":
+            from src.utils import strata_queries
+            clip_ref = _strata_clip_ref(p)
+            t = _opt_number(p.get("time_seconds", p.get("timeSeconds")))
+            if not clip_ref or t is None:
+                return _err("cut_candidates requires clip_id and a numeric time_seconds")
+            fps_raw = p.get("fps")
+            fps = _opt_number(fps_raw)
+            if fps_raw is not None and fps is None:
+                return _err(f"fps must be a number, got {fps_raw!r}")
+            return strata_queries.cut_candidates(
+                project_root,
+                clip_ref,
+                t,
+                window_seconds=_opt_number(p.get("window_seconds", p.get("windowSeconds"))) or 0.35,
+                fps=fps,
+                limit=int(_opt_number(p.get("limit")) or 7),
+            )
+        if action == "strata_query":
+            from src.utils import strata_queries
+            start_raw = p.get("start_seconds", p.get("startSeconds"))
+            end_raw = p.get("end_seconds", p.get("endSeconds"))
+            start = _opt_number(start_raw)
+            end = _opt_number(end_raw)
+            if (start_raw is not None and start is None) or (end_raw is not None and end is None):
+                return _err("start_seconds/end_seconds must be numbers")
+            return strata_queries.strata_query(
+                project_root,
+                clip_ref=_strata_clip_ref(p),
+                start_seconds=start,
+                end_seconds=end,
+                match_word=p.get("match_word") or p.get("matchWord") or p.get("word"),
+                context_seconds=_opt_number(p.get("context_seconds", p.get("contextSeconds"))) or 2.0,
+                include_curve_values=bool(p.get("include_curve_values", p.get("includeCurveValues", False))),
+                limit=int(_opt_number(p.get("limit")) or 20),
+            )
+        if action == "timeline_strata":
+            from src.utils import strata_queries
+            timeline_name = p.get("timeline_name") or p.get("timelineName") or p.get("timeline")
+            if not timeline_name:
+                return _err("timeline_strata requires timeline_name")
+            version_raw = p.get("timeline_version", p.get("timelineVersion"))
+            version = _opt_number(version_raw)
+            if version_raw is not None and version is None:
+                return _err(f"timeline_version must be an integer, got {version_raw!r}")
+            fps_raw = p.get("fps")
+            fps = _opt_number(fps_raw)
+            if fps_raw is not None and fps is None:
+                return _err(f"fps must be a number, got {fps_raw!r}")
+            start_frame = _opt_number(p.get("record_start_frame", p.get("recordStartFrame")))
+            end_frame = _opt_number(p.get("record_end_frame", p.get("recordEndFrame")))
+            return strata_queries.timeline_strata(
+                project_root,
+                str(timeline_name),
+                timeline_version=int(version) if version is not None else None,
+                record_start_frame=int(start_frame) if start_frame is not None else None,
+                record_end_frame=int(end_frame) if end_frame is not None else None,
+                fps=fps,
+                include_curve_values=bool(p.get("include_curve_values", p.get("includeCurveValues", False))),
+            )
+        if action == "plan_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("plan_story_beats requires clip_id")
+            return strata_story.plan_story_beats(project_root, clip_ref)
+        if action == "commit_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("commit_story_beats requires clip_id")
+            beats = p.get("beats")
+            if beats is None:
+                return _err("commit_story_beats requires beats")
+            return strata_story.commit_story_beats(
+                project_root,
+                clip_ref,
+                beats,
+                source_model=p.get("source_model") or p.get("sourceModel"),
+            )
+        if action == "list_story_beats":
+            from src.utils import strata_story
+            clip_ref = _strata_clip_ref(p)
+            if not clip_ref:
+                return _err("list_story_beats requires clip_id")
+            return strata_story.list_story_beats(project_root, clip_ref)
         # Phase B — deep shot-level vision tier.
         if action == "deepen":
             from src.utils import deep_vision
@@ -17660,6 +17828,16 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "detect_shot_relationships",
         "commit_shot_relationships",
         "list_shot_relationships",
+        "strata_status",
+        "backfill_words",
+        "strata_run",
+        "take_diff",
+        "cut_candidates",
+        "strata_query",
+        "timeline_strata",
+        "plan_story_beats",
+        "commit_story_beats",
+        "list_story_beats",
         "get_caps",
         "set_caps_preset",
         "get_usage",

package/src/utils/analysis_store.py

@@ -200,6 +200,45 @@ def resolve_clip_uuid(conn: sqlite3.Connection, ref: Any) -> Optional[str]:
     return None
 
 
+def resolve_clip_uuid_ingesting(
+    project_root: str, conn: sqlite3.Connection, clip_ref: Any
+) -> Optional[str]:
+    """resolve_clip_uuid plus the pre-v9 fallback: when the DB has no rows
+    for the ref, walk clips/*/analysis.json for a matching report and ingest
+    it. Shared by deep_vision and the strata layers so a clip that resolves
+    for one resolves for all."""
+    clip_uuid = resolve_clip_uuid(conn, clip_ref)
+    if clip_uuid:
+        return clip_uuid
+    ma = _ma()
+    clips_root = os.path.join(project_root, "clips")
+    candidate = str(clip_ref or "")
+    if not os.path.isdir(clips_root):
+        return None
+    for entry in sorted(os.listdir(clips_root)):
+        report_path = os.path.join(clips_root, entry, "analysis.json")
+        if not os.path.isfile(report_path):
+            continue
+        try:
+            with open(report_path, "r", encoding="utf-8") as handle:
+                report = json.load(handle)
+        except (OSError, json.JSONDecodeError):
+            continue
+        clip_block = report.get("clip") or {}
+        if candidate not in (
+            entry,
+            str(clip_block.get("clip_id") or ""),
+            str(clip_block.get("media_id") or ""),
+            ma.normalize_path(clip_block.get("file_path") or ""),
+        ):
+            continue
+        ingest = ingest_report(project_root, report, clip_dir=os.path.join(clips_root, entry))
+        if ingest.get("success"):
+            return str(ingest["clip_uuid"])
+        return None
+    return None
+
+
 # ── ingest ────────────────────────────────────────────────────────────────────
 
 
@@ -335,9 +374,15 @@ def ingest_report(
             "SELECT created_at FROM clips WHERE clip_uuid = ?", (clip_uuid,)
         ).fetchone()
         created_at = str(existing["created_at"]) if existing else now
+        # True upsert — never INSERT OR REPLACE: REPLACE deletes the existing
+        # row first, and with PRAGMA foreign_keys=ON that cascade-deletes every
+        # child table (events/curves/transcript_words/story_beats included),
+        # wiping strata rows — human annotations among them — on every
+        # re-ingest. The v13 strata tables are NOT rebuilt by ingest, so the
+        # clips row must be updated in place.
         conn.execute(
             """
-            INSERT OR REPLACE INTO clips
+            INSERT INTO clips
                 (clip_uuid, clip_dir, resolve_clip_id, media_id, clip_name,
                  file_path, bin_path, duration_seconds, fps, resolution,
                  media_type, summary, overall_motion_level, cut_count,
@@ -345,6 +390,28 @@ def ingest_report(
                  analyzed_at, vision_status, vision_committed_at,
                  created_at, updated_at)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(clip_uuid) DO UPDATE SET
+                clip_dir=excluded.clip_dir,
+                resolve_clip_id=excluded.resolve_clip_id,
+                media_id=excluded.media_id,
+                clip_name=excluded.clip_name,
+                file_path=excluded.file_path,
+                bin_path=excluded.bin_path,
+                duration_seconds=excluded.duration_seconds,
+                fps=excluded.fps,
+                resolution=excluded.resolution,
+                media_type=excluded.media_type,
+                summary=excluded.summary,
+                overall_motion_level=excluded.overall_motion_level,
+                cut_count=excluded.cut_count,
+                shot_count=excluded.shot_count,
+                analysis_version=excluded.analysis_version,
+                depth=excluded.depth,
+                signature_hash=excluded.signature_hash,
+                analyzed_at=excluded.analyzed_at,
+                vision_status=excluded.vision_status,
+                vision_committed_at=excluded.vision_committed_at,
+                updated_at=excluded.updated_at
             """,
             (
                 clip_uuid,
@@ -473,6 +540,12 @@ def ingest_report(
                 ),
             )
 
+        # Word-level timestamps (v13): promote segments[*].words to rows so
+        # word-boundary queries never have to parse the report blob.
+        from src.utils import strata as _strata
+
+        words_written = _strata.ingest_transcript_words(conn, clip_uuid, transcription)
+
         # Sampled frames. Shot mapping uses frame_indices_used when present,
         # with a time-containment fallback (some commit paths don't record
         # which frame indices fed which shot).
@@ -576,6 +649,7 @@ def ingest_report(
         "shot_count": len(shot_entries),
         "subjective_fields_written": subj_written,
         "subjective_fields_preserved_human": subj_skipped_human,
+        "transcript_words_written": words_written,
     }
 
 

package/src/utils/api_truth.py

@@ -355,6 +355,38 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["missing-method", "timeline", "edit"],
         "submit": "missing",
     },
+    {
+        "symbol": "Render in Place / bake a timeline clip to new media",
+        "object": "Timeline / TimelineItem / MediaPool",
+        "reality": "There is no scripting method for the Edit-page clip "
+                   "context-menu action 'Render in Place', which bakes a clip "
+                   "(including its Fusion composition and effects) into a NEW "
+                   "rendered media file and drops that file back on the timeline "
+                   "at the same position, replacing the source clip. No "
+                   "Render*/Bake*/Freeze* method exists on Timeline, TimelineItem "
+                   "or MediaPool in the Resolve scripting API reference (BMD docs) "
+                   "or a dir() audit. NOTE the frequently-confused-but-distinct "
+                   "sibling: the render *cache* (a temporary, non-destructive "
+                   "cache of a clip's Color/Fusion output that reduces playback "
+                   "load WITHOUT creating a new media file) IS scriptable — "
+                   "TimelineItem.SetColorOutputCache / SetFusionOutputCache "
+                   "('Render Cache Color/Fusion Output' menu actions) and "
+                   "Graph.SetNodeCacheMode. Render in Place is the permanent, "
+                   "media-producing bake; the render cache is the transient one.",
+        "recommended": "If the goal is only to reduce playback/render load, use "
+                       "the render cache — exposed as timeline_item "
+                       "get_color_cache/set_color_cache/get_fusion_cache/"
+                       "set_fusion_cache and the Color-page graph node cache_mode "
+                       "(no new media, fully reversible). If you genuinely need a "
+                       "baked media file, render the clip's in/out range from the "
+                       "Deliver page (proj.AddRenderJob with MarkIn/MarkOut) and "
+                       "relink/append the result yourself, or run Render in Place "
+                       "from the Resolve UI. There is no one-call API equivalent. "
+                       "See issue #86.",
+        "tags": ["missing-method", "timeline", "render", "cache", "render-in-place", "bake"],
+        "submit": "missing",
+        "issue": 86,
+    },
     {
         "symbol": "Smart Bins / Power Bins creation",
         "object": "MediaPool",