refactor(rag): add HybridRetriever wrapper as app↔lib boundary

Wraps hybridRetrieve in a HybridRetriever class that binds the vector store
and embeddings, exposing a single retrieve(query, options) call as the explicit
app↔react-native-rag boundary. hybridRetrieve is unchanged and still the
production path (messageSources.ts untouched); the class is the boundary/test
seam. No generic and no interface — one impl, one caller; extract an interface
only if a second retriever appears. Deliberately not `implements VectorStore`:
the hybrid is read-only and its ContextChunk output drops id/embedding, so
coercing to QueryResult would change retrieval results.

Test proves 1:1 forwarding with load-bearing attachmentSourceIds and
sourceNamesById, so a spread that dropped either would fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kfaracik

__tests__/hybridRetrieval.test.ts

@@ -1,4 +1,4 @@
-import { hybridRetrieve } from '../utils/hybridRetrieval';
+import { hybridRetrieve, HybridRetriever } from '../utils/hybridRetrieval';
 import * as keywordIndex from '../database/keywordIndex';
 import type { OPSQLiteVectorStore } from '@react-native-rag/op-sqlite';
 
@@ -483,3 +483,60 @@ describe('hybridRetrieve', () => {
     expect(result.map((c) => c.similarity)).toEqual([0, 0.9, 0]);
   });
 });
+
+describe('HybridRetriever', () => {
+  beforeEach(() => {
+    mockKeywordSearch.mockReset();
+  });
+
+  // The cases above already exercise the hybrid logic; this proves the wrapper
+  // forwards 1:1 — query→prompt, store/embeddings from the constructor, and
+  // every option spread through. Inputs are chosen so the two options a naive
+  // spread could silently drop are load-bearing: sourceNamesById resolves doc
+  // 1's missing name, and attachmentSourceIds keeps doc 2's otherwise-gated
+  // low-similarity chunk and orders it first. A wrapper that dropped either
+  // would diverge from the raw call and fail the toEqual.
+  it('forwards to hybridRetrieve 1:1, including attachmentSourceIds and sourceNamesById', async () => {
+    const vectorResults = [
+      {
+        id: '1:0',
+        document: 'a semantic passage about felines',
+        embedding: [1, 0],
+        similarity: 0.8,
+        metadata: { documentId: 1 }, // no name → resolved via sourceNamesById
+      },
+      {
+        id: '2:0',
+        document: 'freshly attached, low semantic overlap',
+        embedding: [0, 1],
+        similarity: 0.05, // gated out unless treated as an attachment
+        metadata: { documentId: 2, name: 'Attachment' },
+      },
+    ];
+    mockKeywordSearch.mockResolvedValue([]);
+
+    const store = makeVectorStore(vectorResults, {});
+    const options = {
+      enabledSourceIds: [1, 2],
+      sourceNamesById: new Map<number, string>([[1, 'ResolvedName']]),
+      attachmentSourceIds: [2],
+    };
+
+    const viaWrapper = await new HybridRetriever(store, null).retrieve(
+      'felines',
+      options
+    );
+    const viaFunction = await hybridRetrieve({
+      prompt: 'felines',
+      vectorStore: store,
+      embeddings: null,
+      ...options,
+    });
+
+    const names = viaWrapper.map((c) => c.metadata?.name);
+    expect(names).toContain('ResolvedName'); // sourceNamesById forwarded
+    expect(names).toContain('Attachment'); // attachmentSourceIds forwarded
+    expect(viaWrapper[0]?.metadata?.name).toBe('Attachment'); // attachment ordered first
+    expect(viaWrapper).toEqual(viaFunction); // and identical to the raw call
+  });
+});

utils/hybridRetrieval.ts

@@ -408,3 +408,34 @@ export const hybridRetrieve = async ({
     sourceNamesById
   );
 };
+
+// Thin app↔library boundary. Binds the store + embeddings so retrieval is a
+// single retrieve(query, options) call, making the hybrid testable and portable
+// in isolation. It forwards to hybridRetrieve unchanged — no interface, because
+// there is one implementation and one caller; extract a Retriever interface only
+// if a second retriever ever appears. Deliberately NOT `implements VectorStore`:
+// the hybrid is read-only and its ContextChunk output drops id/embedding, so
+// coercing to QueryResult would change retrieval results.
+export type HybridRetrieveOptions = Omit<
+  HybridRetrieveParams,
+  'prompt' | 'vectorStore' | 'embeddings'
+>;
+
+export class HybridRetriever {
+  constructor(
+    private vectorStore: OPSQLiteVectorStore,
+    private embeddings?: LFMEmbeddings | null
+  ) {}
+
+  retrieve(
+    query: string,
+    options: HybridRetrieveOptions
+  ): Promise<ContextChunk[]> {
+    return hybridRetrieve({
+      prompt: query,
+      vectorStore: this.vectorStore,
+      embeddings: this.embeddings,
+      ...options,
+    });
+  }
+}