videobook-engine 4.2.0 → 5.3.2

package/dist/temporal-search.js

@@ -1,7 +1,28 @@
+import { guardSearchProvider } from "./search-provider-access.js";
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { normalizeSourcePoint, normalizeSourceRange, rationalEquals, sourceRangeEndTick, } from "./mvp-time.js";
 import { resultOf, syncResultOf } from "./context.js";
 import { canonicalJson, EngineFault, parseJson } from "./store.js";
+import { TemporalVectorIndex } from "./temporal-vector-index.js";
+const retrievalStates = new WeakMap();
+const VECTOR_CANDIDATES = 1_000;
+const continuityPrefixes = new WeakMap();
+const SEGMENT_SELECT = `SELECT s.segment_id, s.artifact_id, a.label AS artifact_label,
+  a.kind AS artifact_kind, a.created_at AS artifact_created_at,
+  s.stream_id, s.object_hash, s.source_range_json, s.source_path, s.segment_kind,
+  s.representative_tick, s.generation, s.manifest_id
+  FROM runtime_media_segments s JOIN artifacts a ON a.artifact_id=s.artifact_id`;
+export function clearTemporalSearchCache(context) {
+    const state = retrievalStates.get(context);
+    retrievalStates.delete(context);
+    for (const index of state?.vectors.values() ?? []) {
+        try {
+            index.dispose();
+        }
+        catch { /* Cache writes cannot prevent closing the catalog. */ }
+    }
+}
 const INDEX_PHASES = [
     "probe",
     "segment",
@@ -14,13 +35,28 @@ const INDEX_PHASES = [
 ];
 export function createTemporalSearchApi(context) {
     const providers = new Map();
+    const registrations = new Map();
     return {
         providers: {
-            register: (provider) => {
-                requiredText(provider.manifestId, "Provider manifest ID");
-                providers.set(provider.manifestId, provider);
+            register: (provider, consent = {}) => {
+                const id = requiredText(provider.manifestId, "Provider manifest ID");
+                const existing = registrations.get(id);
+                if (existing?.matches(provider, consent)) {
+                    existing.validate();
+                    return;
+                }
+                let registered = false;
+                const guarded = guardSearchProvider(provider, consent, () => !registered || providers.get(id) === guarded.provider);
+                guarded.validate();
+                providers.set(id, guarded.provider);
+                registrations.set(id, guarded);
+                registered = true;
             },
             list: () => [...providers.keys()].sort(),
+            unregister: (manifestId) => {
+                registrations.delete(manifestId);
+                return providers.delete(manifestId);
+            },
         },
         manifests: {
             register: (manifest) => syncResultOf(() => registerManifest(context, manifest)),
@@ -31,8 +67,9 @@ export function createTemporalSearchApi(context) {
         commitBatch: (input) => syncResultOf(() => commitIndexBatch(context, input)),
         activate: (manifestId, generation) => syncResultOf(() => activateGeneration(context, manifestId, generation)),
         coverage: (artifact) => syncResultOf(() => searchCoverage(context, artifact)),
-        query: (query) => queryTemporalIndex(context, providers, query),
-        queryPrepared: (query, reference, options = {}) => queryTemporalIndex(context, providers, query, { reference, options }),
+        prepare: (options = {}) => context.withLocalMedia(() => resultOf(() => prepareTemporalIndexes(context, options))),
+        query: (query) => context.withLocalMedia(() => queryTemporalIndex(context, providers, query)),
+        queryPrepared: (query, reference, options = {}) => context.withLocalMedia(() => queryTemporalIndex(context, providers, query, { reference, options })),
         invalidate: (artifact, objectHash) => syncResultOf(() => invalidateCoverage(context, artifact, objectHash)),
         cleanup: () => syncResultOf(() => cleanupRetired(context)),
         stats: () => temporalStats(context),
@@ -226,6 +263,11 @@ function commitIndexBatch(context, input) {
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(batchKey, input.artifactId, input.objectHash, input.manifestId, input.generation, input.phase, input.cursor ?? null, canonicalJson(result), now);
     });
+    const cache = retrievalStates.get(context);
+    if (cache?.generations.has(input.generation)) {
+        for (const observation of observations)
+            cache.pending.add(observation.segmentId);
+    }
     return result;
 }
 function normalizeObservation(context, manifest, batch, input, index, streamCache) {
@@ -445,7 +487,8 @@ async function queryTemporalIndex(context, providers, query, prepared) {
         const active = activeGenerations(context);
         const generationKey = hashJson(active.map((item) => [item.embedding_space, item.generation]));
         const offset = decodeCursor(query.cursor, generationKey);
-        const segments = querySegments(context, active, query);
+        const orderedVideo = prepared?.reference.kind === "video" || query.reference?.kind === "video";
+        const segments = querySegments(context, active, orderedVideo ? { ...query, durationMs: undefined } : query);
         const candidates = new Map(segments.map((segment) => [
             segment.segment_id,
             { segment, signals: [], score: 0 },
@@ -468,7 +511,8 @@ async function queryTemporalIndex(context, providers, query, prepared) {
             .filter((candidate) => (!query.sourceArtifactIds
             || query.sourceArtifactIds.includes(candidate.segment.artifact_id))
             && (!query.artifactKinds
-                || query.artifactKinds.includes(candidate.segment.artifact_kind)))
+                || query.artifactKinds.includes(candidate.segment.artifact_kind))
+            && segmentMatchesDuration(candidate.segment, query.durationMs))
             .map((candidate) => ({
             ...candidate,
             signals: candidate.signals.filter((signal) => allowsSignal(query.modalities, signal.kind)),
@@ -519,22 +563,200 @@ function activeGenerations(context) {
        ORDER BY embedding_space, generation`)
         .all();
 }
+async function prepareTemporalIndexes(context, options) {
+    const active = activeGenerations(context);
+    const selected = active.filter((generation) => (!options.manifestId || generation.manifest_id === options.manifestId)
+        && (!options.generation || generation.generation === options.generation));
+    if ((options.manifestId || options.generation) && selected.length === 0) {
+        throw new EngineFault({ code: "NOT_READY", message: "Activate a generation before preparing its search index" });
+    }
+    const state = retrievalState(context, active, false);
+    const result = { indexes: 0, vectors: 0, updatedVectors: 0, loadedIndexes: 0, persistedIndexes: 0 };
+    for (const generation of selected) {
+        for (const modality of requiredManifest(context, generation.manifest_id).modalities) {
+            if (modality === "metadata")
+                continue;
+            const prepared = await vectorIndex(context, generation, modality, state).prepare(options.signal, options.checkpoint === "periodic");
+            result.indexes++;
+            result.vectors += prepared.vectors;
+            result.updatedVectors += prepared.updatedVectors;
+            result.loadedIndexes += Number(prepared.loaded);
+            result.persistedIndexes += Number(prepared.persisted);
+        }
+    }
+    return result;
+}
+function retrievalState(context, active = activeGenerations(context), refreshMetadata = true) {
+    const generationKey = canonicalJson(active.map((item) => [item.generation, item.embedding_space, item.manifest_id]));
+    let state = retrievalStates.get(context);
+    if (!state || state.generationKey !== generationKey) {
+        const generations = [...new Set(active.map((item) => item.generation))];
+        const rows = generations.length === 0 ? [] : context.store.db.prepare(`${SEGMENT_SELECT} WHERE s.generation IN (${generations.map(() => "?").join(",")}) ORDER BY s.segment_id`).all(...generations);
+        const segments = new Map(rows.map((row) => [row.segment_id, row]));
+        const vectors = state?.vectors ?? new Map();
+        for (const [key, index] of vectors) {
+            const [generation, space] = JSON.parse(key);
+            if (!active.some((item) => item.generation === generation && item.embedding_space === space)) {
+                try {
+                    index.dispose();
+                }
+                catch { /* Retired cache persistence is optional. */ }
+                vectors.delete(key);
+                continue;
+            }
+            for (const [segmentId, entry] of index.entries) {
+                const segment = segments.get(segmentId);
+                if (segment)
+                    entry.value.segment = segment;
+                else
+                    index.delete(segmentId);
+            }
+        }
+        state = {
+            semanticVersion: context.store.semanticVersion, generationKey, generations: new Set(generations),
+            segments, vectors, ordered: new Map(), pending: state?.pending ?? new Set(),
+        };
+        retrievalStates.set(context, state);
+    }
+    if (refreshMetadata && state.semanticVersion !== context.store.semanticVersion) {
+        const generations = [...state.generations];
+        const rows = generations.length === 0 ? [] : context.store.db.prepare(`${SEGMENT_SELECT} WHERE s.generation IN (${generations.map(() => "?").join(",")}) ORDER BY s.segment_id`).all(...generations);
+        state.segments = new Map(rows.map((row) => [row.segment_id, row]));
+        for (const [key, index] of state.vectors) {
+            for (const [segmentId, entry] of index.entries) {
+                const segment = state.segments.get(segmentId);
+                if (segment)
+                    entry.value.segment = segment;
+                else
+                    index.delete(segmentId);
+            }
+            if (index.entries.size === 0) {
+                try {
+                    index.dispose();
+                }
+                catch { /* Empty cache persistence is optional. */ }
+                state.vectors.delete(key);
+            }
+        }
+        state.texts = undefined;
+        state.ordered.clear();
+        state.semanticVersion = context.store.semanticVersion;
+    }
+    if (state.pending.size > 0)
+        refreshRetrievalState(context, state);
+    return state;
+}
+function refreshRetrievalState(context, state) {
+    const pending = [...state.pending];
+    for (let start = 0; start < pending.length; start += 400) {
+        const keys = pending.slice(start, start + 400);
+        const placeholders = keys.map(() => "?").join(",");
+        for (const key of keys) {
+            state.segments.delete(key);
+            state.texts?.delete(key);
+            for (const index of state.vectors.values())
+                index.delete(key);
+        }
+        const rows = context.store.db.prepare(`${SEGMENT_SELECT} WHERE s.segment_id IN (${placeholders}) ORDER BY s.segment_id`).all(...keys);
+        for (const row of rows) {
+            if (state.generations.has(row.generation))
+                state.segments.set(row.segment_id, row);
+        }
+        if (state.texts) {
+            const texts = context.store.db.prepare(`SELECT segment_id, kind, text FROM runtime_segment_text
+         WHERE segment_id IN (${placeholders}) ORDER BY segment_id, kind, text`).all(...keys);
+            for (const row of texts)
+                addCachedText(state.texts, row);
+        }
+        for (const [key, index] of state.vectors) {
+            const [generation, embeddingSpace, modality] = JSON.parse(key);
+            const vectors = context.store.db.prepare(`SELECT segment_id, dimensions, vector_blob FROM runtime_segment_embeddings
+         WHERE generation=? AND embedding_space=? AND modality=?
+           AND segment_id IN (${placeholders}) ORDER BY segment_id`).all(generation, embeddingSpace, modality, ...keys);
+            for (const row of vectors)
+                addCachedVector(state, index, row);
+        }
+    }
+    state.ordered.clear();
+    state.pending.clear();
+}
+function cachedTextRows(context, active) {
+    const state = retrievalState(context, active);
+    if (!state.texts) {
+        state.texts = new Map();
+        const generations = [...state.generations];
+        const rows = generations.length === 0 ? [] : context.store.db.prepare(`SELECT segment_id, kind, text FROM runtime_segment_text
+       WHERE generation IN (${generations.map(() => "?").join(",")}) ORDER BY segment_id, kind, text`).all(...generations);
+        for (const row of rows)
+            addCachedText(state.texts, row);
+    }
+    return [...state.texts.values()].flat();
+}
+function addCachedText(texts, row) {
+    const rows = texts.get(row.segment_id) ?? [];
+    rows.push(row);
+    texts.set(row.segment_id, rows);
+}
+function addCachedVector(state, index, row) {
+    const segment = state.segments.get(row.segment_id);
+    if (!segment)
+        return;
+    if (row.dimensions !== index.dimensions) {
+        throw new EngineFault({ code: "MANIFEST_INCOMPATIBLE", message: "Stored vector dimensions do not match the index manifest" });
+    }
+    const vector = blobToVector(row.vector_blob, row.dimensions);
+    index.set(row.segment_id, vector, { segment, vector, range: segmentRange(segment) });
+}
+function vectorIndex(context, generation, modality, state = retrievalState(context)) {
+    const key = canonicalJson([generation.generation, generation.embedding_space, modality]);
+    const cached = state.vectors.get(key);
+    if (cached)
+        return cached;
+    const manifest = requiredManifest(context, generation.manifest_id);
+    const identity = canonicalJson([key, manifest]);
+    const index = new TemporalVectorIndex(manifest.dimensions, {
+        identity, basePath: join(context.store.dataDir, "runtime-search", hashJson(identity)),
+    });
+    let after = "";
+    for (;;) {
+        const rows = context.store.db.prepare(`SELECT segment_id, dimensions, vector_blob FROM runtime_segment_embeddings
+       WHERE generation=? AND embedding_space=? AND modality=? AND segment_id>?
+       ORDER BY segment_id LIMIT 512`).all(generation.generation, generation.embedding_space, modality, after);
+        for (const row of rows)
+            addCachedVector(state, index, row);
+        if (rows.length < 512)
+            break;
+        after = rows.at(-1).segment_id;
+    }
+    state.vectors.set(key, index);
+    return index;
+}
+function orderedStreams(context, generation) {
+    const state = retrievalState(context);
+    const key = canonicalJson([generation.generation, generation.embedding_space]);
+    const cached = state.ordered.get(key);
+    if (cached)
+        return cached;
+    const streams = new Map();
+    for (const { value } of vectorIndex(context, generation, "visual").entries.values()) {
+        if (!value.range)
+            continue;
+        const stream = streams.get(value.range.streamId) ?? [];
+        stream.push({ segment: value.segment, vector: value.vector, range: value.range });
+        streams.set(value.range.streamId, stream);
+    }
+    for (const stream of streams.values())
+        stream.sort((left, right) => left.range.startTick - right.range.startTick || left.segment.segment_id.localeCompare(right.segment.segment_id));
+    state.ordered.set(key, streams);
+    return streams;
+}
 function querySegments(context, active, query) {
     if (active.length === 0)
         return [];
-    const generations = active.map((item) => item.generation);
-    const placeholders = generations.map(() => "?").join(",");
-    const rows = context.store.db
-        .prepare(`SELECT s.segment_id, s.artifact_id, a.slug AS artifact_slug,
-              a.kind AS artifact_kind, a.created_at AS artifact_created_at,
-              s.stream_id, s.object_hash,
-              s.source_range_json, s.source_path, s.segment_kind,
-              s.representative_tick, s.generation, s.manifest_id
-       FROM runtime_media_segments s
-       JOIN artifacts a ON a.artifact_id=s.artifact_id
-       WHERE s.generation IN (${placeholders})
-       ORDER BY s.artifact_id, s.stream_id, s.representative_tick, s.segment_id`)
-        .all(...generations);
+    const rows = [...retrievalState(context, active).segments.values()];
+    const labelMatches = new Map();
+    const orientations = new Map();
+    const indexingStates = new Map();
     return rows.filter((row) => {
         if (query.artifactKinds && !query.artifactKinds.includes(row.artifact_kind)) {
             return false;
@@ -551,33 +773,38 @@ function querySegments(context, active, query) {
             && row.artifact_created_at >= query.createdBefore) {
             return false;
         }
-        if (query.labels && !artifactHasLabels(context, row.artifact_id, query.labels)) {
-            return false;
-        }
-        if (query.orientations
-            && !query.orientations.includes(artifactOrientation(context, row.artifact_id))) {
-            return false;
+        if (query.labels) {
+            if (!labelMatches.has(row.artifact_id))
+                labelMatches.set(row.artifact_id, artifactHasLabels(context, row.artifact_id, query.labels));
+            if (!labelMatches.get(row.artifact_id))
+                return false;
         }
-        if (query.indexingStates
-            && !query.indexingStates.includes(artifactGenerationState(context, row.artifact_id, row.generation))) {
-            return false;
+        if (query.orientations) {
+            if (!orientations.has(row.artifact_id))
+                orientations.set(row.artifact_id, artifactOrientation(context, row.artifact_id));
+            if (!query.orientations.includes(orientations.get(row.artifact_id)))
+                return false;
         }
-        if (query.durationMs) {
-            const range = segmentRange(row);
-            if (range) {
-                const durationMs = (range.durationTicks * range.timeBase.numerator * 1_000)
-                    / range.timeBase.denominator;
-                if ((query.durationMs.min !== undefined
-                    && durationMs < query.durationMs.min)
-                    || (query.durationMs.max !== undefined
-                        && durationMs > query.durationMs.max)) {
-                    return false;
-                }
-            }
+        if (query.indexingStates) {
+            const key = `${row.artifact_id}:${row.generation}`;
+            if (!indexingStates.has(key))
+                indexingStates.set(key, artifactGenerationState(context, row.artifact_id, row.generation));
+            if (!query.indexingStates.includes(indexingStates.get(key)))
+                return false;
         }
-        return true;
+        return segmentMatchesDuration(row, query.durationMs);
     });
 }
+function segmentMatchesDuration(segment, requested) {
+    if (!requested)
+        return true;
+    const range = segmentRange(segment);
+    if (!range)
+        return true;
+    const durationMs = sourceTickToMs(range.durationTicks, range);
+    return (requested.min === undefined || durationMs >= requested.min)
+        && (requested.max === undefined || durationMs <= requested.max);
+}
 function artifactHasLabels(context, artifactId, requested) {
     const row = context.store.db
         .prepare(`SELECT value_json FROM artifact_metadata
@@ -612,12 +839,7 @@ function addLexicalSignals(context, candidates, text, active) {
     const generations = active.map((item) => item.generation);
     if (generations.length === 0)
         return;
-    const rows = context.store.db
-        .prepare(`SELECT segment_id, kind, text
-       FROM runtime_segment_text
-       WHERE generation IN (${generations.map(() => "?").join(",")})
-       ORDER BY segment_id, kind, text`)
-        .all(...generations);
+    const rows = cachedTextRows(context, active);
     const normalized = text.trim().toLocaleLowerCase();
     const quoted = [...text.matchAll(/"([^"]+)"/g)]
         .map((match) => match[1]?.trim().toLocaleLowerCase())
@@ -705,8 +927,11 @@ function addOrderedVideoSignals(context, candidates, rangeInput, generation) {
         && rangesOverlap(segmentRangeValue.startTick, sourceRangeEndTick(segmentRangeValue), range.startTick, sourceRangeEndTick(range)));
     if (query.length === 0)
         return;
-    const sample = evenlySample(query, Math.min(query.length, 16));
-    addOrderedVideoVectorSignals(context, candidates, sample, generation);
+    const sample = evenlySample(query, Math.min(query.length, 16)).map((item) => ({
+        ...item,
+        offsetMs: sourceTickToMs(item.range.startTick - range.startTick, range),
+    }));
+    addOrderedVideoVectorSignals(context, candidates, sample, generation, sourceTickToMs(range.durationTicks, range));
 }
 function addPreparedReferenceSignals(context, candidates, reference, options, active) {
     for (const generation of active) {
@@ -720,38 +945,62 @@ function addPreparedReferenceSignals(context, candidates, reference, options, ac
             continue;
         }
         const samples = preparedVideoSamples(reference, options);
+        const startMs = options.range?.startMs ?? 0;
+        const durationMs = Math.min(options.range?.durationMs ?? Infinity, preparedVideoDuration(reference) - startMs);
         for (const sample of samples) {
             preparedVector(sample.vector, manifest.dimensions);
         }
         addOrderedVideoVectorSignals(context, candidates, samples.map((sample) => ({
             vector: Float32Array.from(sample.vector),
-        })), generation);
+            offsetMs: sample.offsetMs - startMs,
+        })), generation, durationMs);
     }
 }
-function addOrderedVideoVectorSignals(context, candidates, sample, generation) {
+function addOrderedVideoVectorSignals(context, candidates, sample, generation, durationMs) {
     if (sample.length === 0)
         return;
-    const all = orderedEmbeddings(context, generation, () => true);
-    const byStream = new Map();
-    for (const item of all) {
-        const values = byStream.get(item.range.streamId) ?? [];
-        values.push(item);
-        byStream.set(item.range.streamId, values);
-    }
+    const byStream = orderedStreams(context, generation);
+    const starts = orderedCandidateStarts(context, candidates, sample, generation, byStream);
+    const queryVectors = new Map();
     const windows = [];
-    for (const values of byStream.values()) {
-        values.sort((left, right) => left.range.startTick - right.range.startTick
-            || left.segment.segment_id.localeCompare(right.segment.segment_id));
-        if (values.length < sample.length)
-            continue;
-        for (let start = 0; start <= values.length - sample.length; start += 1) {
-            const window = values.slice(start, start + sample.length);
-            const aligned = sample.reduce((sum, item, index) => sum + cosineSimilarity(item.vector, window[index].vector), 0) / sample.length;
-            const coherence = transitionCoherence(sample, window);
+    for (const [streamId, positions] of starts) {
+        const values = byStream.get(streamId);
+        for (const start of [...positions].sort((left, right) => left - right)) {
+            const first = values[start];
+            const startMs = sourceTickToMs(first.range.startTick, first.range);
+            const end = orderedPosition(values, startMs + durationMs);
+            const count = end - start;
+            const window = Array.from({ length: Math.min(count, 16) }, (_, index) => values[start + (count === 1 ? 0 : Math.round(index * (count - 1) / (Math.min(count, 16) - 1)))]);
+            const last = values[end - 1];
+            const availableMs = Math.min(durationMs, sourceTickToMs(sourceRangeEndTick(last.range), last.range) - startMs);
+            const timedWindow = window.map((item) => ({
+                ...item,
+                offsetMs: sourceTickToMs(item.range.startTick, item.range) - startMs,
+            }));
+            const offsets = [...new Set([...sample, ...timedWindow]
+                    .map((item) => item.offsetMs)
+                    .filter((offset) => offset >= 0 && offset < availableMs))]
+                .sort((left, right) => left - right);
+            if (offsets.length === 0)
+                continue;
+            const query = offsets.map((offset) => {
+                let vector = queryVectors.get(offset);
+                if (!vector) {
+                    vector = videoVectorAt(sample, offset);
+                    queryVectors.set(offset, vector);
+                }
+                return { vector };
+            });
+            const target = offsets.map((offset) => ({ vector: videoVectorAt(timedWindow, offset) }));
+            const aligned = query.reduce((sum, item, index) => sum + cosineSimilarity(item.vector, target[index].vector), 0) / query.length;
+            const coherence = transitionCoherence(query, target) * 0.75
+                + temporalContinuity(values, start, end) * 0.25;
             windows.push({
                 values: window,
-                score: aligned * 0.75 + coherence * 0.25,
+                score: (aligned * 0.75 + coherence * 0.25) * availableMs / durationMs,
                 coherence,
+                durationTicks: Math.max(1, Math.min(sourceRangeEndTick(last.range) - first.range.startTick, Math.round(availableMs * first.range.timeBase.denominator
+                    / (first.range.timeBase.numerator * 1_000)))),
             });
         }
     }
@@ -763,7 +1012,7 @@ function addOrderedVideoVectorSignals(context, candidates, sample, generation) {
         const last = window.values.at(-1);
         const combined = {
             ...first.range,
-            durationTicks: sourceRangeEndTick(last.range) - first.range.startTick,
+            durationTicks: window.durationTicks,
         };
         const segmentId = `ordered:${generation.generation}:${first.segment.segment_id}:${last.segment.segment_id}`;
         const candidate = {
@@ -774,6 +1023,14 @@ function addOrderedVideoVectorSignals(context, candidates, sample, generation) {
                 representative_tick: first.range.startTick + Math.floor(combined.durationTicks / 2),
             },
             signals: [
+                ...(isExactOrderedWindow(sample, window.values)
+                    ? [{
+                            kind: "exact",
+                            rank: 1,
+                            score: 1,
+                            explanation: "Exact source bytes and ordered range matched",
+                        }]
+                    : []),
                 {
                     kind: "visual",
                     rank: index + 1,
@@ -786,30 +1043,56 @@ function addOrderedVideoVectorSignals(context, candidates, sample, generation) {
         candidates.set(segmentId, candidate);
     });
 }
+function orderedCandidateStarts(context, candidates, sample, generation, streams) {
+    const starts = new Map();
+    const index = vectorIndex(context, generation, "visual");
+    const timedCandidates = new Map([...candidates].filter(([, candidate]) => candidate.segment.source_range_json !== null));
+    const seedCount = Math.max(32, Math.floor(512 / sample.length));
+    for (const querySample of sample) {
+        for (const { value } of index.nearest(querySample.vector, seedCount, timedCandidates)) {
+            if (!value.range)
+                continue;
+            const stream = streams.get(value.range.streamId);
+            const desiredMs = sourceTickToMs(value.range.startTick, value.range) - querySample.offsetMs;
+            const low = orderedPosition(stream, desiredMs);
+            const positions = starts.get(value.range.streamId) ?? new Set();
+            for (const position of [low - 1, low, low + 1]) {
+                const item = stream[position];
+                if (item && candidates.has(item.segment.segment_id))
+                    positions.add(position);
+            }
+            starts.set(value.range.streamId, positions);
+        }
+    }
+    return starts;
+}
+function orderedPosition(stream, milliseconds) {
+    let low = 0;
+    let high = stream.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        const item = stream[middle];
+        if (sourceTickToMs(item.range.startTick, item.range) < milliseconds)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+function videoVectorAt(samples, offsetMs) {
+    const next = samples.findIndex((sample) => sample.offsetMs >= offsetMs);
+    if (next === -1)
+        return samples.at(-1).vector;
+    if (next === 0 || samples[next].offsetMs === offsetMs)
+        return samples[next].vector;
+    const before = samples[next - 1];
+    const after = samples[next];
+    const fraction = (offsetMs - before.offsetMs) / (after.offsetMs - before.offsetMs);
+    return before.vector.map((value, index) => value * (1 - fraction) + after.vector[index] * fraction);
+}
 function orderedEmbeddings(context, generation, include) {
-    const rows = context.store.db
-        .prepare(`SELECT s.segment_id, s.artifact_id, a.slug AS artifact_slug,
-              a.kind AS artifact_kind, a.created_at AS artifact_created_at,
-              s.stream_id, s.object_hash, s.source_range_json,
-              s.source_path, s.segment_kind, s.representative_tick,
-              s.generation, s.manifest_id, e.dimensions, e.vector_blob
-       FROM runtime_media_segments s
-       JOIN artifacts a ON a.artifact_id=s.artifact_id
-       JOIN runtime_segment_embeddings e ON e.segment_id=s.segment_id
-       WHERE s.generation=? AND e.embedding_space=?
-         AND e.modality='visual' AND s.source_range_json IS NOT NULL
-       ORDER BY s.stream_id, s.representative_tick, s.segment_id`)
-        .all(generation.generation, generation.embedding_space);
-    return rows.flatMap((row) => {
-        const range = segmentRange(row);
-        return range && include(range)
-            ? [{
-                    segment: row,
-                    range,
-                    vector: blobToVector(row.vector_blob, row.dimensions),
-                }]
-            : [];
-    });
+    return [...orderedStreams(context, generation).values()]
+        .flatMap((rows) => rows.filter((row) => include(row.range)));
 }
 function transitionCoherence(query, candidate) {
     if (query.length < 2)
@@ -820,6 +1103,42 @@ function transitionCoherence(query, candidate) {
     }
     return score / (query.length - 1);
 }
+function temporalContinuity(candidate, start, end) {
+    if (end - start < 2)
+        return 1;
+    let prefix = continuityPrefixes.get(candidate);
+    if (!prefix) {
+        prefix = new Float64Array(candidate.length);
+        for (let index = 1; index < candidate.length; index++) {
+            const previous = candidate[index - 1].range;
+            const current = candidate[index].range;
+            const gapMs = Math.max(0, sourceTickToMs(current.startTick, current)
+                - sourceTickToMs(sourceRangeEndTick(previous), previous));
+            const scaleMs = Math.max(1, (sourceTickToMs(previous.durationTicks, previous)
+                + sourceTickToMs(current.durationTicks, current)) / 2);
+            prefix[index] = prefix[index - 1] + 1 / (1 + gapMs / scaleMs);
+        }
+        continuityPrefixes.set(candidate, prefix);
+    }
+    return (prefix[end - 1] - prefix[start]) / (end - start - 1);
+}
+function isExactOrderedWindow(query, candidate) {
+    return query.length === candidate.length && query.every((item, index) => {
+        const reference = item.range;
+        const match = candidate[index]?.range;
+        return Boolean(reference
+            && match
+            && reference.objectHash === match.objectHash
+            && nearlyEqual(sourceTickToMs(reference.startTick, reference), sourceTickToMs(match.startTick, match))
+            && nearlyEqual(sourceTickToMs(reference.durationTicks, reference), sourceTickToMs(match.durationTicks, match)));
+    });
+}
+function sourceTickToMs(tick, range) {
+    return (tick * range.timeBase.numerator * 1_000) / range.timeBase.denominator;
+}
+function nearlyEqual(left, right) {
+    return Math.abs(left - right) <= 1e-6;
+}
 function vectorDifference(left, right) {
     const result = new Float32Array(left.length);
     for (let index = 0; index < left.length; index += 1) {
@@ -838,31 +1157,13 @@ function evenlySample(values, count) {
     });
 }
 function rankVectorRows(context, candidates, generation, queryVector, modality, explanation) {
-    const rows = context.store.db
-        .prepare(`SELECT segment_id, embedding_space, modality, dimensions, vector_blob
-       FROM runtime_segment_embeddings
-       WHERE generation=? AND embedding_space=?
-         AND modality=?
-       ORDER BY segment_id`)
-        .all(generation.generation, generation.embedding_space, modality);
-    rows
-        .map((row) => ({
-        row,
-        score: cosineSimilarity(queryVector, blobToVector(row.vector_blob, row.dimensions)),
-    }))
-        .filter((item) => Number.isFinite(item.score))
-        .sort((left, right) => right.score - left.score
-        || left.row.segment_id.localeCompare(right.row.segment_id))
+    vectorIndex(context, generation, modality)
+        .nearest(queryVector, VECTOR_CANDIDATES, candidates)
         .forEach((item, index) => {
-        const candidate = candidates.get(item.row.segment_id);
+        const candidate = candidates.get(item.key);
         if (!candidate)
             return;
-        candidate.signals.push({
-            kind: modality,
-            rank: index + 1,
-            score: item.score,
-            explanation,
-        });
+        candidate.signals.push({ kind: modality, rank: index + 1, score: item.score, explanation });
     });
 }
 function referenceEmbeddingRows(context, reference, generation) {
@@ -870,13 +1171,14 @@ function referenceEmbeddingRows(context, reference, generation) {
     if (segments.length === 0)
         return [];
     const placeholders = segments.map(() => "?").join(",");
+    const modality = reference.kind === "audio" ? "audio" : "visual";
     return context.store.db
         .prepare(`SELECT segment_id, embedding_space, modality, dimensions, vector_blob
        FROM runtime_segment_embeddings
        WHERE segment_id IN (${placeholders})
-         AND embedding_space=?
+         AND embedding_space=? AND modality=?
        ORDER BY segment_id`)
-        .all(...segments, generation.embedding_space);
+        .all(...segments, generation.embedding_space, modality);
 }
 function referenceSegments(context, reference, generation) {
     if (reference.kind === "image") {
@@ -1073,7 +1375,9 @@ function intervalPriority(interval) {
 function candidateToHit(candidate) {
     return {
         artifactId: candidate.segment.artifact_id,
-        artifactSlug: candidate.segment.artifact_slug,
+        ...(candidate.segment.artifact_label
+            ? { artifactLabel: candidate.segment.artifact_label }
+            : {}),
         artifactKind: candidate.segment.artifact_kind,
         location: segmentLocation(candidate.segment),
         ...(candidate.segment.representative_tick === null
@@ -1297,6 +1601,13 @@ function validatePreparedReference(reference, options) {
             message: "Prepared video references require between 1 and 16 samples",
         });
     }
+    if (reference.durationMs !== undefined && (!Number.isFinite(reference.durationMs) || reference.durationMs <= 0
+        || reference.samples.some((sample) => sample.offsetMs >= reference.durationMs))) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Prepared video duration must be finite, positive, and contain every sample",
+        });
+    }
     let previousOffset = -1;
     for (const sample of reference.samples) {
         if (!Number.isFinite(sample.offsetMs) || sample.offsetMs < 0) {
@@ -1334,11 +1645,9 @@ function validatePreparedReference(reference, options) {
 }
 function preparedVideoSamples(reference, options) {
     const range = options.range;
-    const endMs = range?.durationMs === undefined
-        ? Number.POSITIVE_INFINITY
-        : range.startMs + range.durationMs;
+    const endMs = Math.min(preparedVideoDuration(reference), range?.durationMs === undefined ? Infinity : range.startMs + range.durationMs);
     const samples = range
-        ? reference.samples.filter((sample) => sample.offsetMs >= range.startMs && sample.offsetMs <= endMs)
+        ? reference.samples.filter((sample) => sample.offsetMs >= range.startMs && sample.offsetMs < endMs)
         : reference.samples;
     if (samples.length === 0) {
         throw new EngineFault({
@@ -1348,6 +1657,13 @@ function preparedVideoSamples(reference, options) {
     }
     return samples;
 }
+function preparedVideoDuration(reference) {
+    if (reference.durationMs !== undefined)
+        return reference.durationMs;
+    const last = reference.samples.at(-1);
+    const intervals = reference.samples.slice(1).map((sample, index) => sample.offsetMs - reference.samples[index].offsetMs).sort((a, b) => a - b);
+    return last.offsetMs + (intervals[Math.floor(intervals.length / 2)] ?? 1);
+}
 function preparedVector(vector, dimensions) {
     if (!Array.isArray(vector)
         || vector.length === 0