@ossclip/core 0.1.18 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -22,6 +22,20 @@ export {
 // lineDirection is a VALUE export but stays browser-safe: captions.ts
 // imports types only. CaptionTrack needs it at render time (Urdu field test
 // 2026-08-05 — RTL lines were laying out LTR).
-export { lineDirection, type CaptionLine, type CaptionWord } from "./captions";
-export type { KeptSpan } from "./timemap";
+// `backfillSrcStart` rides along for the same reason: the EDITOR is the load
+// path that has to repair a pre-§137 render-props.json before anything derives
+// a caption key from it (§137), and the editor imports this surface. Pure, and
+// captions.ts stays browser-safe — it imports types plus timemap, which is
+// itself type-only against ./schema.
+export {
+  backfillSrcStart,
+  lineDirection,
+  type CaptionLine,
+  type CaptionWord,
+} from "./captions";
+// `mapFromKeptSpans` is a VALUE export and browser-safe (timemap.ts imports
+// types only). The editor's load-path repair needs the MAP, not the raw span
+// array, to decide whether a repair is possible at all — see
+// `anchorCaptionLines` (§137): a non-empty array can still build an empty map.
+export { mapFromKeptSpans, TimeMap, type KeptSpan } from "./timemap";
 export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";

package/src/captions.ts

@@ -1,11 +1,23 @@
 import type { Transcript, Word } from "./schema";
-import type { TimeMap } from "./timemap";
+import { mapFromKeptSpans, type KeptSpan, type TimeMap } from "./timemap";
 
-/** Caption timing lives in OUTPUT time — captions never know about cuts. */
+/**
+ * Caption *timing* lives in OUTPUT time: `start`/`end` are what the renderer
+ * draws against and they know nothing about cuts. `srcStart` is the deliberate
+ * exception (§137) — it is SOURCE time, carried so a re-cut cannot move it.
+ * Never read it as an output instant.
+ */
 export interface CaptionWord {
   text: string;
   start: number;
   end: number;
+  /**
+   * The word's start in SOURCE seconds (§137). `start`/`end` above are OUTPUT
+   * times and a re-cut moves them; this does not, which is what lets a caption
+   * edit survive one. The field the edit layer keys on — see
+   * `captionKeyFor` in overrides.ts.
+   */
+  srcStart: number;
 }
 
 export interface CaptionLine {
@@ -14,6 +26,52 @@ export interface CaptionLine {
   end: number;
 }
 
+/**
+ * Fill in `srcStart` for caption lines read back from a `render-props.json`
+ * written before the field existed (§137).
+ *
+ * The type promises `srcStart` on every word, but the on-disk format predates
+ * it and there is no schema at that boundary — the editor loads render props
+ * as an unvalidated cast — so lines that TYPECHECK as `CaptionLine` can still
+ * arrive with the field missing. Without this, every legacy word would key on
+ * the same absent value and a retype would anchor to the wrong word: the exact
+ * failure the source anchor exists to prevent, arriving silently instead of as
+ * a crash.
+ *
+ * It is recoverable because the same file still carries `spans`: the word's
+ * output start projected back through the map those spans describe. That is a
+ * BEST-EFFORT recovery, not an inverse — exact for a word whose start survived
+ * the cut uncut, approximate in two cases the file no longer records:
+ *  - at a seam (`outOut_k === outIn_{k+1}`) an output instant has two source
+ *    preimages and `toSource` returns the earlier one (`timemap.ts:21-23`), so
+ *    a word that truly began at `srcIn_{k+1}` lands on the far side of the cut;
+ *  - a word whose start fell INSIDE a removed span was clamped to the nearest
+ *    kept edge by `toOutputClamped` when the file was written, so its source
+ *    instant is simply gone and backfill returns the edge.
+ * Both are the best the data on disk supports — the alternative is no anchor at
+ * all. Words written with a real `srcStart` are never re-derived this way.
+ * Pure — the caller owns reading the file.
+ */
+export function backfillSrcStart(
+  lines: readonly CaptionLine[],
+  spans: readonly KeptSpan[],
+): CaptionLine[] {
+  /** The shape a legacy file actually holds, versus the one the type promises. */
+  type LegacyWord = Omit<CaptionWord, "srcStart"> & { srcStart?: number };
+  const legacy = (line: CaptionLine) => line.words as readonly LegacyWord[];
+  // Nothing to recover from a file already written with the field — and an
+  // existing `srcStart` is never recomputed, because the map that produced it
+  // may not be the one in `spans`.
+  if (lines.every((l) => legacy(l).every((w) => w.srcStart !== undefined))) return [...lines];
+  const map = mapFromKeptSpans(spans);
+  return lines.map((line) => ({
+    ...line,
+    words: legacy(line).map((w) =>
+      w.srcStart === undefined ? { ...w, srcStart: map.toSource(w.start) } : (w as CaptionWord),
+    ),
+  }));
+}
+
 /**
  * Per-LINE direction from the text itself — the first-strong-character
  * heuristic (Unicode UAX #9 rules P2/P3), not the transcript's language
@@ -65,7 +123,9 @@ export function buildCaptionLines(
   const mapped: CaptionWord[] = [];
   for (const w of transcript.words) {
     const m = map.mapWord(w as Word);
-    if (m) mapped.push({ text: w.text, start: m.start, end: m.end });
+    // `w.start` is source time, `m.start` output — both are needed, and only
+    // the source one is stable across a re-cut (§137).
+    if (m) mapped.push({ text: w.text, start: m.start, end: m.end, srcStart: w.start });
   }
 
   const lines: CaptionLine[] = [];

package/src/export-fcpxml.ts

@@ -0,0 +1,112 @@
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Production, Segment } from "./schema";
+
+/**
+ * FCPXML 1.10 marker export — the file format half of `ossclip analyse`
+ * (next-directions §2; design doc 2026-08-12-analyse-fcpxml-export-design.md).
+ * Pure by the house split: Production in, XML string out; the CLI owns the
+ * file write. The document is a project whose single asset-clip is the
+ * ORIGINAL source with one named marker per planned cut — markers, not
+ * applied cuts, because an editor wants to REVIEW "dead air here / blooper
+ * here" before acting on it, and both Resolve and Premiere read this format.
+ *
+ * No marker colours, resolved deliberately: stock FCPXML `<marker>` carries
+ * no colour attribute, and colour does not reliably survive a Resolve round
+ * trip — so the cut REASON travels in the marker name (the report.txt
+ * vocabulary), which every importer displays.
+ */
+
+/** A frame's duration as an exact rational — FCPXML's own time currency. */
+export interface FrameDuration {
+  num: number;
+  den: number;
+}
+
+/**
+ * NTSC rates have no integer-denominator form — 29.97 is exactly 30000/1001,
+ * and ffprobe reports it as a float that equals neither 29.97 nor the
+ * rational. Matched by tolerance for that reason; anything else is treated
+ * as the integer rate it rounds to.
+ */
+const NTSC_RATES: Array<{ fps: number; fd: FrameDuration }> = [
+  { fps: 24000 / 1001, fd: { num: 1001, den: 24000 } },
+  { fps: 30000 / 1001, fd: { num: 1001, den: 30000 } },
+  { fps: 60000 / 1001, fd: { num: 1001, den: 60000 } },
+];
+
+export function fpsToFrameDuration(fps: number): FrameDuration {
+  for (const { fps: ntsc, fd } of NTSC_RATES) {
+    if (Math.abs(fps - ntsc) < 0.01) return fd;
+  }
+  return { num: 1, den: Math.round(fps) };
+}
+
+/**
+ * A seconds value as a frame-aligned FCPXML rational (`"53/30s"`). A float
+ * like `1.77s` is legal FCPXML but frame-misaligned, and importers round it
+ * silently — quantizing here keeps the marker on the frame the report named,
+ * with the rounding visible in this codebase instead of implicit in theirs.
+ */
+export function quantizeToFrame(seconds: number, fd: FrameDuration): string {
+  const frames = Math.round((seconds * fd.den) / fd.num);
+  return `${frames * fd.num}/${fd.den}s`;
+}
+
+function esc(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/** The report.txt line, minus the timestamps the marker position already is. */
+function markerName(seg: Segment): string {
+  const dur = (seg.srcOut - seg.srcIn).toFixed(2);
+  const conf = seg.confidence !== undefined ? ` (conf ${seg.confidence.toFixed(2)})` : "";
+  return `${seg.reason ?? "cut"} −${dur}s${conf}`;
+}
+
+export function buildFcpxmlMarkers(production: Production): string {
+  const { path, probe } = production.source;
+  const fd = fpsToFrameDuration(probe.fps);
+  const dur = quantizeToFrame(probe.duration, fd);
+  const name = basename(path);
+  const removals = (production.cutlist ?? []).filter((s) => s.kind === "remove");
+  const markers = removals
+    .map(
+      (s) =>
+        `            <marker start="${quantizeToFrame(s.srcIn, fd)}" ` +
+        `duration="${fd.num}/${fd.den}s" value="${esc(markerName(s))}"/>`,
+    )
+    .join("\n");
+  // pathToFileURL, not string concat: it percent-encodes the characters a
+  // URL cannot carry (spaces, #) while the XML escaping below handles the
+  // ones an ATTRIBUTE cannot (&) — two encodings, two owners.
+  const srcUrl = esc(pathToFileURL(path).href);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE fcpxml>
+<fcpxml version="1.10">
+  <resources>
+    <format id="r1" frameDuration="${fd.num}/${fd.den}s" width="${probe.width}" height="${probe.height}"/>
+    <asset id="r2" name="${esc(name)}" start="0/${fd.den}s" duration="${dur}" hasVideo="1" hasAudio="${probe.hasAudio ? 1 : 0}" format="r1">
+      <media-rep kind="original-media" src="${srcUrl}"/>
+    </asset>
+  </resources>
+  <library>
+    <event name="ossclip">
+      <project name="${esc(`${name} — ossclip markers`)}">
+        <sequence format="r1" duration="${dur}" tcStart="0/${fd.den}s">
+          <spine>
+            <asset-clip ref="r2" offset="0/${fd.den}s" name="${esc(name)}" start="0/${fd.den}s" duration="${dur}" format="r1">
+${markers ? `${markers}\n` : ""}            </asset-clip>
+          </spine>
+        </sequence>
+      </project>
+    </event>
+  </library>
+</fcpxml>
+`;
+}

package/src/index.ts

@@ -27,5 +27,6 @@ export * from "./face";
 export * from "./cover";
 export * from "./source-text";
 export * from "./report";
+export * from "./export-fcpxml";
 export * from "./config";
 export { run } from "./exec";

package/src/overrides.ts

@@ -8,7 +8,7 @@ import {
   type Theme,
 } from "./scene-schema";
 import { resolveSceneProps } from "./scene-registry";
-import type { CaptionLine } from "./captions";
+import type { CaptionLine, CaptionWord } from "./captions";
 
 /**
  * The user's edit layer (SPEC: direct manipulation).
@@ -98,8 +98,8 @@ export const SceneOverrideSchema = z.object({
   /**
    * Vertical centre for this scene's captions (R15 §56). NOT part of the
    * top-level `captions` key — that one is the caption TEXT retype map,
-   * keyed by word index; position is a property of the SCENE, where the
-   * timeline selection can address it and "apply to all" can fan it out.
+   * keyed per word; position is a property of the SCENE, where the timeline
+   * selection can address it and "apply to all" can fan it out.
    */
   captionY: z.number().min(0).max(1).optional(),
   /** Caption size multiplier (R16 §64) — same per-scene, fan-out-able shape
@@ -136,12 +136,13 @@ export type SceneOverride = z.infer<typeof SceneOverrideSchema>;
  * One retyped caption word (PLAN 2026-07-29 Task 7, scope (a) — decided with
  * the author: 1:1 in-place retype, timing untouched).
  *
- * Keyed by the word's position in the caption stream, GUARDED by the text
- * that was there when the edit was made — the same verification-anchor
- * pattern as `AppliedRepair.heard` (§17). Captions are derived (repaired
- * transcript through the TimeMap), so a changed cleanup level or repair set
- * can shift positions; the guard means a stale edit is DROPPED WITH A LOG
- * rather than silently landing on the wrong word.
+ * Keyed by the word's SOURCE time since §137 (`captionKeyFor` below — the
+ * original positional key is what a user cut broke), GUARDED by the text that
+ * was there when the edit was made — the same verification-anchor pattern as
+ * `AppliedRepair.heard` (§17). Captions are derived (repaired transcript
+ * through the TimeMap), so a changed cleanup level or repair set can still
+ * re-word the stream under an anchor that survived; the guard means a stale
+ * edit is DROPPED WITH A LOG rather than silently landing on the wrong word.
  */
 export const CaptionEditSchema = z.object({
   /** The replacement text. */
@@ -162,10 +163,78 @@ export type CaptionEdit = z.infer<typeof CaptionEditSchema>;
  */
 export function captionEditWas(
   captions: Record<string, CaptionEdit>,
-  index: number,
+  key: string,
   seen: string,
 ): string {
-  return captions[String(index)]?.was ?? seen;
+  return captions[key]?.was ?? seen;
+}
+
+/**
+ * The id a pre-§137 split gets when it is upgraded: the output milliseconds of
+ * whatever `at` the file holds NOW.
+ *
+ * Load-bearing for the migration — a saved doc hiding `scene-0@600` should
+ * still match that half after the upgrade — but ONLY for a doc that has not
+ * already been through a re-anchoring produce run, and the distinction is not
+ * cosmetic (final review, Important 3). `at` is the one thing a re-cut moves,
+ * so on a doc the §137 bug already damaged this reproduces the CURRENT time,
+ * not the original: the field workdir's live `overrides.json` holds
+ * `splits: [0]`, mints id `"0"`, and its saved `scene-0@600` matches nothing.
+ * There is no better derivation available — the original ms is genuinely gone
+ * from a re-anchored file, and nothing on disk records it — so the honest
+ * statement is that a doc damaged BEFORE this fix landed cannot recover its
+ * split-half overrides, and only `overrides.json.bak` can (which is why
+ * `produce`'s write gate must not spend it; final review, Critical 2).
+ */
+export function legacySplitId(at: number): string {
+  return String(Math.round(at * 1000));
+}
+
+export const SplitSchema = z.union([
+  // `.finite()` is stated rather than assumed. JSON has no Infinity literal
+  // but an overflowing one (`1e400`) parses to it, and a non-finite `at`
+  // would derive `id: "Infinity"` — one shared name for every such split,
+  // the same garbage-derived-key failure `captionKeyFor` refuses for caption
+  // words. zod v4's `z.number()` already rejects non-finite where v3's did
+  // not, so this is a requirement written down at the site instead of a
+  // default that has already changed once underneath this file.
+  z.object({ at: z.number().finite().nonnegative(), id: z.string().min(1) }),
+  // Legacy: a bare number, upgraded in place so every overrides.json written
+  // before §137 parses and keeps its split-half overrides attached.
+  z.number().finite().nonnegative().transform((at) => ({ at, id: legacySplitId(at) })),
+]);
+export type Split = z.infer<typeof SplitSchema>;
+
+/**
+ * A split id that no split in `existing` already holds.
+ *
+ * Uniqueness is load-bearing (§137): the id is the ONLY thing tying an
+ * override to a split half — `splitCues` names the half `${rootId}@${id}` and
+ * `dropHiddenCues` filters on that exact string — so two splits sharing an id
+ * mint two cues with one name, and deleting one half deletes both, as does
+ * any framing or timing edit on it.
+ *
+ * Decoupling `id` from `at` is what made this reachable. While the id was
+ * recomputed from the time, two ids could only collide if two splits sat
+ * within 0.5ms of each other, which `SPLIT_MIN_PIECE_SEC` forbids. Now a
+ * split minted at 1.2s and re-anchored to 0.6s by a re-cut still holds
+ * `"1200"`, so ⌘B at 1.2s again asks for an id that is taken — and
+ * `addSplit`'s dedupe cannot see it, because that compares `at` and 0.6 is
+ * nowhere near 1.2.
+ *
+ * The suffix is a COUNTER, deliberately, not a nonce or a timestamp: this
+ * value is persisted in the user's `overrides.json` and names a cue, so it
+ * has to be reproducible from the doc alone.
+ */
+export function mintSplitId(at: number, existing: readonly Split[]): string {
+  const base = legacySplitId(at);
+  const taken = new Set(existing.map((s) => s.id));
+  if (!taken.has(base)) return base;
+  // Starts at 2 so the first collision reads as "the second `1200`".
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
 }
 
 export const OverrideDocSchema = z.object({
@@ -185,16 +254,22 @@ export const OverrideDocSchema = z.object({
    */
   captionsHidden: z.boolean().optional(),
   scenes: z.record(z.string(), SceneOverrideSchema).default({}),
-  /** Retyped caption words, keyed by caption-stream word index. */
+  /** Retyped caption words, keyed by the word's source time (§137). */
   captions: z.record(z.string(), CaptionEditSchema).default({}),
   /**
-   * Scene split points in ABSOLUTE output seconds (R16 §61 — Cmd/Ctrl+B at
-   * the playhead). Time-anchored rather than scene-anchored on purpose: a
-   * re-plan can rename or move scenes, and a split is a decision about a
-   * MOMENT of the output. Applied by `splitCues` after the plain fill, so a
-   * split lands on graphic cues and takes alike.
+   * Scene split points. `at` is ABSOLUTE output seconds (R16 §61 — Cmd/Ctrl+B
+   * at the playhead) and moves when a re-cut re-anchors the doc; `id` is
+   * minted once when the split is created and NEVER recomputed (§137). The
+   * split half is named `${rootId}@${id}`, so re-anchoring `at` cannot rename
+   * the half out from under a `hidden` (or any other) override on it — the
+   * bug that resurrected a deleted scene in the field case.
+   *
+   * `at` stays time-anchored rather than scene-anchored on purpose: a re-plan
+   * can rename or move scenes, and WHERE to cut is a decision about a MOMENT
+   * of the output. Applied by `splitCues` after the plain fill, so a split
+   * lands on graphic cues and takes alike.
    */
-  splits: z.array(z.number().nonnegative()).default([]),
+  splits: z.array(SplitSchema).default([]),
   /**
    * User cuts — ranges of the OUTPUT to remove, in the output seconds of the
    * CURRENT render-props (what the user saw when they cut) (PLAN 2026-08-04
@@ -292,8 +367,9 @@ function resolveSwappedProps(
 /**
  * The override entry a cue resolves against: its own, layered over its split
  * ROOT's (R16 §68). A split half is still the same scene — captions scaled
- * on the original must render scaled on both halves — so `id@ms` inherits
- * everything from `id`, with two exceptions that describe the WHOLE original
+ * on the original must render scaled on both halves — so `id@<split id>`
+ * inherits everything from `id` (the suffix is the split's own minted id since
+ * §137, not a time), with two exceptions that describe the WHOLE original
  * rather than a piece of it: `timing` (the root's absolute window would undo
  * the split) and `hidden` (deleting the original is not deleting one half).
  * The half's OWN entry wins key by key, and the record-shaped keys merge
@@ -378,10 +454,14 @@ export const SPLIT_MIN_PIECE_SEC = 0.3;
  * Cut cues at the stored split points (R16 §61).
  *
  * Both halves keep everything but their window; the half STARTING at the
- * split takes the id `${id}@${ms}` — named by its start time, so edits on it
- * stay attached while the split exists, survive further splits of the same
- * original cue, and are reported as orphans (never misapplied) if the split
- * is removed. Runs AFTER `fillPlainCues` so takes split like scenes do, and
+ * split takes the id `${rootId}@${split.id}` — named by the split's OWN
+ * minted id (§137), so edits on it stay attached while the split exists,
+ * survive further splits of the same original cue, and are reported as
+ * orphans (never misapplied) if the split is removed. The id used to be
+ * recomputed from the split's CURRENT start time, which meant a re-cut
+ * re-anchoring `at` renamed the half and orphaned every override on it —
+ * the field case where a deleted scene came back after a 0.6s cut.
+ * Runs AFTER `fillPlainCues` so takes split like scenes do, and
  * BEFORE the final override pass so the halves' own edits (framing, timing,
  * elements) land on them. A split that misses every cue — after a re-plan
  * moved the material — is skipped; the time stays in the doc, harmless.
@@ -389,23 +469,25 @@ export const SPLIT_MIN_PIECE_SEC = 0.3;
  * intro animation (a Sequence restarts at its own frame 0) — acceptable for
  * the feature's real use, cutting takes and re-timing halves.
  */
-export function splitCues(cues: readonly SceneCue[], times: readonly number[]): SceneCue[] {
+export function splitCues(cues: readonly SceneCue[], splits: readonly Split[]): SceneCue[] {
   const out = [...cues];
-  for (const t of [...times].sort((a, b) => a - b)) {
+  for (const s of [...splits].sort((a, b) => a.at - b.at)) {
     const i = out.findIndex(
-      (c) => t >= c.startSec + SPLIT_MIN_PIECE_SEC && t <= c.endSec - SPLIT_MIN_PIECE_SEC,
+      (c) => s.at >= c.startSec + SPLIT_MIN_PIECE_SEC && s.at <= c.endSec - SPLIT_MIN_PIECE_SEC,
     );
     if (i === -1) continue;
     const cue = out[i]!;
     // Derive from the ROOT id, not the (possibly already-split) cue id:
     // `take-0@6000`, never `take-0@3000@6000` — so a half's id depends only
-    // on the original cue and its own start time, and adding an EARLIER
+    // on the original cue and the split that made it, and adding an EARLIER
     // split cannot rename later halves out from under their edits.
     out.splice(
       i,
       1,
-      { ...cue, endSec: t },
-      { ...cue, id: `${cue.id.split("@")[0]}@${Math.round(t * 1000)}`, startSec: t },
+      { ...cue, endSec: s.at },
+      // The suffix comes from the SPLIT's own id, not from `s.at` — that is
+      // the §137 fix.
+      { ...cue, id: `${cue.id.split("@")[0]}@${s.id}`, startSec: s.at },
     );
   }
   return out;
@@ -462,17 +544,396 @@ export function splitThenDropHidden(
   return dropHiddenCues(splitCues(cues, doc.splits), doc);
 }
 
+/**
+ * A caption edit's key: the word's source start, quantised to milliseconds
+ * (§137). Positional indices were the original design and a user cut breaks
+ * them — removing one word shifts every later index, so the `was` guard below
+ * fires on every edit and the user's retypes vanish into the report nobody
+ * printed. Source time is the one property of a word that a re-cut cannot
+ * move.
+ *
+ * THROWS on a non-finite `srcStart` rather than minting `wNaN`. The type
+ * promises a number and `captions.ts:33-39` says outright that the promise is
+ * a lie at the render-props boundary — the editor loads that file as an
+ * unvalidated cast, so a pre-§137 workdir yields words with the field absent.
+ * `w${Math.round(NaN * 1000)}` is `"wNaN"` for EVERY word: one shared anchor
+ * for a whole video, under which a single stored edit would rewrite every word
+ * in it. That is the failure this whole change exists to prevent, arriving
+ * silently. Parse, never coerce — and a loud throw is the parse here, since a
+ * missing anchor has no honest fallback. `backfillSrcStart` (Task 6's load
+ * path) is what keeps legacy files from reaching this.
+ */
+export function captionKeyFor(srcStart: number): string {
+  if (!Number.isFinite(srcStart)) {
+    throw new Error(
+      `captionKeyFor: caption words need a finite srcStart (§137), got ${String(srcStart)} — ` +
+        `run backfillSrcStart on lines read from a pre-§137 render-props.json`,
+    );
+  }
+  return `w${Math.round(srcStart * 1000)}`;
+}
+
+/** A pre-§137 key: a bare non-negative integer, i.e. a caption-word position. */
+export function isLegacyCaptionKey(key: string): boolean {
+  return /^\d+$/.test(key);
+}
+
+/**
+ * The anchor a word carries, or null when it carries none.
+ *
+ * `captionKeyFor` THROWS on a non-finite `srcStart` and should: reaching it
+ * with one is a programmer error. A word that simply has no `srcStart` is a
+ * DATA condition, not a programmer error — the render-props boundary is an
+ * unvalidated cast (`captions.ts:33-39`), so a pre-§137 workdir loads with the
+ * field absent on every word (the editor's own e2e fixture is exactly that,
+ * preserved on purpose). The editor calls `applyCaptionEdits` inside a
+ * render-time `useMemo` with no error boundary above it, so a throw down there
+ * white-screens the whole editor over a file that merely predates the field
+ * (§137 review). Distinguishing the two here keeps the parse loud where it
+ * means something and turns the boundary case into "this word can carry no
+ * edit" — the edits that then find no home are REPORTED (`found: null` /
+ * `unresolved`), which is the honest answer. `backfillSrcStart` on the load
+ * path is what makes these words anchorable again.
+ *
+ * PUBLIC since §137 Task 5, deliberately: the editor needs the same verdict
+ * before it writes an edit, and a second copy of "is this word anchorable"
+ * living in `apps/editor` is how the two would drift apart. Every caller that
+ * holds a word it did not itself construct should come through here rather
+ * than calling `captionKeyFor` — a `useEdits` retype runs in a React event
+ * handler with no error boundary above it, so a throw there is a crash on any
+ * pre-§137 workdir, not a caught parse failure.
+ */
+export function captionAnchorOf(word: CaptionWord | undefined): string | null {
+  if (!word || !Number.isFinite(word.srcStart)) return null;
+  return captionKeyFor(word.srcStart);
+}
+
+/**
+ * How far either side of the stored index the migration will look for `was`
+ * (§137).
+ *
+ * A JUDGEMENT, not a measurement — stated because this is the constant that
+ * decides how much of a user's saved work the one-shot upgrade recovers, and
+ * it shipped with a *what* comment and no *why* (final review, Important 2).
+ * The trade runs in both directions at once: every extra word the scan
+ * considers is another chance that a common word (`the`, `it`) matches by
+ * coincidence, and the ambiguity rule below turns a coincidence into a
+ * REFUSAL. So widening this recovers more far-drifted edits and refuses more
+ * near ones; it is not a free "more is better" dial. Eight words is on the
+ * order of two or three seconds of speech — comfortably past the field case (a
+ * 0.6s trim moved every stored index by one) while still short enough that the
+ * window usually holds a given word once.
+ *
+ * The bound is affordable only because being past it is no longer a LOSS. Such
+ * an edit is reported `out-of-range` — the word is still on screen, merely too
+ * far from where the edit was stored to be sure it is the same one — and both
+ * migration callers carry it through into the doc they keep, so a later run
+ * against a different cut can still place it. Deleting it was the final
+ * review's Critical 1.
+ *
+ * THE TWO MIGRATION PATHS SEE DIFFERENT DRIFT, which is what makes the value
+ * user-visible rather than internal. The editor migrates against the LAST
+ * run's `render-props.json`, and its live preview deliberately never applies
+ * `doc.cuts` (`App.tsx`) — so the positions the doc stored and the positions
+ * it resolves against are the same ones: drift 0, every legacy edit exact-hits
+ * and shows as applied. `produce` migrates against lines built AFTER the
+ * user's new cut, so its drift is the number of caption words that cut
+ * removed. A cut removing more than this many words therefore shows every
+ * retype in the preview and reports them `out-of-range` in the render. Closing
+ * that gap would mean re-implementing the EDL in the browser, which is the one
+ * thing `App.tsx`'s live memo exists to avoid, so the divergence is STATED
+ * rather than fixed — and `out-of-range` plus the write-back's preservation
+ * rule is what keeps it a message instead of vanished work.
+ *
+ * Exported so the report lines can name the bound they hit, and so the
+ * boundary tests are written against the constant rather than against `8`.
+ */
+export const MIGRATION_SEARCH_RADIUS = 8;
+
+/**
+ * WHY an edit could not be migrated. Reported rather than folded into one
+ * message (§137 Task 6 review, Minor 7): each cause needs something different
+ * from the user, and blaming the cut for all of them sends someone looking for
+ * a word that is still sitting on screen.
+ *  - `not-found`: no word here says `was` any more — a cut removed it, or a
+ *    re-plan rewrote it.
+ *  - `out-of-range`: a word here DOES say `was`, but only past
+ *    `MIGRATION_SEARCH_RADIUS` from the stored index. Split out of
+ *    `not-found` (final review, Important 2): the two are the same silence to
+ *    the code and opposite advice to the user — one word is gone, the other is
+ *    sitting on screen untouched, and telling that user "the cut removed it"
+ *    sends them to redo work they can still see.
+ *  - `ambiguous`: several words nearby say `was` and the search cannot tell
+ *    which one the user meant.
+ *  - `unanchorable`: the word IS here, but carries no source time to key on —
+ *    a render-props.json with no usable `spans` to backfill from.
+ *  - `collision`: two legacy edits resolved to the same word; neither can be
+ *    trusted over the other.
+ *  - `superseded`: a legacy edit resolved onto a word an already-source-keyed
+ *    edit holds. The CURRENT-format edit wins and is kept; this is the older
+ *    duplicate being retired, not a loss of the live edit.
+ */
+export type CaptionMigrationReason =
+  | "not-found"
+  | "out-of-range"
+  | "ambiguous"
+  | "unanchorable"
+  | "collision"
+  | "superseded";
+
+export interface CaptionKeyMigration {
+  edits: Record<string, CaptionEdit>;
+  /**
+   * Edits the migration would not commit — reported, never guessed at. Keyed
+   * by their ORIGINAL doc key, which is the only name the user's file knows
+   * them by, and carrying WHY (see `CaptionMigrationReason`).
+   */
+  unresolved: Array<{ key: string; was: string; reason: CaptionMigrationReason }>;
+}
+
+/**
+ * An answer from `resolveCaptionAnchor`: an anchor, or why there is none.
+ * `collision`/`superseded` are excluded because they are not properties of one
+ * edit at all — they need the other claims to be visible first.
+ */
+type AnchorClaim =
+  | { to: string }
+  | { to: null; reason: Exclude<CaptionMigrationReason, "collision" | "superseded"> };
+
+/**
+ * Where one stored edit wants to land, or why it cannot land anywhere.
+ *
+ * Split out of `migrateCaptionKeys` so every edit can be resolved BEFORE any
+ * of them is written: a collision is only visible once both claims exist, and
+ * a function that writes as it goes cannot see the second claim coming.
+ */
+function resolveCaptionAnchor(
+  key: string,
+  edit: CaptionEdit,
+  words: readonly CaptionWord[],
+): AnchorClaim {
+  // Already a source key (or something that is not a position at all) — the
+  // doc's own key stands, and the collision check downstream still applies.
+  if (!isLegacyCaptionKey(key)) return { to: key };
+  const at = Number(key);
+  // The record confirming itself — see `migrateCaptionKeys` for why this
+  // wins ahead of the ambiguity rule rather than through it. A confirmed
+  // position that carries no anchor resolves to NOTHING rather than falling
+  // through to the search: the record already named the word, and letting the
+  // search then pick a same-text word elsewhere would rewrite one the user
+  // did not edit.
+  if (words[at]?.text === edit.was) return anchorOrUnanchorable(words[at]);
+  const matches: number[] = [];
+  for (let d = 1; d <= MIGRATION_SEARCH_RADIUS; d++) {
+    for (const i of [at - d, at + d]) {
+      if (words[i]?.text === edit.was) matches.push(i);
+    }
+  }
+  // Ambiguity is judged on the TEXT matches, before anchors are considered —
+  // an unanchorable candidate still means the search could not tell two words
+  // apart, so it must not silently narrow the field to one.
+  if (matches.length === 0) {
+    // Nothing WITHIN the radius — but that is two different facts, and they
+    // owe the user opposite advice (final review, Important 2). A full scan
+    // (only ever on the failure path, so it costs nothing on a healthy doc)
+    // separates "the cut removed this word" from "the word is right there,
+    // further from the stored index than the search is willing to trust". The
+    // second is not re-anchored — past the radius the position record has been
+    // proven wrong by too much for a lone text match to stand in for it — but
+    // it is REPORTED as what it is, and the callers keep the edit in the doc
+    // so a later run can still place it.
+    const elsewhere = words.some((w) => w.text === edit.was);
+    return { to: null, reason: elsewhere ? "out-of-range" : "not-found" };
+  }
+  if (matches.length > 1) return { to: null, reason: "ambiguous" };
+  return anchorOrUnanchorable(words[matches[0]!]);
+}
+
+/** The word was FOUND; whether it can be keyed on is a separate question. */
+function anchorOrUnanchorable(word: CaptionWord | undefined): AnchorClaim {
+  const anchor = captionAnchorOf(word);
+  return anchor === null ? { to: null, reason: "unanchorable" } : { to: anchor };
+}
+
+/**
+ * Upgrade pre-§137 positional keys to source-time keys.
+ *
+ * Position first, and an exact position hit WINS OUTRIGHT — it is not a
+ * guess. The stored index is the position the editor recorded when the user
+ * made the edit, and `was` matching the word now sitting there is that record
+ * confirming itself: two independent facts agreeing. The same word appearing
+ * elsewhere nearby weakens neither, so the ambiguity rule below deliberately
+ * does NOT gate this branch (ruling on the §137 plan, task 2: folding the
+ * exact hit into the candidate scan makes a confirmed record lose to an
+ * unrelated coincidence, and a doc that never drifted at all would stop
+ * migrating because the user happened to edit a repeated word — that breaks
+ * "every existing overrides.json keeps working" for a case where we have the
+ * answer).
+ *
+ * When the word at that position is NOT the edit's `was`, the position has
+ * been PROVEN wrong (a cut removed words before it), so search outward for
+ * the `was`: that recovers the field case rather than discarding work the
+ * user already did. Ambiguity gates that search alone — two candidates a
+ * search genuinely cannot tell apart are reported instead, because a wrong
+ * anchor silently rewrites the wrong word, which is worse than an edit the
+ * user has to redo.
+ *
+ * TWO LEGACY EDITS RESOLVING TO THE SAME WORD are that same ambiguity one
+ * level up, and both go to `unresolved` — the output is a Record, so writing as
+ * we went would have the second edit silently overwrite the first and report
+ * nothing, which is the very bug this task was opened for. It is not a corner
+ * case:
+ *  - an outward search can land on the word another edit exact-hit (`the cat
+ *    sat on a mat`, edits at "0" and "5", both `was: "the"`);
+ *  - two words can share a `srcStart` outright — `backfillSrcStart`
+ *    (`captions.ts:44-50`) maps seam preimages and cut-clamped words onto the
+ *    same source instant BY DESIGN, so duplicate keys are manufactured, not
+ *    float trivia.
+ * Neither edit is guessed at, both are named, and the user can re-apply the
+ * one they meant.
+ *
+ * A LEGACY EDIT COLLIDING WITH AN ALREADY-SOURCE-KEYED ONE is NOT that case,
+ * and refusing both was a real bug (§137 Task 6 review, Important 3): a doc
+ * holding both key spaces at once — `{"0": …, "w6000": …}` over one word — is
+ * the normal shape of any project edited before and after this change, and
+ * treating it as an unbreakable tie DELETED the newer, current-format edit
+ * whose anchor was never in doubt. The source-keyed edit WINS: it is the one
+ * the editor wrote most recently, it names its word directly rather than by a
+ * position something may have shifted, and it is the format everything else
+ * reads. Only the legacy claim is retired, reported as `superseded`. (There
+ * can be at most one source-keyed claimant per anchor: such a claim resolves
+ * to its own key, and a Record cannot hold one key twice.)
+ */
+export function migrateCaptionKeys(
+  edits: Record<string, CaptionEdit>,
+  lines: readonly CaptionLine[],
+): CaptionKeyMigration {
+  const words = lines.flatMap((l) => l.words);
+  const out: Record<string, CaptionEdit> = {};
+  const unresolved: CaptionKeyMigration["unresolved"] = [];
+
+  // Resolve every edit first, write second — see the collision paragraph.
+  const claims = Object.entries(edits).map(([key, edit]) => ({
+    key,
+    edit,
+    legacy: isLegacyCaptionKey(key),
+    claim: resolveCaptionAnchor(key, edit, words),
+  }));
+  type Claim = (typeof claims)[number];
+  const claimants = new Map<string, Claim[]>();
+  for (const c of claims) {
+    if (c.claim.to === null) continue;
+    const rivals = claimants.get(c.claim.to);
+    if (rivals) rivals.push(c);
+    else claimants.set(c.claim.to, [c]);
+  }
+
+  for (const c of claims) {
+    if (c.claim.to === null) {
+      unresolved.push({ key: c.key, was: c.edit.was, reason: c.claim.reason });
+      continue;
+    }
+    const rivals = claimants.get(c.claim.to)!;
+    // Identity, not `.key` — the winner has to be THIS claim object, or a
+    // second claimant would write itself in over the one that already won.
+    const winner = rivals.length === 1 ? rivals[0]! : rivals.find((r) => !r.legacy);
+    if (winner === c) {
+      out[c.claim.to] = c.edit;
+      continue;
+    }
+    unresolved.push({
+      key: c.key,
+      was: c.edit.was,
+      // `winner` undefined means every claimant was legacy: a genuine tie.
+      reason: winner === undefined ? "collision" : "superseded",
+    });
+  }
+  return { edits: out, unresolved };
+}
+
+/**
+ * The caption map to KEEP after a migration: everything it placed, plus every
+ * edit it would not place, left exactly as the user's file holds it.
+ *
+ * `migration.edits` alone is what both callers wrote back at first, and it is
+ * a DELETE (final review, Critical 1): an edit produce cannot anchor this run
+ * may well be anchorable the next one — a different cut, re-planned lines, or
+ * simply a `MIGRATION_SEARCH_RADIUS` the drift no longer exceeds — and
+ * dropping it forecloses that, permanently, on a run the user only asked to
+ * render. Nobody asked for a delete. An unresolved key left in the doc costs
+ * nothing: it addresses no word, so it applies to nothing, and it is reported
+ * by name on every run. That was the pre-§137 status quo for a stale key and
+ * it is the right one.
+ *
+ * `superseded` is the ONE retirement, and it is not a loss: a newer
+ * source-keyed edit already covers that word (see `migrateCaptionKeys`), so
+ * keeping the older legacy duplicate would re-report the same collision on
+ * every run forever with nothing the user could do about it.
+ *
+ * Preserved keys cannot collide with placed ones — a preserved key is legacy
+ * (`/^\d+$/`, since a source key always resolves to itself and wins its
+ * anchor) and a placed key is always `w<ms>`. `before` must have been through
+ * `OverrideDocSchema`, for the `"__proto__"` reason `migrateCaptionKeys`
+ * states.
+ */
+export function captionEditsToKeep(
+  before: Record<string, CaptionEdit>,
+  migration: CaptionKeyMigration,
+): Record<string, CaptionEdit> {
+  const out: Record<string, CaptionEdit> = { ...migration.edits };
+  for (const u of migration.unresolved) {
+    if (u.reason === "superseded") continue;
+    const edit = before[u.key];
+    // Unreachable — `unresolved` is built from `before`'s own entries — but
+    // this is user data on its way back to disk, and a lookup that came back
+    // undefined must not be written into a map typed as `CaptionEdit`.
+    if (edit !== undefined) out[u.key] = edit;
+  }
+  return out;
+}
+
 export interface AppliedCaptionEdits {
   lines: CaptionLine[];
-  /** Edits whose guard failed — the word at that index is not what they knew. */
-  dropped: Array<{ index: number; expected: string; found: string }>;
+  /**
+   * Edits that did not apply. `found: null` means no word carries that source
+   * anchor any more (a cut removed it); a string means the word is there but
+   * says something else (a re-plan changed it).
+   *
+   * `reason` is present ONLY for the third case — a SECOND word carrying an
+   * anchor an earlier word already claimed, which is not a stale edit at all
+   * (the edit may well have applied, to the first word). Written only when it
+   * has something to say, the same rule the override doc's own optional keys
+   * follow; absent means the ordinary stale report `found` already
+   * distinguishes. A key can therefore appear in this array more than once.
+   */
+  dropped: Array<{
+    key: string;
+    expected: string;
+    found: string | null;
+    reason?: "duplicate-anchor";
+  }>;
 }
 
 /**
  * Apply retyped caption words. Text only, never timing — the stamps drive the
  * kinetic highlight and the 1:1 constraint is what keeps scene anchors and
- * §21's copy/caption agreement intact. An edit whose `was` no longer matches
- * is reported, not applied and not silently discarded.
+ * §21's copy/caption agreement intact.
+ *
+ * Keyed by source time since §137, so a user cut earlier in the video no
+ * longer shifts every later edit onto the wrong word. An edit that does not
+ * apply is REPORTED — callers must surface `dropped`; the editor discarding it
+ * is what made this failure invisible in the field case.
+ *
+ * AT MOST ONE WORD per edit — the first carrying the key, and the guard's
+ * verdict on that word is final. Keys are millisecond-quantised, so two words
+ * CAN share one (`captions.ts:44-50`: backfilled seam preimages and
+ * cut-clamped words land on the same source instant by design, and rounding
+ * closes sub-millisecond gaps besides). A plain `.map()` rewrites every word
+ * that matches — fanning one retype out onto a word the user never touched,
+ * which is exactly the "wrong anchor silently rewrites the wrong word" the
+ * migration's ambiguity rule refuses to commit, and a breach of the 1:1
+ * in-place retype contract above. Later claimants are reported with
+ * `reason: "duplicate-anchor"` and left alone rather than edited.
  */
 export function applyCaptionEdits(
   lines: readonly CaptionLine[],
@@ -480,19 +941,40 @@ export function applyCaptionEdits(
 ): AppliedCaptionEdits {
   const dropped: AppliedCaptionEdits["dropped"] = [];
   if (Object.keys(edits).length === 0) return { lines: [...lines], dropped };
-  let index = 0;
+
+  const seen = new Set<string>();
   const out = lines.map((line) => ({
     ...line,
     words: line.words.map((w) => {
-      const edit = edits[String(index++)];
+      // No anchor, no edit — a pre-§137 word cannot be addressed, and this is
+      // the boundary that must not throw (see `captionAnchorOf`). The stored
+      // edits then fall out of the sweep below as `found: null`.
+      const key = captionAnchorOf(w);
+      if (key === null) return w;
+      const edit = edits[key];
       if (!edit) return w;
+      // An earlier word already answered for this anchor — whichever way it
+      // answered. Applying here too would fan one retype onto a second word;
+      // re-running the guard here would let an edit be applied AND reported
+      // dropped for the same key.
+      if (seen.has(key)) {
+        dropped.push({ key, expected: edit.was, found: w.text, reason: "duplicate-anchor" });
+        return w;
+      }
+      seen.add(key);
       if (w.text !== edit.was) {
-        dropped.push({ index: index - 1, expected: edit.was, found: w.text });
+        dropped.push({ key, expected: edit.was, found: w.text });
         return w;
       }
       return { ...w, text: edit.text };
     }),
   }));
+
+  // An anchor no word carries any more — the cut removed the word the user
+  // edited. Silence here is exactly the field case, so say it.
+  for (const [key, edit] of Object.entries(edits)) {
+    if (!seen.has(key)) dropped.push({ key, expected: edit.was, found: null });
+  }
   return { lines: out, dropped };
 }
 
@@ -605,7 +1087,9 @@ export interface ReclampResult {
 }
 
 /**
- * The scene a cue id belongs to, stripping a split half's `@ms` suffix —
+ * The scene a cue id belongs to, stripping a split half's `@<split id>`
+ * suffix. That suffix is opaque since §137 — a minted id, not a time — so the
+ * `@` is the only thing this can key on; it is the
  * same idiom `splitCues` itself uses to derive a later half's id from its
  * root, and the same one `effectiveOverride` above inlines to find a half's
  * root entry. Two cues sharing a root are the SAME scene, cut in two.

package/src/recut.ts

@@ -1,4 +1,4 @@
-import type { OverrideDoc } from "./overrides";
+import { SPLIT_MIN_PIECE_SEC, type OverrideDoc } from "./overrides";
 import type { Segment } from "./schema";
 import { mapsClose, TimeMap } from "./timemap";
 
@@ -56,7 +56,65 @@ export function remapOverridesThroughRecut(
 ): RecutRemap {
   const reports: string[] = [];
 
-  const splits = doc.splits.map((t) => remapPoint("split", t, oldMap, newMap, reports));
+  // Only `at` moves: a split's `id` is minted once and never recomputed
+  // (§137, `SplitSchema`) — re-deriving it here is what renamed the half and
+  // orphaned the overrides on it.
+  const splits = doc.splits.map((s) => {
+    const before = reports.length;
+    const at = remapPoint(`split "${s.id}"`, s.at, oldMap, newMap, reports);
+    // `splitCues` needs a cue with `at >= startSec + SPLIT_MIN_PIECE_SEC` AND
+    // `at <= endSec - SPLIT_MIN_PIECE_SEC`. Output time runs [0,
+    // outputDuration] and every cue lives inside it, so a split closer than
+    // that to EITHER end can match no cue at all and is skipped: the half it
+    // named stops existing, every override keyed to it is orphaned, and the
+    // scene the user deleted comes back. Before §137 the only trace of that
+    // was produce.ts's generic `edit for scene-0@600 dropped — the plan no
+    // longer has that scene`, which blames the plan and names neither the
+    // split nor the re-cut that moved it. Name both.
+    //
+    // Start: the field case — a 0.6s cut pushed a split at 0.6s to 0.
+    // End: `at` need not move at all; cutting the tail moves `outputDuration`
+    // out from under it (a split at 9.5s of 10s, with 9.6–10.0 cut).
+    //
+    // Both fire only when THIS re-cut is what pushed the split past the bar:
+    // `reports` is the "a value MOVED" channel (see `RecutRemap`), and a
+    // split already past it beforehand is a pre-existing condition — one the
+    // editor's own SPLIT_MIN_PIECE_SEC guard refuses to create — that would
+    // otherwise be re-announced on every identity re-cut, forever.
+    //
+    // The two guards look mirrored and are NOT symmetric about a pure shift,
+    // which is worth stating because reading them as a matched pair invites
+    // "a shift can never be reported" — false at the start. The END bar is
+    // `outputDuration - MIN`, so it slides with the timeline and both sides of
+    // that comparison move together. The START bar is absolute 0 + MIN and
+    // does not slide, so `at < MIN && s.at >= MIN` DOES fire under a pure
+    // shift — and must: trimming 0.6s off the front is exactly what dragged a
+    // split at 0.6s down to 0 in the field case (recut.test.ts, "reports the
+    // split whose remapped `at` can no longer divide anything").
+    //
+    // `remapPoint` states the new time itself when it snapped this split onto
+    // a cut edge; restating it here would read as a second, separate move
+    // rather than the consequence of the one already reported.
+    const where = reports.length > before ? "is" : `is now ${at.toFixed(3)}s —`;
+    if (at < SPLIT_MIN_PIECE_SEC && s.at >= SPLIT_MIN_PIECE_SEC) {
+      reports.push(
+        `split "${s.id}" ${where} too close to the start to divide a scene, ` +
+          `so any edit on its second half will not apply`,
+      );
+      // `else`, not a second `if`: an output shorter than two minimum pieces
+      // trips both bars for the same split, and one line already says it can
+      // no longer divide anything — two would read as two problems.
+    } else if (
+      at > newMap.outputDuration - SPLIT_MIN_PIECE_SEC &&
+      s.at <= oldMap.outputDuration - SPLIT_MIN_PIECE_SEC
+    ) {
+      reports.push(
+        `split "${s.id}" ${where} too close to the end to divide a scene, ` +
+          `so any edit on its second half will not apply`,
+      );
+    }
+    return { ...s, at };
+  });
 
   // Record-shaped: rebuild key by key rather than mutate, matching every
   // other `OverrideDoc`-shaping function in overrides.ts (e.g.