FTS Over Segments

"Index the structured truth. Never index the export — the export is allowed to be wrong."

The Tempting Shortcut

Recall generates readable Markdown transcripts. They're right there, one file per video, full of exactly the text you want to search. So the shortcut writes itself: point a search index at the Markdown folder and you're done. Every instinct says yes. Recall says no, and the reasons stack up fast.

Markdown is mutable. It's a file on disk that a human can hand-edit, that a sync can make stale, that a regeneration can replace. Index it and you've let an export become an input — the exact loop Track 2 forbade. A hand-edited file would silently rewrite what your search believes.
Markdown has lost the structure. Search isn't the product here; the doorway back to the video is. That doorway needs an absolute timestamp per segment. Flatten the release into prose and the timestamps are gone — you can find the words and still not know where in a two-hour video they live.
The index must be rebuildable. A derived index needs a canonical source it can be purged and replayed from. That source is the release in the database, not a file someone might have touched.

Index What the Release Actually Is

So Recall indexes ordered, timestamped segments, projected from the current release into a full-text index inside the database. Each hit carries what the doorway needs: the current release it came from, the absolute video timestamp, the surrounding text, the source identity and path, the release's content hash, and a rank. That's a search result you can act on — click it and the engine knows exactly which video and exactly which second.

Markdown still exists, and it's still useful — for a human to read. It just lives strictly downstream, an export with no authority, participating in nothing: not the index, not queue completion, not summary truth. Even the legacy corpus followed this rule: its old Markdown was imported once as clearly-labeled structured evidence, and from then on search ran on the structured segments, never on the files.

Two Details That Reveal the Care

First: product search groups hits by video without discarding the later ones. The naive grouping — one row per video, take the best hit — quietly throws away every other match in that video, which is often precisely the moment you were hunting. Grouping is a presentation choice; it must never become a data-loss choice.

Second: similar-video results are currently lexical, and a vector index is deliberately not canonical state. If one is added later, the rule already exists: it must stay release-addressed and rebuildable — derived from the same versioned truth, purgeable and replayable, never a second source of authority. Derived things stay derived, no matter how clever they get.

Code

The index is a projection of the current release's segments·sql

-- Ordered, timestamped segments of a release: the structured truth.
CREATE TABLE transcript_segments (
  release_id   TEXT NOT NULL,
  seq          INTEGER NOT NULL,
  start_ms     INTEGER NOT NULL,   -- ABSOLUTE video timestamp
  end_ms       INTEGER NOT NULL,
  text         TEXT NOT NULL
);

-- The searchable projection. Derived -> purge and replay to rebuild.
CREATE VIRTUAL TABLE transcript_segment_fts USING fts5(
  text,
  content='transcript_segments'
);

-- A hit carries the doorway back to the video:
--   video_id + start_ms  -> open the source at that exact second
--   content_sha256       -> which release version this came from
--
-- The generated Markdown is indexed by NOTHING. It's an export.

Exercise

Find a search index, cache, or derived view in your own work and trace what it actually reads from. Is its source the canonical structured record, or a rendered/exported artifact (a Markdown file, a CSV dump, an HTML page, a generated report)? If it's the export, name the failure: what happens when someone edits that file, or when it goes stale? Then re-point it at the structured source and confirm you could purge and rebuild the whole index from scratch.

Hint

Two questions: (1) if I deleted the index entirely, could I rebuild it from a canonical source, or would I lose something that only exists in the index? Anything in the second category isn't derived — it's undeclared truth. (2) Does the index read anything a human can edit by hand? If yes, an export has become an input, and the system's beliefs are now editable with a text editor.