videobook-engine 2.0.1 → 4.2.0

package/dist/temporal-search.js

@@ -0,0 +1,1507 @@
+import { createHash } from "node:crypto";
+import { normalizeSourcePoint, normalizeSourceRange, rationalEquals, sourceRangeEndTick, } from "./mvp-time.js";
+import { resultOf, syncResultOf } from "./context.js";
+import { canonicalJson, EngineFault, parseJson } from "./store.js";
+const INDEX_PHASES = [
+    "probe",
+    "segment",
+    "transcript",
+    "ocr",
+    "visual",
+    "audio",
+    "lexical",
+    "activate",
+];
+export function createTemporalSearchApi(context) {
+    const providers = new Map();
+    return {
+        providers: {
+            register: (provider) => {
+                requiredText(provider.manifestId, "Provider manifest ID");
+                providers.set(provider.manifestId, provider);
+            },
+            list: () => [...providers.keys()].sort(),
+        },
+        manifests: {
+            register: (manifest) => syncResultOf(() => registerManifest(context, manifest)),
+            list: () => listManifests(context),
+            get: (manifestId) => syncResultOf(() => requiredManifest(context, manifestId)),
+        },
+        plan: (artifact, objectHash, manifestId, generation) => syncResultOf(() => indexPlan(context, artifact, objectHash, manifestId, generation)),
+        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 }),
+        invalidate: (artifact, objectHash) => syncResultOf(() => invalidateCoverage(context, artifact, objectHash)),
+        cleanup: () => syncResultOf(() => cleanupRetired(context)),
+        stats: () => temporalStats(context),
+    };
+}
+function registerManifest(context, manifest) {
+    validateManifest(manifest);
+    const existing = context.store.db
+        .prepare("SELECT * FROM runtime_index_manifests WHERE manifest_id=?")
+        .get(manifest.manifestId);
+    if (existing) {
+        const projected = manifestFromRow(existing);
+        if (canonicalJson(projected) !== canonicalJson(manifest)) {
+            throw new EngineFault({
+                code: "MANIFEST_INCOMPATIBLE",
+                message: `Index manifest is immutable: ${manifest.manifestId}`,
+            });
+        }
+        return projected;
+    }
+    context.store.runtime(() => {
+        context.store.db
+            .prepare(`INSERT INTO runtime_index_manifests(
+          manifest_id, provider, model_id, model_revision, license,
+          embedding_space, dimensions, modalities_json,
+          supported_languages_json, preprocessing_version,
+          extractor_version, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(manifest.manifestId, manifest.provider, manifest.modelId, manifest.modelRevision, manifest.license ?? null, manifest.embeddingSpace, manifest.dimensions, canonicalJson(manifest.modalities), canonicalJson(manifest.supportedLanguages), manifest.preprocessingVersion, manifest.extractorVersion, manifest.createdAt);
+    });
+    return manifest;
+}
+function validateManifest(manifest) {
+    requiredText(manifest.manifestId, "Manifest ID");
+    requiredText(manifest.provider, "Manifest provider");
+    requiredText(manifest.modelId, "Manifest model ID");
+    requiredText(manifest.modelRevision, "Manifest model revision");
+    requiredText(manifest.embeddingSpace, "Manifest embedding space");
+    safeIntegerAtLeast(manifest.dimensions, 1, "Manifest dimensions");
+    if (manifest.modalities.length === 0) {
+        throw new Error("Manifest must support at least one modality");
+    }
+    requiredText(manifest.preprocessingVersion, "Preprocessing version");
+    requiredText(manifest.extractorVersion, "Extractor version");
+    safeIntegerAtLeast(manifest.createdAt, 0, "Manifest createdAt");
+}
+function listManifests(context) {
+    return context.store.db
+        .prepare(`SELECT * FROM runtime_index_manifests
+         ORDER BY created_at, manifest_id`)
+        .all().map(manifestFromRow);
+}
+function requiredManifest(context, manifestId) {
+    const row = context.store.db
+        .prepare("SELECT * FROM runtime_index_manifests WHERE manifest_id=?")
+        .get(manifestId);
+    if (!row) {
+        throw new EngineFault({
+            code: "NOT_FOUND",
+            message: `Index manifest not found: ${manifestId}`,
+        });
+    }
+    return manifestFromRow(row);
+}
+function manifestFromRow(row) {
+    return {
+        manifestId: row.manifest_id,
+        provider: row.provider,
+        modelId: row.model_id,
+        modelRevision: row.model_revision,
+        ...(row.license ? { license: row.license } : {}),
+        embeddingSpace: row.embedding_space,
+        dimensions: row.dimensions,
+        modalities: parseJson(row.modalities_json, []),
+        supportedLanguages: parseJson(row.supported_languages_json, []),
+        preprocessingVersion: row.preprocessing_version,
+        extractorVersion: row.extractor_version,
+        createdAt: row.created_at,
+    };
+}
+function indexPlan(context, artifactReference, objectHash, manifestId, generation) {
+    const artifact = context.artifactRow(artifactReference);
+    assertArtifactObject(context, artifact.artifact_id, objectHash);
+    requiredManifest(context, manifestId);
+    requiredText(generation, "Index generation");
+    const coverage = coverageRows(context, "WHERE artifact_id=? AND object_hash=? AND manifest_id=? AND generation=?", [artifact.artifact_id, objectHash, manifestId, generation]);
+    const completed = new Set(coverage
+        .filter((item) => item.state === "ready")
+        .map((item) => item.phase));
+    return {
+        artifactId: artifact.artifact_id,
+        objectHash,
+        manifestId,
+        generation,
+        phases: INDEX_PHASES,
+        pendingPhases: INDEX_PHASES.filter((phase) => !completed.has(phase)),
+        coverage,
+    };
+}
+function commitIndexBatch(context, input) {
+    const artifact = context.artifactRow(input.artifactId);
+    const manifest = requiredManifest(context, input.manifestId);
+    if (artifact.artifact_id !== input.artifactId) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Index batches require a canonical artifact ID",
+        });
+    }
+    assertArtifactObject(context, artifact.artifact_id, input.objectHash);
+    requiredText(input.generation, "Index generation");
+    safeIntegerAtLeast(input.maxUnits, 1, "Index batch max units");
+    if (input.observations.length > input.maxUnits) {
+        throw new EngineFault({
+            code: "RESOURCE_EXHAUSTED",
+            message: "Index batch exceeds maxUnits",
+        });
+    }
+    const batchKey = hashJson({
+        artifactId: input.artifactId,
+        objectHash: input.objectHash,
+        manifestId: input.manifestId,
+        generation: input.generation,
+        phase: input.phase,
+        cursor: input.cursor ?? null,
+        observations: input.observations,
+    });
+    const existing = context.store.db
+        .prepare("SELECT result_json FROM runtime_index_batches WHERE batch_key=?")
+        .get(batchKey);
+    if (existing) {
+        return parseJson(existing.result_json, {
+            artifactId: input.artifactId,
+            manifestId: input.manifestId,
+            phase: input.phase,
+            committedUnits: 0,
+            coveredRanges: [],
+            complete: false,
+            generation: input.generation,
+        });
+    }
+    const streamCache = new Map();
+    const observations = input.observations.map((observation, index) => normalizeObservation(context, manifest, input, observation, index, streamCache));
+    const coveredRanges = input.coveredRanges.map(normalizeSourceRange);
+    const result = {
+        artifactId: input.artifactId,
+        manifestId: input.manifestId,
+        phase: input.phase,
+        committedUnits: observations.length,
+        coveredRanges,
+        ...(input.nextCursor ? { nextCursor: input.nextCursor } : {}),
+        complete: input.complete,
+        generation: input.generation,
+    };
+    context.store.runtime((now) => {
+        ensureGeneration(context, manifest, input.generation, now);
+        const statements = prepareObservationStatements(context);
+        const existingSegments = existingSegmentIds(context, observations);
+        const writtenSegments = new Set();
+        for (const observation of observations) {
+            upsertObservation(input, observation, now, statements, existingSegments.has(observation.segmentId)
+                || writtenSegments.has(observation.segmentId));
+            writtenSegments.add(observation.segmentId);
+        }
+        const prior = context.store.db
+            .prepare(`SELECT indexed_units FROM runtime_index_coverage
+         WHERE artifact_id=? AND object_hash=? AND manifest_id=?
+           AND generation=? AND phase=?`)
+            .get(input.artifactId, input.objectHash, input.manifestId, input.generation, input.phase);
+        context.store.db
+            .prepare(`INSERT INTO runtime_index_coverage(
+          artifact_id, object_hash, manifest_id, generation, phase,
+          state, covered_ranges_json, indexed_units, total_units,
+          retryable, error_json, cursor, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, NULL, ?, ?)
+        ON CONFLICT(
+          artifact_id, object_hash, manifest_id, generation, phase
+        ) DO UPDATE SET
+          state=excluded.state,
+          covered_ranges_json=excluded.covered_ranges_json,
+          indexed_units=excluded.indexed_units,
+          total_units=excluded.total_units,
+          retryable=1,
+          error_json=NULL,
+          cursor=excluded.cursor,
+          updated_at=excluded.updated_at`)
+            .run(input.artifactId, input.objectHash, input.manifestId, input.generation, input.phase, input.complete ? "ready" : "partial", canonicalJson(coveredRanges), (prior?.indexed_units ?? 0) + observations.length, input.totalUnits ?? null, input.nextCursor ?? null, now);
+        context.store.db
+            .prepare(`INSERT INTO runtime_index_batches(
+          batch_key, artifact_id, object_hash, manifest_id, generation,
+          phase, cursor, result_json, committed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(batchKey, input.artifactId, input.objectHash, input.manifestId, input.generation, input.phase, input.cursor ?? null, canonicalJson(result), now);
+    });
+    return result;
+}
+function normalizeObservation(context, manifest, batch, input, index, streamCache) {
+    if (input.artifactId !== batch.artifactId
+        || input.objectHash !== batch.objectHash) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Index observation source does not match its batch",
+        });
+    }
+    const segmentId = input.segmentId
+        ?? deterministicUuid(batch.generation, `${batch.artifactId}:${batch.phase}:${batch.cursor ?? "start"}:${index}`);
+    const range = input.range ? normalizeSourceRange(input.range) : undefined;
+    if (range) {
+        if (range.objectHash !== batch.objectHash
+            || (input.streamId && range.streamId !== input.streamId)) {
+            throw new EngineFault({
+                code: "INVALID_RANGE",
+                message: "Observation range does not match its stream identity",
+            });
+        }
+        let stream = streamCache.get(range.streamId);
+        if (!streamCache.has(range.streamId)) {
+            stream = context.store.db
+                .prepare(`SELECT artifact_id, object_hash, duration_ticks,
+                  time_base_numerator, time_base_denominator
+           FROM artifact_streams WHERE stream_id=?`)
+                .get(range.streamId);
+            streamCache.set(range.streamId, stream);
+        }
+        if (!stream
+            || stream.artifact_id !== batch.artifactId
+            || stream.object_hash !== batch.objectHash
+            || sourceRangeEndTick(range) > stream.duration_ticks
+            || !rationalEquals(range.timeBase, {
+                numerator: stream.time_base_numerator,
+                denominator: stream.time_base_denominator,
+            })) {
+            throw new EngineFault({
+                code: "INVALID_RANGE",
+                message: "Observation range exceeds or mismatches its source stream",
+            });
+        }
+    }
+    else if (!input.sourcePath) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Untimed observations require a source path",
+        });
+    }
+    requiredText(input.segmentationVersion, "Segmentation version");
+    for (const text of input.texts) {
+        requiredText(text.text, "Segment text");
+        if (text.startUtf8Byte !== undefined
+            || text.endUtf8Byte !== undefined) {
+            safeIntegerAtLeast(text.startUtf8Byte ?? -1, 0, "Text start byte");
+            safeIntegerAtLeast(text.endUtf8Byte ?? -1, 1, "Text end byte");
+            if ((text.endUtf8Byte ?? 0) <= (text.startUtf8Byte ?? 0)) {
+                throw new EngineFault({
+                    code: "INVALID_RANGE",
+                    message: "Text byte range must be positive and half-open",
+                });
+            }
+        }
+    }
+    for (const embedding of input.embeddings) {
+        if (embedding.embeddingSpace !== manifest.embeddingSpace) {
+            throw new EngineFault({
+                code: "MANIFEST_INCOMPATIBLE",
+                message: "Observation embedding space does not match its manifest",
+            });
+        }
+        if (embedding.vector.length !== manifest.dimensions) {
+            throw new EngineFault({
+                code: "MANIFEST_INCOMPATIBLE",
+                message: "Observation vector dimensions do not match its manifest",
+            });
+        }
+        if (!embedding.vector.every(Number.isFinite)) {
+            throw new Error("Observation vectors must contain finite numbers");
+        }
+    }
+    return {
+        ...input,
+        segmentId,
+        ...(range ? { range } : {}),
+    };
+}
+function ensureGeneration(context, manifest, generation, now) {
+    const existing = context.store.db
+        .prepare(`SELECT manifest_id FROM runtime_index_generations
+       WHERE embedding_space=? AND generation=?`)
+        .get(manifest.embeddingSpace, generation);
+    if (existing && existing.manifest_id !== manifest.manifestId) {
+        throw new EngineFault({
+            code: "MANIFEST_INCOMPATIBLE",
+            message: "Generation is already bound to another manifest",
+        });
+    }
+    context.store.db
+        .prepare(`INSERT OR IGNORE INTO runtime_index_generations(
+        embedding_space, generation, manifest_id, state,
+        activated_at, created_at
+      ) VALUES (?, ?, ?, 'building', NULL, ?)`)
+        .run(manifest.embeddingSpace, generation, manifest.manifestId, now);
+}
+function upsertObservation(batch, observation, now, statements, replaceChildren) {
+    statements.upsertSegment.run(observation.segmentId, observation.artifactId, observation.streamId ?? observation.range?.streamId ?? null, observation.objectHash, observation.range ? canonicalJson(observation.range) : null, observation.sourcePath ?? null, observation.kind, observation.representativeTick ?? null, observation.segmentationVersion, batch.generation, batch.manifestId, now);
+    if (replaceChildren) {
+        statements.deleteText.run(observation.segmentId);
+        statements.deleteEmbeddings.run(observation.segmentId);
+        statements.deleteFingerprints.run(observation.segmentId);
+    }
+    observation.texts.forEach((text, index) => {
+        statements.insertText.run(text.textId ?? deterministicUuid(observation.segmentId, `text:${index}`), observation.segmentId, text.kind, text.language ?? null, text.text, text.startUtf8Byte ?? null, text.endUtf8Byte ?? null, text.confidence ?? null, canonicalJson(text.provenance ?? {}), batch.generation);
+    });
+    observation.embeddings.forEach((embedding, index) => {
+        statements.insertEmbedding.run(embedding.embeddingId
+            ?? deterministicUuid(observation.segmentId, `embedding:${index}`), observation.segmentId, embedding.modality, embedding.embeddingSpace, embedding.vector.length, vectorToBlob(embedding.vector), embedding.sourceHash, batch.generation, now);
+    });
+    observation.fingerprints.forEach((fingerprint, index) => {
+        statements.insertFingerprint.run(fingerprint.fingerprintId
+            ?? deterministicUuid(observation.segmentId, `fingerprint:${index}`), observation.segmentId, fingerprint.kind, fingerprint.value, fingerprint.extractorVersion, batch.generation);
+    });
+}
+function existingSegmentIds(context, observations) {
+    const existing = new Set();
+    for (let offset = 0; offset < observations.length; offset += 500) {
+        const ids = observations
+            .slice(offset, offset + 500)
+            .map((observation) => observation.segmentId);
+        if (ids.length === 0)
+            continue;
+        const rows = context.store.db
+            .prepare(`SELECT segment_id FROM runtime_media_segments
+         WHERE segment_id IN (${ids.map(() => "?").join(",")})`)
+            .all(...ids);
+        for (const row of rows)
+            existing.add(row.segment_id);
+    }
+    return existing;
+}
+function prepareObservationStatements(context) {
+    return {
+        upsertSegment: context.store.db.prepare(`INSERT INTO runtime_media_segments(
+        segment_id, artifact_id, stream_id, object_hash,
+        source_range_json, source_path, segment_kind,
+        representative_tick, segmentation_version,
+        generation, manifest_id, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(segment_id) DO UPDATE SET
+        source_range_json=excluded.source_range_json,
+        source_path=excluded.source_path,
+        segment_kind=excluded.segment_kind,
+        representative_tick=excluded.representative_tick,
+        segmentation_version=excluded.segmentation_version`),
+        deleteText: context.store.db.prepare("DELETE FROM runtime_segment_text WHERE segment_id=?"),
+        deleteEmbeddings: context.store.db.prepare("DELETE FROM runtime_segment_embeddings WHERE segment_id=?"),
+        deleteFingerprints: context.store.db.prepare("DELETE FROM runtime_segment_fingerprints WHERE segment_id=?"),
+        insertText: context.store.db.prepare(`INSERT INTO runtime_segment_text(
+        text_id, segment_id, kind, language, text,
+        start_utf8_byte, end_utf8_byte, confidence,
+        provenance_json, generation
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insertEmbedding: context.store.db.prepare(`INSERT INTO runtime_segment_embeddings(
+        embedding_id, segment_id, modality, embedding_space,
+        dimensions, vector_blob, source_hash, generation, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insertFingerprint: context.store.db.prepare(`INSERT INTO runtime_segment_fingerprints(
+        fingerprint_id, segment_id, kind, value,
+        extractor_version, generation
+      ) VALUES (?, ?, ?, ?, ?, ?)`),
+    };
+}
+function activateGeneration(context, manifestId, generation) {
+    const manifest = requiredManifest(context, manifestId);
+    const row = context.store.db
+        .prepare(`SELECT state FROM runtime_index_generations
+       WHERE embedding_space=? AND generation=? AND manifest_id=?`)
+        .get(manifest.embeddingSpace, generation, manifestId);
+    if (!row) {
+        throw new EngineFault({
+            code: "NOT_FOUND",
+            message: `Index generation not found: ${generation}`,
+        });
+    }
+    const ready = context.store.db
+        .prepare(`SELECT 1 AS present FROM runtime_index_coverage
+       WHERE manifest_id=? AND generation=?
+         AND state IN ('ready','partial') LIMIT 1`)
+        .get(manifestId, generation);
+    if (!ready) {
+        throw new EngineFault({
+            code: "INDEX_INCOMPLETE",
+            message: "Generation has no searchable coverage",
+        });
+    }
+    context.store.runtime((now) => {
+        context.store.db
+            .prepare(`UPDATE runtime_index_generations
+         SET state='retired'
+         WHERE embedding_space=? AND state='active' AND generation<>?`)
+            .run(manifest.embeddingSpace, generation);
+        context.store.db
+            .prepare(`UPDATE runtime_index_generations
+         SET state='active', activated_at=?
+         WHERE embedding_space=? AND generation=?`)
+            .run(now, manifest.embeddingSpace, generation);
+    });
+    return { manifestId, generation };
+}
+async function queryTemporalIndex(context, providers, query, prepared) {
+    return resultOf(async () => {
+        validateQuery(query, prepared?.reference);
+        if (prepared)
+            validatePreparedReference(prepared.reference, prepared.options);
+        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 candidates = new Map(segments.map((segment) => [
+            segment.segment_id,
+            { segment, signals: [], score: 0 },
+        ]));
+        if (query.text) {
+            if (allowsLexical(query.modalities)) {
+                addLexicalSignals(context, candidates, query.text, active);
+            }
+            if (allowsSemanticVector(query.modalities)) {
+                await addTextVectorSignals(context, providers, candidates, query.text, active);
+            }
+        }
+        if (query.reference) {
+            addReferenceSignals(context, candidates, query.reference, active);
+        }
+        if (prepared) {
+            addPreparedReferenceSignals(context, candidates, prepared.reference, prepared.options, active);
+        }
+        const ranked = [...candidates.values()]
+            .filter((candidate) => (!query.sourceArtifactIds
+            || query.sourceArtifactIds.includes(candidate.segment.artifact_id))
+            && (!query.artifactKinds
+                || query.artifactKinds.includes(candidate.segment.artifact_kind)))
+            .map((candidate) => ({
+            ...candidate,
+            signals: candidate.signals.filter((signal) => allowsSignal(query.modalities, signal.kind)),
+        }))
+            .filter((candidate) => candidate.signals.length > 0)
+            .map(finalizeCandidate)
+            .filter((candidate) => candidate.score >= (query.minScore ?? 0))
+            .sort(compareCandidates);
+        const deduplicated = collapseOverlaps(ranked);
+        const limit = Math.min(query.limit ?? 20, 100);
+        const page = deduplicated.slice(offset, offset + limit);
+        return {
+            hits: page.map(candidateToHit),
+            ...(offset + limit < deduplicated.length
+                ? {
+                    nextCursor: encodeCursor(generationKey, offset + limit),
+                }
+                : {}),
+            coverage: searchCoverage(context),
+        };
+    });
+}
+function allowsLexical(modalities) {
+    return (!modalities
+        || modalities.includes("auto")
+        || modalities.some((item) => item === "speech" || item === "ocr" || item === "metadata"));
+}
+function allowsSemanticVector(modalities) {
+    return (!modalities
+        || modalities.includes("auto")
+        || modalities.some((item) => item === "visual"
+            || item === "audio"
+            || item === "speech"
+            || item === "ocr"));
+}
+function allowsSignal(modalities, signal) {
+    if (!modalities || modalities.includes("auto"))
+        return true;
+    if (signal === "exact" || signal === "near")
+        return true;
+    return modalities.includes(signal);
+}
+function activeGenerations(context) {
+    return context.store.db
+        .prepare(`SELECT embedding_space, generation, manifest_id, state
+       FROM runtime_index_generations
+       WHERE state='active'
+       ORDER BY embedding_space, generation`)
+        .all();
+}
+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);
+    return rows.filter((row) => {
+        if (query.artifactKinds && !query.artifactKinds.includes(row.artifact_kind)) {
+            return false;
+        }
+        if (query.sourceArtifactIds
+            && !query.sourceArtifactIds.includes(row.artifact_id)) {
+            return false;
+        }
+        if (query.createdAfter !== undefined
+            && row.artifact_created_at <= query.createdAfter) {
+            return false;
+        }
+        if (query.createdBefore !== undefined
+            && 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.indexingStates
+            && !query.indexingStates.includes(artifactGenerationState(context, row.artifact_id, row.generation))) {
+            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;
+                }
+            }
+        }
+        return true;
+    });
+}
+function artifactHasLabels(context, artifactId, requested) {
+    const row = context.store.db
+        .prepare(`SELECT value_json FROM artifact_metadata
+       WHERE artifact_id=? AND key='labels'`)
+        .get(artifactId);
+    const labels = row ? parseJson(row.value_json, []) : [];
+    return requested.every((label) => labels.includes(label));
+}
+function artifactOrientation(context, artifactId) {
+    const row = context.store.db
+        .prepare(`SELECT profile_json FROM artifact_streams
+       WHERE artifact_id=? AND kind='video'
+       ORDER BY stream_index LIMIT 1`)
+        .get(artifactId);
+    const profile = row
+        ? parseJson(row.profile_json, {})
+        : {};
+    const width = profile.video?.width ?? 1;
+    const height = profile.video?.height ?? 1;
+    if (width === height)
+        return "square";
+    return width > height ? "landscape" : "portrait";
+}
+function artifactGenerationState(context, artifactId, generation) {
+    const rows = context.store.db
+        .prepare(`SELECT state FROM runtime_index_coverage
+       WHERE artifact_id=? AND generation=?`)
+        .all(artifactId, generation);
+    return aggregateCoverageState(rows);
+}
+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 normalized = text.trim().toLocaleLowerCase();
+    const quoted = [...text.matchAll(/"([^"]+)"/g)]
+        .map((match) => match[1]?.trim().toLocaleLowerCase())
+        .filter((item) => Boolean(item));
+    const terms = normalized
+        .replaceAll('"', "")
+        .split(/\s+/)
+        .filter((term) => term.length > 1);
+    const matches = rows
+        .map((row) => {
+        const haystack = row.text.toLocaleLowerCase();
+        const exact = quoted.some((phrase) => haystack.includes(phrase));
+        const termCount = terms.filter((term) => haystack.includes(term)).length;
+        return {
+            row,
+            exact,
+            score: (exact ? 2 : 0)
+                + (terms.length === 0 ? 0 : termCount / terms.length),
+        };
+    })
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score
+        || left.row.segment_id.localeCompare(right.row.segment_id));
+    matches.forEach((match, index) => {
+        const candidate = candidates.get(match.row.segment_id);
+        if (!candidate)
+            return;
+        candidate.signals.push({
+            kind: match.row.kind === "ocr"
+                ? "ocr"
+                : match.row.kind === "transcript"
+                    ? "speech"
+                    : "metadata",
+            rank: index + 1,
+            score: match.score,
+            explanation: match.exact
+                ? "Exact quoted text matched this moment"
+                : "Query terms matched indexed text",
+        });
+        if (!candidate.excerpt || match.exact)
+            candidate.excerpt = match.row.text;
+    });
+}
+async function addTextVectorSignals(context, providers, candidates, text, active) {
+    for (const generation of active) {
+        const provider = providers.get(generation.manifest_id);
+        if (!provider)
+            continue;
+        const manifest = requiredManifest(context, generation.manifest_id);
+        await provider.prepare();
+        const queryVector = provider.embedText(text);
+        const resolved = await queryVector;
+        if (resolved.length !== manifest.dimensions) {
+            throw new EngineFault({
+                code: "MANIFEST_INCOMPATIBLE",
+                message: "Query provider returned incompatible vector dimensions",
+            });
+        }
+        for (const modality of manifest.modalities) {
+            if (modality === "metadata")
+                continue;
+            rankVectorRows(context, candidates, generation, resolved, modality, `Text-to-${modality} semantic similarity`);
+        }
+    }
+}
+function addReferenceSignals(context, candidates, reference, active) {
+    for (const generation of active) {
+        if (reference.kind === "video") {
+            addOrderedVideoSignals(context, candidates, reference.range, generation);
+            continue;
+        }
+        const queryRows = referenceEmbeddingRows(context, reference, generation);
+        if (queryRows.length === 0)
+            continue;
+        const queryVector = averageVectors(queryRows.map((row) => blobToVector(row.vector_blob, row.dimensions)));
+        const modality = reference.kind === "audio" ? "audio" : "visual";
+        rankVectorRows(context, candidates, generation, queryVector, modality, `${reference.kind} reference similarity`);
+        addFingerprintSignals(context, candidates, queryRows, generation);
+    }
+}
+function addOrderedVideoSignals(context, candidates, rangeInput, generation) {
+    const range = normalizeSourceRange(rangeInput);
+    const query = orderedEmbeddings(context, generation, (segmentRangeValue) => segmentRangeValue.streamId === range.streamId
+        && segmentRangeValue.objectHash === range.objectHash
+        && 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);
+}
+function addPreparedReferenceSignals(context, candidates, reference, options, active) {
+    for (const generation of active) {
+        if (generation.embedding_space !== reference.embeddingSpace)
+            continue;
+        const manifest = requiredManifest(context, generation.manifest_id);
+        if (reference.kind === "image") {
+            const queryVector = preparedVector(reference.vector, manifest.dimensions);
+            rankVectorRows(context, candidates, generation, queryVector, "visual", "Prepared image reference similarity");
+            addPreparedFingerprintSignals(context, candidates, reference.fingerprints ?? [], generation);
+            continue;
+        }
+        const samples = preparedVideoSamples(reference, options);
+        for (const sample of samples) {
+            preparedVector(sample.vector, manifest.dimensions);
+        }
+        addOrderedVideoVectorSignals(context, candidates, samples.map((sample) => ({
+            vector: Float32Array.from(sample.vector),
+        })), generation);
+    }
+}
+function addOrderedVideoVectorSignals(context, candidates, sample, generation) {
+    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 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);
+            windows.push({
+                values: window,
+                score: aligned * 0.75 + coherence * 0.25,
+                coherence,
+            });
+        }
+    }
+    windows
+        .sort((left, right) => right.score - left.score
+        || left.values[0].segment.segment_id.localeCompare(right.values[0].segment.segment_id))
+        .forEach((window, index) => {
+        const first = window.values[0];
+        const last = window.values.at(-1);
+        const combined = {
+            ...first.range,
+            durationTicks: sourceRangeEndTick(last.range) - first.range.startTick,
+        };
+        const segmentId = `ordered:${generation.generation}:${first.segment.segment_id}:${last.segment.segment_id}`;
+        const candidate = {
+            segment: {
+                ...first.segment,
+                segment_id: segmentId,
+                source_range_json: canonicalJson(combined),
+                representative_tick: first.range.startTick + Math.floor(combined.durationTicks / 2),
+            },
+            signals: [
+                {
+                    kind: "visual",
+                    rank: index + 1,
+                    score: window.score,
+                    explanation: `Ordered video alignment with temporal coherence ${window.coherence.toFixed(3)}`,
+                },
+            ],
+            score: 0,
+        };
+        candidates.set(segmentId, candidate);
+    });
+}
+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),
+                }]
+            : [];
+    });
+}
+function transitionCoherence(query, candidate) {
+    if (query.length < 2)
+        return 1;
+    let score = 0;
+    for (let index = 1; index < query.length; index += 1) {
+        score += cosineSimilarity(vectorDifference(query[index].vector, query[index - 1].vector), vectorDifference(candidate[index].vector, candidate[index - 1].vector));
+    }
+    return score / (query.length - 1);
+}
+function vectorDifference(left, right) {
+    const result = new Float32Array(left.length);
+    for (let index = 0; index < left.length; index += 1) {
+        result[index] = left[index] - right[index];
+    }
+    return result;
+}
+function evenlySample(values, count) {
+    if (count <= 1)
+        return values.length === 0 ? [] : [values[0]];
+    if (count >= values.length)
+        return values;
+    return Array.from({ length: count }, (_, index) => {
+        const position = Math.round((index * (values.length - 1)) / (count - 1));
+        return values[position];
+    });
+}
+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))
+        .forEach((item, index) => {
+        const candidate = candidates.get(item.row.segment_id);
+        if (!candidate)
+            return;
+        candidate.signals.push({
+            kind: modality,
+            rank: index + 1,
+            score: item.score,
+            explanation,
+        });
+    });
+}
+function referenceEmbeddingRows(context, reference, generation) {
+    const segments = referenceSegments(context, reference, generation.generation);
+    if (segments.length === 0)
+        return [];
+    const placeholders = segments.map(() => "?").join(",");
+    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=?
+       ORDER BY segment_id`)
+        .all(...segments, generation.embedding_space);
+}
+function referenceSegments(context, reference, generation) {
+    if (reference.kind === "image") {
+        const artifact = context.artifactRow(reference.artifact);
+        return context.store.db
+            .prepare(`SELECT segment_id FROM runtime_media_segments
+           WHERE generation=? AND artifact_id=?
+           ORDER BY segment_id`)
+            .all(generation, artifact.artifact_id).map((row) => row.segment_id);
+    }
+    const range = reference.kind === "frame"
+        ? undefined
+        : normalizeSourceRange(reference.range);
+    const point = reference.kind === "frame"
+        ? normalizeSourcePoint(reference.source)
+        : undefined;
+    const rows = context.store.db
+        .prepare(`SELECT segment_id, source_range_json
+       FROM runtime_media_segments
+       WHERE generation=? AND stream_id=? AND object_hash=?
+       ORDER BY representative_tick, segment_id`)
+        .all(generation, point?.streamId ?? range?.streamId, point?.objectHash ?? range?.objectHash);
+    return rows
+        .filter((row) => {
+        if (!row.source_range_json)
+            return false;
+        const candidate = parseJson(row.source_range_json, null);
+        if (!candidate)
+            return false;
+        if (point) {
+            return (candidate.startTick <= point.tick
+                && point.tick < sourceRangeEndTick(candidate));
+        }
+        return range
+            ? rangesOverlap(candidate.startTick, sourceRangeEndTick(candidate), range.startTick, sourceRangeEndTick(range))
+            : false;
+    })
+        .map((row) => row.segment_id);
+}
+function addFingerprintSignals(context, candidates, queryRows, generation) {
+    const segmentIds = unique(queryRows.map((row) => row.segment_id));
+    if (segmentIds.length === 0)
+        return;
+    const fingerprints = context.store.db
+        .prepare(`SELECT kind, value FROM runtime_segment_fingerprints
+       WHERE segment_id IN (${segmentIds.map(() => "?").join(",")})
+       ORDER BY kind, value`)
+        .all(...segmentIds);
+    addPreparedFingerprintSignals(context, candidates, fingerprints, generation);
+}
+function addPreparedFingerprintSignals(context, candidates, fingerprints, generation) {
+    for (const fingerprint of fingerprints) {
+        const rows = context.store.db
+            .prepare(`SELECT segment_id FROM runtime_segment_fingerprints
+         WHERE generation=? AND kind=? AND value=?
+         ORDER BY segment_id`)
+            .all(generation.generation, fingerprint.kind, fingerprint.value);
+        rows.forEach((row, index) => {
+            const candidate = candidates.get(row.segment_id);
+            if (!candidate)
+                return;
+            candidate.signals.push({
+                kind: fingerprint.kind === "sha256" ? "exact" : "near",
+                rank: index + 1,
+                score: 1,
+                explanation: fingerprint.kind === "sha256"
+                    ? "Exact source fingerprint matched"
+                    : "Near-duplicate fingerprint matched",
+            });
+        });
+    }
+}
+function finalizeCandidate(candidate) {
+    const sortedSignals = [...candidate.signals].sort((left, right) => signalPriority(left.kind) - signalPriority(right.kind)
+        || left.rank - right.rank);
+    const rrf = sortedSignals.reduce((sum, signal) => sum + 1 / (60 + signal.rank), 0);
+    const exactBoost = sortedSignals.some((signal) => signal.kind === "exact")
+        ? 1
+        : sortedSignals.some((signal) => signal.kind === "near")
+            ? 0.25
+            : 0;
+    return { ...candidate, signals: sortedSignals, score: rrf + exactBoost };
+}
+function compareCandidates(left, right) {
+    return (right.score - left.score
+        || left.segment.artifact_id.localeCompare(right.segment.artifact_id)
+        || locationKey(left.segment).localeCompare(locationKey(right.segment))
+        || left.segment.segment_id.localeCompare(right.segment.segment_id));
+}
+function collapseOverlaps(candidates) {
+    const accepted = [];
+    const intervals = new Map();
+    for (const candidate of candidates) {
+        const range = segmentRange(candidate.segment);
+        if (!range) {
+            accepted.push(candidate);
+            continue;
+        }
+        const key = `${candidate.segment.artifact_id}\u0000${range.streamId}`;
+        const interval = {
+            start: range.startTick,
+            end: sourceRangeEndTick(range),
+            duration: range.durationTicks,
+            segmentId: candidate.segment.segment_id,
+        };
+        const root = intervals.get(key) ?? null;
+        if (hasDuplicateInterval(root, interval))
+            continue;
+        intervals.set(key, insertInterval(root, interval));
+        accepted.push(candidate);
+    }
+    return accepted;
+}
+function hasDuplicateInterval(node, candidate) {
+    if (!node || node.maxEnd <= candidate.start)
+        return false;
+    if (node.left
+        && node.left.maxEnd > candidate.start
+        && hasDuplicateInterval(node.left, candidate)) {
+        return true;
+    }
+    const other = node.interval;
+    if (other.start < candidate.end) {
+        const overlap = Math.max(0, Math.min(candidate.end, other.end) - Math.max(candidate.start, other.start));
+        if (overlap / Math.min(candidate.duration, other.duration) >= 0.8) {
+            return true;
+        }
+    }
+    else {
+        return false;
+    }
+    return hasDuplicateInterval(node.right, candidate);
+}
+function insertInterval(node, interval) {
+    if (!node) {
+        return {
+            interval,
+            priority: intervalPriority(interval),
+            maxEnd: interval.end,
+            left: null,
+            right: null,
+        };
+    }
+    if (compareIntervals(interval, node.interval) < 0) {
+        node.left = insertInterval(node.left, interval);
+        if (node.left.priority > node.priority)
+            node = rotateIntervalRight(node);
+    }
+    else {
+        node.right = insertInterval(node.right, interval);
+        if (node.right.priority > node.priority)
+            node = rotateIntervalLeft(node);
+    }
+    refreshMaxEnd(node);
+    return node;
+}
+function rotateIntervalLeft(node) {
+    const pivot = node.right;
+    if (!pivot)
+        return node;
+    node.right = pivot.left;
+    pivot.left = node;
+    refreshMaxEnd(node);
+    refreshMaxEnd(pivot);
+    return pivot;
+}
+function rotateIntervalRight(node) {
+    const pivot = node.left;
+    if (!pivot)
+        return node;
+    node.left = pivot.right;
+    pivot.right = node;
+    refreshMaxEnd(node);
+    refreshMaxEnd(pivot);
+    return pivot;
+}
+function refreshMaxEnd(node) {
+    node.maxEnd = Math.max(node.interval.end, node.left?.maxEnd ?? Number.NEGATIVE_INFINITY, node.right?.maxEnd ?? Number.NEGATIVE_INFINITY);
+}
+function compareIntervals(left, right) {
+    return (left.start - right.start
+        || left.end - right.end
+        || left.segmentId.localeCompare(right.segmentId));
+}
+function intervalPriority(interval) {
+    let hash = 2_166_136_261;
+    const key = `${interval.segmentId}:${interval.start}:${interval.end}`;
+    for (let index = 0; index < key.length; index += 1) {
+        hash ^= key.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return hash >>> 0;
+}
+function candidateToHit(candidate) {
+    return {
+        artifactId: candidate.segment.artifact_id,
+        artifactSlug: candidate.segment.artifact_slug,
+        artifactKind: candidate.segment.artifact_kind,
+        location: segmentLocation(candidate.segment),
+        ...(candidate.segment.representative_tick === null
+            ? {}
+            : { representativeTick: candidate.segment.representative_tick }),
+        score: candidate.score,
+        signals: candidate.signals,
+        ...(candidate.excerpt ? { excerpt: candidate.excerpt } : {}),
+        indexManifestIds: [candidate.segment.manifest_id],
+    };
+}
+function segmentLocation(segment) {
+    const range = segmentRange(segment);
+    if (range) {
+        return {
+            kind: "timed",
+            artifactId: segment.artifact_id,
+            range,
+        };
+    }
+    return {
+        kind: segment.segment_kind === "document" ? "document" : "still",
+        artifactId: segment.artifact_id,
+        sourcePath: segment.source_path ?? "unknown",
+        objectHash: segment.object_hash,
+        ...(segment.segment_kind === "document"
+            ? { startUtf8Byte: 0, endUtf8Byte: 1 }
+            : {}),
+    };
+}
+function segmentRange(segment) {
+    return segment.source_range_json
+        ? parseJson(segment.source_range_json, null)
+        : null;
+}
+function locationKey(segment) {
+    return canonicalJson(segmentLocation(segment));
+}
+function searchCoverage(context, artifactReference) {
+    const artifactId = artifactReference
+        ? context.artifactRow(artifactReference).artifact_id
+        : undefined;
+    const active = activeGenerations(context);
+    const rows = coverageRows(context, artifactId
+        ? `WHERE artifact_id=? AND generation IN (${active.map(() => "?").join(",")})`
+        : active.length > 0
+            ? `WHERE generation IN (${active.map(() => "?").join(",")})`
+            : "WHERE 1=0", artifactId
+        ? [artifactId, ...active.map((item) => item.generation)]
+        : active.map((item) => item.generation));
+    const allArtifacts = context.store.db
+        .prepare("SELECT COUNT(*) AS count FROM artifacts")
+        .get();
+    const indexedArtifactCount = new Set(rows.map((row) => row.artifactId)).size;
+    const state = aggregateCoverageState(rows);
+    const generation = hashJson(active.map((item) => [item.embedding_space, item.generation]));
+    const modalities = unique(active.flatMap((item) => requiredManifest(context, item.manifest_id).modalities)).map((modality) => {
+        const relevant = rows.filter((row) => phaseForModality(modality) === row.phase);
+        return {
+            modality,
+            state: aggregateCoverageState(relevant),
+            indexedUnits: relevant.reduce((sum, row) => sum + row.indexedUnits, 0),
+            ...(relevant.some((row) => row.totalUnits !== undefined)
+                ? {
+                    totalUnits: relevant.reduce((sum, row) => sum + (row.totalUnits ?? 0), 0),
+                }
+                : {}),
+            languageCoverage: modality === "speech" || modality === "ocr"
+                ? "best-effort"
+                : "unsupported",
+            manifestId: active.find((item) => requiredManifest(context, item.manifest_id).modalities.includes(modality))?.manifest_id,
+        };
+    });
+    return {
+        state,
+        generation,
+        modalities,
+        indexedArtifactCount,
+        totalArtifactCount: artifactId ? 1 : allArtifacts.count,
+        partialResults: state !== "ready",
+    };
+}
+function coverageRows(context, clause, params) {
+    const rows = context.store.db
+        .prepare(`SELECT artifact_id, object_hash, manifest_id, generation, phase,
+              state, covered_ranges_json, indexed_units, total_units,
+              retryable, error_json, cursor, updated_at
+       FROM runtime_index_coverage ${clause}
+       ORDER BY artifact_id, manifest_id, generation, phase`)
+        .all(...params);
+    return rows.map((row) => ({
+        artifactId: row.artifact_id,
+        objectHash: row.object_hash,
+        manifestId: row.manifest_id,
+        phase: row.phase,
+        state: row.state,
+        coveredRanges: parseJson(row.covered_ranges_json, []),
+        indexedUnits: row.indexed_units,
+        ...(row.total_units === null ? {} : { totalUnits: row.total_units }),
+        ...(row.cursor === null ? {} : { nextCursor: row.cursor }),
+        retryable: row.retryable === 1,
+        ...(row.error_json
+            ? { error: parseJson(row.error_json, {
+                    code: "INTERNAL_ERROR",
+                    message: "Unknown index error",
+                }) }
+            : {}),
+        updatedAt: row.updated_at,
+    }));
+}
+function invalidateCoverage(context, artifactReference, objectHash) {
+    const artifact = context.artifactRow(artifactReference);
+    return context.store.runtime((now) => {
+        const result = objectHash
+            ? context.store.db
+                .prepare(`UPDATE runtime_index_coverage
+             SET state='stale', updated_at=?
+             WHERE artifact_id=? AND object_hash=?`)
+                .run(now, artifact.artifact_id, objectHash)
+            : context.store.db
+                .prepare(`UPDATE runtime_index_coverage
+             SET state='stale', updated_at=?
+             WHERE artifact_id=?`)
+                .run(now, artifact.artifact_id);
+        return Number(result.changes);
+    });
+}
+function cleanupRetired(context) {
+    return context.store.runtime(() => {
+        const retired = context.store.db
+            .prepare(`SELECT generation FROM runtime_index_generations
+           WHERE state='retired'`)
+            .all().map((row) => row.generation);
+        if (retired.length === 0)
+            return { removedSegments: 0 };
+        const placeholders = retired.map(() => "?").join(",");
+        const result = context.store.db
+            .prepare(`DELETE FROM runtime_media_segments
+         WHERE generation IN (${placeholders})`)
+            .run(...retired);
+        context.store.db
+            .prepare(`DELETE FROM runtime_index_coverage
+         WHERE generation IN (${placeholders})`)
+            .run(...retired);
+        context.store.db
+            .prepare(`DELETE FROM runtime_index_batches
+         WHERE generation IN (${placeholders})`)
+            .run(...retired);
+        context.store.db
+            .prepare(`DELETE FROM runtime_index_generations
+         WHERE generation IN (${placeholders})`)
+            .run(...retired);
+        return { removedSegments: Number(result.changes) };
+    });
+}
+function temporalStats(context) {
+    const count = (table, clause = "") => context.store.db
+        .prepare(`SELECT COUNT(*) AS count FROM ${table} ${clause}`)
+        .get().count;
+    return {
+        activeGenerations: count("runtime_index_generations", "WHERE state='active'"),
+        segments: count("runtime_media_segments"),
+        textObservations: count("runtime_segment_text"),
+        embeddings: count("runtime_segment_embeddings"),
+        fingerprints: count("runtime_segment_fingerprints"),
+    };
+}
+function assertArtifactObject(context, artifactId, objectHash) {
+    const object = context.store.db
+        .prepare(`SELECT 1 AS present FROM artifact_files
+       WHERE artifact_id=? AND object_hash=? LIMIT 1`)
+        .get(artifactId, objectHash);
+    if (!object) {
+        throw new EngineFault({
+            code: "OBJECT_UNAVAILABLE",
+            message: "Artifact does not currently reference the requested object",
+            details: { artifactId, objectHash },
+        });
+    }
+}
+function validateQuery(query, prepared) {
+    if (!query.text && !query.reference && !prepared) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Search requires text, reference media, or both",
+        });
+    }
+    if (query.reference && prepared) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Search cannot combine artifact and prepared references",
+        });
+    }
+    if (query.text !== undefined)
+        requiredText(query.text, "Search text");
+    if (query.limit !== undefined)
+        safeIntegerAtLeast(query.limit, 1, "Search limit");
+    if (query.minScore !== undefined && !Number.isFinite(query.minScore)) {
+        throw new Error("Search minScore must be finite");
+    }
+}
+function validatePreparedReference(reference, options) {
+    requiredText(reference.embeddingSpace, "Prepared reference embedding space");
+    if (reference.kind === "image") {
+        preparedVector(reference.vector);
+        if (options.range) {
+            throw new EngineFault({
+                code: "INVALID_INPUT",
+                message: "Image references do not accept a time range",
+            });
+        }
+        for (const fingerprint of reference.fingerprints ?? []) {
+            requiredText(fingerprint.kind, "Prepared fingerprint kind");
+            requiredText(fingerprint.value, "Prepared fingerprint value");
+        }
+        return;
+    }
+    if (reference.samples.length === 0 || reference.samples.length > 16) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Prepared video references require between 1 and 16 samples",
+        });
+    }
+    let previousOffset = -1;
+    for (const sample of reference.samples) {
+        if (!Number.isFinite(sample.offsetMs) || sample.offsetMs < 0) {
+            throw new EngineFault({
+                code: "INVALID_INPUT",
+                message: "Prepared video sample offsets must be finite and non-negative",
+            });
+        }
+        if (sample.offsetMs <= previousOffset) {
+            throw new EngineFault({
+                code: "INVALID_INPUT",
+                message: "Prepared video sample offsets must be strictly increasing",
+            });
+        }
+        previousOffset = sample.offsetMs;
+        preparedVector(sample.vector);
+    }
+    const range = options.range;
+    if (range) {
+        if (!Number.isFinite(range.startMs) || range.startMs < 0) {
+            throw new EngineFault({
+                code: "INVALID_RANGE",
+                message: "Prepared video range start must be finite and non-negative",
+            });
+        }
+        if (range.durationMs !== undefined
+            && (!Number.isFinite(range.durationMs) || range.durationMs <= 0)) {
+            throw new EngineFault({
+                code: "INVALID_RANGE",
+                message: "Prepared video range duration must be finite and positive",
+            });
+        }
+    }
+    preparedVideoSamples(reference, options);
+}
+function preparedVideoSamples(reference, options) {
+    const range = options.range;
+    const endMs = range?.durationMs === undefined
+        ? Number.POSITIVE_INFINITY
+        : range.startMs + range.durationMs;
+    const samples = range
+        ? reference.samples.filter((sample) => sample.offsetMs >= range.startMs && sample.offsetMs <= endMs)
+        : reference.samples;
+    if (samples.length === 0) {
+        throw new EngineFault({
+            code: "INVALID_RANGE",
+            message: "Prepared video range does not contain a sampled frame",
+        });
+    }
+    return samples;
+}
+function preparedVector(vector, dimensions) {
+    if (!Array.isArray(vector)
+        || vector.length === 0
+        || vector.some((value) => !Number.isFinite(value))) {
+        throw new EngineFault({
+            code: "INVALID_INPUT",
+            message: "Prepared reference vectors must contain finite values",
+        });
+    }
+    if (dimensions !== undefined && vector.length !== dimensions) {
+        throw new EngineFault({
+            code: "MANIFEST_INCOMPATIBLE",
+            message: "Prepared reference vector dimensions do not match the index",
+        });
+    }
+    return Float32Array.from(vector);
+}
+function aggregateCoverageState(rows) {
+    if (rows.length === 0)
+        return "not-indexed";
+    if (rows.some((row) => row.state === "failed"))
+        return "failed";
+    if (rows.some((row) => row.state === "stale"))
+        return "stale";
+    if (rows.every((row) => row.state === "ready"))
+        return "ready";
+    return "partial";
+}
+function phaseForModality(modality) {
+    if (modality === "visual")
+        return "visual";
+    if (modality === "audio")
+        return "audio";
+    if (modality === "ocr")
+        return "ocr";
+    if (modality === "speech")
+        return "transcript";
+    return "lexical";
+}
+function signalPriority(kind) {
+    return ["exact", "near", "speech", "ocr", "visual", "audio", "metadata"].indexOf(kind);
+}
+function vectorToBlob(vector) {
+    const values = Float32Array.from(vector);
+    return Buffer.from(values.buffer, values.byteOffset, values.byteLength);
+}
+function blobToVector(blob, dimensions) {
+    const bytes = Buffer.from(blob);
+    if (bytes.byteLength !== dimensions * Float32Array.BYTES_PER_ELEMENT) {
+        throw new EngineFault({
+            code: "MANIFEST_INCOMPATIBLE",
+            message: "Stored vector dimensions do not match its byte length",
+        });
+    }
+    const copy = new Uint8Array(bytes);
+    return new Float32Array(copy.buffer);
+}
+function cosineSimilarity(left, right) {
+    if (left.length !== right.length || left.length === 0) {
+        throw new EngineFault({
+            code: "MANIFEST_INCOMPATIBLE",
+            message: "Cannot compare incompatible vector dimensions",
+        });
+    }
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        const leftValue = left[index];
+        const rightValue = right[index];
+        dot += leftValue * rightValue;
+        leftNorm += leftValue * leftValue;
+        rightNorm += rightValue * rightValue;
+    }
+    if (leftNorm === 0 || rightNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}
+function averageVectors(vectors) {
+    const first = vectors[0];
+    if (!first)
+        return new Float32Array();
+    const result = new Float32Array(first.length);
+    for (const vector of vectors) {
+        if (vector.length !== result.length) {
+            throw new EngineFault({
+                code: "MANIFEST_INCOMPATIBLE",
+                message: "Reference vectors have incompatible dimensions",
+            });
+        }
+        vector.forEach((value, index) => {
+            result[index] = result[index] + value;
+        });
+    }
+    for (let index = 0; index < result.length; index += 1) {
+        result[index] = result[index] / vectors.length;
+    }
+    return result;
+}
+function encodeCursor(generation, offset) {
+    return Buffer.from(canonicalJson({ generation, offset }), "utf8").toString("base64url");
+}
+function decodeCursor(cursor, generation) {
+    if (!cursor)
+        return 0;
+    const parsed = parseJson(Buffer.from(cursor, "base64url").toString("utf8"), {});
+    if (parsed.generation !== generation
+        || !Number.isSafeInteger(parsed.offset)
+        || (parsed.offset ?? -1) < 0) {
+        throw new EngineFault({
+            code: "STALE_REVISION",
+            message: "Search cursor belongs to another index generation",
+        });
+    }
+    return parsed.offset;
+}
+function hashJson(value) {
+    return `sha256:${createHash("sha256")
+        .update(canonicalJson(value))
+        .digest("hex")}`;
+}
+function deterministicUuid(namespace, value) {
+    const bytes = createHash("sha256")
+        .update(namespace)
+        .update("\0")
+        .update(value)
+        .digest()
+        .subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+    ].join("-");
+}
+function requiredText(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${label} is required`);
+    return normalized;
+}
+function safeIntegerAtLeast(value, minimum, label) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new Error(`${label} must be a safe integer of at least ${minimum}`);
+    }
+}
+function rangesOverlap(leftStart, leftEnd, rightStart, rightEnd) {
+    return leftStart < rightEnd && rightStart < leftEnd;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=temporal-search.js.map