trueref/docs/features/TRUEREF-0008.md

# TRUEREF-0008 — Hybrid Semantic Search Engine

**Priority:** P1
**Status:** Pending
**Depends On:** TRUEREF-0006, TRUEREF-0007
**Blocks:** TRUEREF-0010 (enhances it)

---

## Overview

Combine FTS5 BM25 keyword search with vector similarity search (cosine similarity over embeddings) using Reciprocal Rank Fusion (RRF) to produce a hybrid ranking that outperforms either approach alone. When embeddings are not available, the system transparently falls back to FTS5-only mode.

---

## Acceptance Criteria

- [ ] `HybridSearchService` that coordinates FTS5 and vector search
- [ ] Cosine similarity search over stored embeddings
- [ ] Reciprocal Rank Fusion for combining ranked lists
- [ ] Graceful degradation to FTS5-only when embeddings unavailable
- [ ] Query embedding generated at search time via the configured provider
- [ ] Results deduplicated by snippet ID (same snippet may appear in both result sets)
- [ ] Configurable `alpha` parameter: weight between FTS5 (0.0) and vector (1.0)
- [ ] Performance: < 300ms for searches over 100k snippets
- [ ] Unit tests with mock embedding provider

---

## Architecture

```
query text
    │
    ├──── FTS5 Search ──────────────┐
    │      (BM25 ranking)           │
    │                               │
    └──── Vector Search ────────────┤
           (cosine similarity)      │
           (embed query first)      │
                                    │
                               RRF Fusion
                                    │
                               Final ranked list
```

---

## Vector Search Implementation

SQLite does not natively support vector operations, so cosine similarity is computed in JavaScript after loading candidate embeddings:

```typescript
function cosineSimilarity(a: Float32Array, b: Float32Array): number {
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

async vectorSearch(
  queryEmbedding: Float32Array,
  repositoryId: string,
  limit: number = 50
): Promise<Array<{ snippetId: string; score: number }>> {
  // Load all embeddings for the repository (filtered)
  const rows = this.db.prepare(`
    SELECT se.snippet_id, se.embedding
    FROM snippet_embeddings se
    JOIN snippets s ON s.id = se.snippet_id
    WHERE s.repository_id = ?
  `).all(repositoryId) as { snippet_id: string; embedding: Buffer }[];

  // Compute cosine similarity for each
  const scored = rows.map(row => {
    const embedding = new Float32Array(
      row.embedding.buffer,
      row.embedding.byteOffset,
      row.embedding.byteLength / 4
    );
    return {
      snippetId: row.snippet_id,
      score: cosineSimilarity(queryEmbedding, embedding),
    };
  });

  // Sort descending by score, return top-k
  return scored
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}
```

**Performance note:** For repositories with > 50k snippets, pre-filtering by FTS5 candidates before computing cosine similarity is recommended. This is a future optimization — for v1, in-memory computation is acceptable.

---

## Reciprocal Rank Fusion

```typescript
function reciprocalRankFusion(
  ...rankings: Array<Array<{ id: string; score: number }>>
): Array<{ id: string; rrfScore: number }> {
  const K = 60; // RRF constant (standard value)
  const scores = new Map<string, number>();

  for (const ranking of rankings) {
    ranking.forEach(({ id }, rank) => {
      const current = scores.get(id) ?? 0;
      scores.set(id, current + 1 / (K + rank + 1));
    });
  }

  return Array.from(scores.entries())
    .map(([id, rrfScore]) => ({ id, rrfScore }))
    .sort((a, b) => b.rrfScore - a.rrfScore);
}
```

---

## Hybrid Search Service

```typescript
export interface HybridSearchOptions {
  repositoryId: string;
  versionId?: string;
  type?: 'code' | 'info';
  limit?: number;
  alpha?: number;          // 0.0 = FTS5 only, 1.0 = vector only, 0.5 = balanced
}

export class HybridSearchService {
  constructor(
    private db: BetterSQLite3.Database,
    private searchService: SearchService,
    private embeddingProvider: EmbeddingProvider | null,
  ) {}

  async search(
    query: string,
    options: HybridSearchOptions
  ): Promise<SnippetSearchResult[]> {
    const limit = options.limit ?? 20;
    const alpha = options.alpha ?? 0.5;

    // Always run FTS5 search
    const ftsResults = this.searchService.searchSnippets(query, {
      repositoryId: options.repositoryId,
      versionId: options.versionId,
      type: options.type,
      limit: limit * 3, // get more candidates for fusion
    });

    // If no embedding provider or alpha = 0, return FTS5 results directly
    if (!this.embeddingProvider || alpha === 0) {
      return ftsResults.slice(0, limit);
    }

    // Embed the query and run vector search
    const [queryEmbedding] = await this.embeddingProvider.embed([query]);
    const vectorResults = await this.vectorSearch(
      queryEmbedding.values,
      options.repositoryId,
      limit * 3
    );

    // Normalize result lists for RRF
    const ftsRanked = ftsResults.map((r, i) => ({
      id: r.snippet.id,
      score: i,
    }));
    const vecRanked = vectorResults.map((r, i) => ({
      id: r.snippetId,
      score: i,
    }));

    // Apply RRF
    const fused = reciprocalRankFusion(ftsRanked, vecRanked);

    // Fetch full snippet data for top results
    const topIds = fused.slice(0, limit).map(r => r.id);
    return this.fetchSnippetsByIds(topIds, options.repositoryId);
  }
}
```

---

## Configuration

The hybrid search alpha value can be set per-request or globally via settings:

```typescript
// Default config stored in settings table under key 'search_config'
export interface SearchConfig {
  alpha: number;           // 0.5 default
  maxResults: number;      // 20 default
  enableHybrid: boolean;   // true if embedding provider is configured
}
```

---

## Files to Create

- `src/lib/server/search/hybrid.search.service.ts`
- `src/lib/server/search/vector.search.ts`
- `src/lib/server/search/rrf.ts`
- `src/lib/server/search/hybrid.search.service.test.ts`