mnemonad-cli 0.1.1 → 0.3.0

package/lib/search/Indexer.js

@@ -0,0 +1,204 @@
+import { existsSync, rmSync } from 'node:fs';
+import VectorIndex from './VectorIndex.js';
+import TextWindowChunkingStrategy from './chunking/TextWindowChunkingStrategy.js';
+
+/** First N bytes checked for a null byte — the standard, cheap heuristic (same one git and
+ *  most diff tools use) for "this is almost certainly binary, don't try to embed it as text". */
+const BINARY_SNIFF_BYTES = 8000;
+
+function looksLikeText(bytes) {
+	const n = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+	for (let i = 0; i < n; i++) {
+		if (bytes[i] === 0) return false;
+	}
+	return true;
+}
+
+function toHex(bytes) {
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Builds/updates a `VectorIndex` from a folder — anything shaped like
+ * `@fizzyflow/doublesync`'s `DoubleSyncFolder` (has an async `walk()` generator), which
+ * covers the CLI's real-disk `FSFolder` and any in-memory folder the same way. Incremental by
+ * construction: a file whose content hash already matches what's stored is skipped entirely,
+ * no re-embedding, no re-chunking, not even a read past the hash check.
+ */
+export default class Indexer {
+	/**
+	 * @param {Object} [params]
+	 * @param {?import('./embeddings/EmbeddingProvider.js').default} [params.embeddingProvider] -
+	 *   required by `index()`; `status()` never embeds, so it can go without one (see
+	 *   providers.js's createProvider for the usual way to get one).
+	 * @param {import('./chunking/ChunkingStrategy.js').default} [params.chunkingStrategy]
+	 */
+	constructor({ embeddingProvider = null, chunkingStrategy } = {}) {
+		this.embeddingProvider = embeddingProvider;
+		this.chunkingStrategy = chunkingStrategy || new TextWindowChunkingStrategy();
+	}
+
+	/**
+	 * What `index()` would do to `dbPath`, without doing it: no embedding, no model load, and
+	 * the database opened read-only. Uses the same walk and the same rules as `index()` (see
+	 * `_scan`), so it agrees exactly on which files count — a binary or empty file, which
+	 * `index()` never records, isn't reported as missing from the index.
+	 *
+	 * @param {import('@fizzyflow/doublesync').DoubleSyncFolder} folder
+	 * @param {string} dbPath
+	 * @returns {Promise<?{changed: string[], added: string[], removed: string[]}>} null when
+	 *   there's no index at `dbPath` at all.
+	 */
+	async status(folder, dbPath) {
+		if (!existsSync(dbPath)) return null;
+		const index = new VectorIndex(dbPath, { readonly: true });
+		try {
+			const indexed = new Set(index.listFiles());
+			const changed = [];
+			const added = [];
+			const seen = new Set();
+			for await (const entry of this._scan(folder, index)) {
+				// An emptied file is left out of `seen`, so it comes out as removed below —
+				// exactly what index() would do to it.
+				if (!entry.unchanged && !entry.chunks) continue;
+				seen.add(entry.relPath);
+				if (entry.unchanged) continue;
+				(indexed.has(entry.relPath) ? changed : added).push(entry.relPath);
+			}
+			const removed = [...indexed].filter((p) => !seen.has(p));
+			return { changed, added, removed };
+		} finally {
+			index.close();
+		}
+	}
+
+	/**
+	 * The walk both `index()` and `status()` run. Yields one entry per text file:
+	 * `{relPath, unchanged: true}` when the index already has it at this content hash, or
+	 * `{relPath, hash, chunks}` otherwise (`chunks` null for a file with no text to embed).
+	 */
+	async *_scan(folder, index) {
+		for await (const { path, file } of folder.walk()) {
+			const relPath = path.join('/');
+			const bytes = await file.getContent();
+			if (!looksLikeText(bytes)) continue;
+
+			const hash = toHex(await file.getFingerprint());
+			if (index.getFileHash(relPath) === hash) {
+				yield { relPath, unchanged: true };
+				continue;
+			}
+
+			const text = new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+			const chunks = this.chunkingStrategy.chunk(text);
+			yield { relPath, hash, chunks: chunks.length > 0 ? chunks : null };
+		}
+	}
+
+	/**
+	 * @param {import('@fizzyflow/doublesync').DoubleSyncFolder} folder
+	 * @param {string} dbPath
+	 * @param {Object} [opts]
+	 * @param {boolean} [opts.rebuild] - start from an empty index instead of updating this one:
+	 *   every file is embedded again. The one way to switch an index to a different model — and,
+	 *   since it rewrites the whole file, the next push carries the full index again.
+	 * @returns {Promise<{filesChanged: number, filesSkipped: number, filesRemoved: number, chunksAdded: number}>}
+	 */
+	async index(folder, dbPath, { rebuild = false } = {}) {
+		if (!this.embeddingProvider) throw new Error('Indexer.index: no embeddingProvider configured');
+		if (rebuild) {
+			rmSync(dbPath, { force: true });
+			rmSync(`${dbPath}-journal`, { force: true });
+		} else {
+			assertSameModel(VectorIndex.readMeta(dbPath), this.embeddingProvider, dbPath);
+		}
+		const index = new VectorIndex(dbPath);
+		try {
+			const seenPaths = new Set();
+			// One entry per changed/new file, chunked but not yet embedded — embedding happens
+			// in one batched call across every changed file below, rather than one call per
+			// file, since a single call amortizes the model's own fixed per-call overhead.
+			const pending = [];
+			let filesSkipped = 0;
+
+			for await (const entry of this._scan(folder, index)) {
+				// A file with no text to embed (emptied since last time) is deliberately left out
+				// of seenPaths, so the removal pass below drops its old chunks like a deleted file's.
+				if (entry.unchanged) {
+					seenPaths.add(entry.relPath);
+					filesSkipped++;
+				} else if (entry.chunks) {
+					seenPaths.add(entry.relPath);
+					pending.push(entry);
+				}
+			}
+
+			let chunksAdded = 0;
+			if (pending.length > 0) {
+				const allTexts = pending.flatMap((p) => p.chunks.map((c) => c.text));
+				const allVectors = await this.embeddingProvider.embed(allTexts);
+				index.initVectorColumn(this.embeddingProvider.dimension);
+
+				let cursor = 0;
+				for (const p of pending) {
+					const vectors = allVectors.slice(cursor, cursor + p.chunks.length);
+					cursor += p.chunks.length;
+					index.replaceFileChunks(p.relPath, p.hash, p.chunks.map((c, i) => ({
+						startOffset: c.startOffset,
+						endOffset: c.endOffset,
+						embedding: vectors[i],
+					})));
+					chunksAdded += p.chunks.length;
+				}
+
+				index.setMeta('model', this.embeddingProvider.modelId);
+				if (this.embeddingProvider.embedder) index.setMeta('embedder', this.embeddingProvider.embedder);
+				index.setMeta('dimension', String(this.embeddingProvider.dimension));
+				if (this.embeddingProvider.dtype) index.setMeta('dtype', this.embeddingProvider.dtype);
+				index.setMeta('chunk_size', String(this.chunkingStrategy.size ?? ''));
+				index.setMeta('chunk_overlap', String(this.chunkingStrategy.overlap ?? ''));
+			} else {
+				// Nothing changed this run — if the index already has content from a previous
+				// run, the vector column still needs registering on this fresh connection (see
+				// VectorIndex.initVectorColumn's own doc) before removeFile()'s bookkeeping below
+				// touches the same tables. Not required for a genuinely empty/new index — there's
+				// no dimension to know yet, and nothing to query either.
+				const existingDim = index.getMeta('dimension');
+				if (existingDim) index.initVectorColumn(Number(existingDim));
+			}
+
+			let filesRemoved = 0;
+			for (const indexedPath of index.listFiles()) {
+				if (!seenPaths.has(indexedPath)) {
+					index.removeFile(indexedPath);
+					filesRemoved++;
+				}
+			}
+
+			return { filesChanged: pending.length, filesSkipped, filesRemoved, chunksAdded };
+		} finally {
+			index.close();
+		}
+	}
+}
+
+/**
+ * Thrown when `index()` would add one model's vectors to an index built with another — two
+ * models' vectors aren't comparable (and usually aren't even the same length), so mixing them
+ * would quietly break every search. `rebuild` is the way through.
+ */
+export class ModelMismatchError extends Error {
+	constructor(dbPath, indexModel, providerModel) {
+		super(
+			`${dbPath} was built with ${indexModel}, not ${providerModel} — one index can't mix two models.`
+		);
+		this.name = 'ModelMismatchError';
+		this.indexModel = indexModel;
+		this.providerModel = providerModel;
+	}
+}
+
+function assertSameModel(meta, provider, dbPath) {
+	if (!meta?.model) return;
+	if (meta.model !== provider.modelId) throw new ModelMismatchError(dbPath, meta.model, provider.modelId);
+}

package/lib/search/Searcher.js

@@ -0,0 +1,68 @@
+import VectorIndex from './VectorIndex.js';
+import { LEGACY_DTYPE, EMBEDDER_TRANSFORMERS, embedderOfIndex } from './schema.js';
+
+/**
+ * Queries an already-built `VectorIndex`. Deliberately the only piece that needs an embedding
+ * model loaded on the *searcher's* machine — and only to embed the query string itself, never
+ * the corpus, which is the entire point of pushing the index alongside the content: whoever
+ * pulls it gets every embedding for free, already paid for by whoever ran `Indexer` first.
+ */
+export default class Searcher {
+	/**
+	 * @param {Object} params
+	 * @param {(opts: {model: string, embedder: string, dtype: ?string}) => Promise<any>} [params.createProvider] -
+	 *   builds the provider the index's own metadata asks for (see providers.js) — the common
+	 *   case, opening someone else's index.
+	 * @param {any} [params.embeddingProvider] - use this one instead, whatever the index recorded
+	 *   (tests; a custom provider). Its vectors must still match the index's dimension.
+	 */
+	constructor({ createProvider = null, embeddingProvider = null } = {}) {
+		if (!createProvider && !embeddingProvider) {
+			throw new Error('Searcher: pass createProvider or embeddingProvider');
+		}
+		this._createProvider = createProvider;
+		this._embeddingProvider = embeddingProvider;
+	}
+
+	/**
+	 * @param {string} dbPath
+	 * @param {string} query
+	 * @param {number} [k=5]
+	 * @returns {Promise<{path: string, chunkIndex: number, startOffset: number, endOffset: number, distance: number}[]>}
+	 */
+	async search(dbPath, query, k = 5) {
+		// Read-only: the index is a file that gets pushed, and searching it must not change it.
+		const index = new VectorIndex(dbPath, { readonly: true });
+		try {
+			const dim = Number(index.getMeta('dimension'));
+			if (!dim) {
+				throw new Error(`${dbPath}: no index metadata found — run \`mnemonad index\` first`);
+			}
+			index.initVectorColumn(dim);
+
+			const provider = this._embeddingProvider || await this._createProvider(describeIndexModel(index));
+			const [queryVector] = await provider.embed([query]);
+			if (queryVector.length !== dim) {
+				throw new Error(
+					`Query embedding is ${queryVector.length}-dimensional but this index is ${dim}-dimensional — ` +
+					`the embedding model must match the one used to build it (recorded model: ${index.getMeta('model')})`
+				);
+			}
+
+			return index.search(queryVector, k);
+		} finally {
+			index.close();
+		}
+	}
+}
+
+/** The model an index says it was built with, in the shape createProvider takes. */
+export function describeIndexModel(index) {
+	const meta = { model: index.getMeta('model'), embedder: index.getMeta('embedder') };
+	const embedder = embedderOfIndex(meta);
+	return {
+		model: meta.model,
+		embedder,
+		dtype: embedder === EMBEDDER_TRANSFORMERS ? (index.getMeta('dtype') || LEGACY_DTYPE) : null,
+	};
+}

package/lib/search/VectorIndex.js

@@ -0,0 +1,225 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import Database from 'better-sqlite3';
+import { VECTOR_INIT_SQL, SEARCH_SQL, vectorInitOptions, overfetchFor, mapSearchRow } from './schema.js';
+
+// @sqliteai/sqlite-vector's own ESM build (dist/index.mjs) cannot find its platform binary
+// package from a genuine ESM context — it tries a bare `require(packageName)` via a bundler-
+// injected shim that only works when a real CJS `require` is already in scope, which never
+// happens in native ESM (confirmed live: `import { getExtensionPath } from
+// '@sqliteai/sqlite-vector'` throws `ExtensionNotFoundError` even when the platform package
+// is correctly installed). `createRequire` is the standard Node workaround — it resolves the
+// package's CJS build instead, where a real `require` exists and the same lookup works.
+const require = createRequire(import.meta.url);
+const { getExtensionPath } = require('@sqliteai/sqlite-vector');
+
+/**
+ * A single, diff-friendly SQLite file holding embeddings for one synced folder — meant to be
+ * pushed alongside the folder's own content (a plain file, not dot-prefixed, so it rides
+ * through `push`/`pull`/`diff` unmodified) so a pull is immediately searchable with no
+ * re-embedding.
+ *
+ * The whole schema is designed around one constraint, verified empirically (not assumed):
+ * inserting rows into a plain table with a monotonic rowid touches only new/near-full pages,
+ * which content-defined chunking recognizes as mostly-unchanged on a re-push. A real
+ * measurement (200 existing rows, 5 new ones) showed ~2.9x overhead versus the new data's
+ * raw size — nowhere near a full-file rewrite, but *not* literally zero-touch either. What
+ * actually breaks this property: `VACUUM` (copies and rewrites every byte — never call it
+ * during routine reindexing) and `UPDATE`/`DELETE` on the (large, embedding-heavy)
+ * `search_index` table. `search_index_files` is deliberately the one place this class *does*
+ * mutate rows in place — it holds one row per file, so its churn is proportional to how many
+ * files actually changed, not to corpus size, and paying that small cost is what makes
+ * "which chunks are current" a correct query instead of a guess (see search_index_files' own
+ * doc below).
+ */
+export default class VectorIndex {
+	/**
+	 * @param {string} dbPath - path to the SQLite file. Created if it doesn't exist yet
+	 *   (unless `readonly`).
+	 * @param {Object} [options]
+	 * @param {boolean} [options.readonly=false] - open an existing index without writing
+	 *   anything to it — not even the schema check below. For inspecting an index that's about
+	 *   to be pushed (see Indexer.status()), where touching the file would change what's pushed.
+	 */
+	constructor(dbPath, { readonly = false } = {}) {
+		this.path = dbPath;
+		this._db = readonly
+			? new Database(dbPath, { readonly: true, fileMustExist: true })
+			: new Database(dbPath);
+		// Deliberately not enabling WAL mode: WAL leaves a separate `-wal`/`-shm` file holding
+		// uncommitted pages, which would need an explicit checkpoint before every push (a real
+		// operational footgun for anyone forgetting it). Left at SQLite's own default rollback
+		// journal instead — this class always closes the database (see close()) before anything
+		// downstream would push it, so there's never a mid-transaction state to leave behind.
+		this._db.loadExtension(getExtensionPath());
+		if (!readonly) this._ensureSchema();
+	}
+
+	_ensureSchema() {
+		this._db.exec(`
+			CREATE TABLE IF NOT EXISTS search_index (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				path TEXT NOT NULL,
+				chunk_index INTEGER NOT NULL,
+				content_hash TEXT NOT NULL,
+				start_offset INTEGER NOT NULL,
+				end_offset INTEGER NOT NULL,
+				embedding BLOB NOT NULL
+			)
+		`);
+		// One row per file, deliberately mutable (see class doc) — "content_hash" here is what
+		// decides which rows in the (append-only) search_index table above actually count as
+		// current: a chunk only counts if its own content_hash matches this table's row for the
+		// same path. That's what lets a stale reindex's chunks keep existing physically (pure
+		// insert, never deleted) while still being correctly excluded from search results —
+		// see search()'s own join.
+		this._db.exec(`
+			CREATE TABLE IF NOT EXISTS search_index_files (
+				path TEXT PRIMARY KEY,
+				content_hash TEXT NOT NULL,
+				chunk_count INTEGER NOT NULL
+			)
+		`);
+		this._db.exec(`
+			CREATE TABLE IF NOT EXISTS search_index_meta (
+				key TEXT PRIMARY KEY,
+				value TEXT NOT NULL
+			)
+		`);
+	}
+
+	/**
+	 * Registers `search_index`/`embedding` as a vector column with sqlite-vector — required on
+	 * every fresh connection before `vector_full_scan` etc. work (confirmed live: omitting this
+	 * fails with "vector_full_scan: unable to retrieve context", not a clearer error). Safe to
+	 * call more than once; last call wins.
+	 *
+	 * @param {number} dim
+	 * @param {'FLOAT32'|'INT8'} [type='FLOAT32']
+	 */
+	initVectorColumn(dim, type = 'FLOAT32') {
+		this._dim = dim;
+		this._vectorType = type;
+		this._db.prepare(VECTOR_INIT_SQL).run(vectorInitOptions(dim, type));
+	}
+
+	/** @returns {?string} the file's currently-indexed content hash, or null if never indexed. */
+	getFileHash(path) {
+		const row = this._db.prepare('SELECT content_hash FROM search_index_files WHERE path = ?').get(path);
+		return row?.content_hash ?? null;
+	}
+
+	/** @returns {string[]} every path currently recorded in the index (indexed, not necessarily still on disk). */
+	listFiles() {
+		return this._db.prepare('SELECT path FROM search_index_files').all().map((r) => r.path);
+	}
+
+	/**
+	 * Replaces one file's chunks. Never touches the file's *old* rows in `search_index` — it
+	 * only ever inserts new ones (see class doc for why) — and upserts the single
+	 * `search_index_files` row that makes the old ones stop counting as current.
+	 *
+	 * @param {string} path
+	 * @param {string} contentHash - the file's new content hash (same hashing this package's
+	 *   caller already uses to detect the file changed in the first place).
+	 * @param {{startOffset: number, endOffset: number, embedding: Float32Array}[]} chunks
+	 */
+	replaceFileChunks(path, contentHash, chunks) {
+		const insert = this._db.prepare(`
+			INSERT INTO search_index (path, chunk_index, content_hash, start_offset, end_offset, embedding)
+			VALUES (?, ?, ?, ?, ?, ?)
+		`);
+		const upsertFile = this._db.prepare(`
+			INSERT INTO search_index_files (path, content_hash, chunk_count) VALUES (?, ?, ?)
+			ON CONFLICT(path) DO UPDATE SET content_hash = excluded.content_hash, chunk_count = excluded.chunk_count
+		`);
+		const tx = this._db.transaction(() => {
+			chunks.forEach((chunk, index) => {
+				insert.run(path, index, contentHash, chunk.startOffset, chunk.endOffset, Buffer.from(chunk.embedding.buffer, chunk.embedding.byteOffset, chunk.embedding.byteLength));
+			});
+			upsertFile.run(path, contentHash, chunks.length);
+		});
+		tx();
+	}
+
+	/** A file no longer exists in the tree — stop counting its (still physically present) chunks as current. */
+	removeFile(path) {
+		this._db.prepare('DELETE FROM search_index_files WHERE path = ?').run(path);
+	}
+
+	setMeta(key, value) {
+		this._db.prepare(`
+			INSERT INTO search_index_meta (key, value) VALUES (?, ?)
+			ON CONFLICT(key) DO UPDATE SET value = excluded.value
+		`).run(key, String(value));
+	}
+
+	/**
+	 * An existing index's metadata, read without writing anything — or null when there's no
+	 * index at `dbPath` (or it has no metadata yet).
+	 * @returns {?Object<string, string>}
+	 */
+	static readMeta(dbPath) {
+		if (!existsSync(dbPath)) return null;
+		const index = new VectorIndex(dbPath, { readonly: true });
+		try {
+			const rows = index._db.prepare('SELECT key, value FROM search_index_meta').all();
+			return rows.length ? Object.fromEntries(rows.map((r) => [r.key, r.value])) : null;
+		} catch {
+			// No meta table: not an index this package built.
+			return null;
+		} finally {
+			index.close();
+		}
+	}
+
+	/** @returns {?string} */
+	getMeta(key) {
+		return this._db.prepare('SELECT value FROM search_index_meta WHERE key = ?').get(key)?.value ?? null;
+	}
+
+	/**
+	 * Nearest-neighbor search, current chunks only. Over-fetches from `vector_full_scan` (exact,
+	 * brute-force — appropriate for the corpus sizes a synced folder actually has; no ANN/
+	 * partitioning index, which would break the diffability this whole design depends on) since
+	 * some of its top candidates may turn out to be stale once joined against
+	 * `search_index_files`, and stops short of the caller's requested `k` otherwise.
+	 *
+	 * @param {Float32Array} queryEmbedding
+	 * @param {number} k
+	 * @returns {{path: string, chunkIndex: number, startOffset: number, endOffset: number, distance: number}[]}
+	 */
+	search(queryEmbedding, k) {
+		const queryBuf = Buffer.from(queryEmbedding.buffer, queryEmbedding.byteOffset, queryEmbedding.byteLength);
+		// BigInt, not a plain number: better-sqlite3 binds every JS `number` parameter as SQLite
+		// REAL (confirmed live — even a whole number like 64), but vector_full_scan's own count
+		// argument strictly requires INTEGER and rejects REAL outright rather than coercing it.
+		// (The WASM build binds whole numbers as INTEGER on its own — see WasmIndexReader.)
+		return this._db
+			.prepare(SEARCH_SQL)
+			.all(queryBuf, BigInt(overfetchFor(k)), BigInt(k))
+			.map(mapSearchRow);
+	}
+
+	/**
+	 * The deliberate, rare, full-rewrite operation — drops every chunk that isn't current
+	 * (superseded by a later reindex of the same file, or belonging to a file removed from the
+	 * index entirely) and reclaims the space. Costs a CDC-diff equivalent to a full snapshot —
+	 * same trade routine reindexing exists specifically to avoid — so this is opt-in, not run
+	 * automatically. Mirrors the CLI's own `compact` command for stream history.
+	 */
+	compact() {
+		this._db.exec(`
+			DELETE FROM search_index
+			WHERE NOT EXISTS (
+				SELECT 1 FROM search_index_files f
+				WHERE f.path = search_index.path AND f.content_hash = search_index.content_hash
+			)
+		`);
+		this._db.exec('VACUUM');
+	}
+
+	close() {
+		this._db.close();
+	}
+}

package/lib/search/browser/BrowserSearcher.js

@@ -0,0 +1,131 @@
+import WasmIndexReader from './WasmIndexReader.js';
+import { LEGACY_DTYPE, EMBEDDER_TRANSFORMERS, embedderOfIndex } from '../schema.js';
+
+/**
+ * The browser's `Searcher`: holds one open index (from bytes, not a path) and the embedding
+ * model that matches it, so repeated queries pay for neither again. `open()` again with new
+ * bytes when the index file changes; the model is only reloaded if the new index was built
+ * with a different one.
+ *
+ * Which provider to build for which index is the caller's job (`createProvider`), so this
+ * class — and the browser entry around it — never imports a model runtime itself: the
+ * explorer builds the static provider from its own files source, and loads transformers.js
+ * only for an index that needs it.
+ */
+export default class BrowserSearcher {
+	/**
+	 * @param {Object} params
+	 * @param {any} params.sqlite3 - an initialized `@sqliteai/sqlite-wasm` module.
+	 * @param {(opts: {model: string, embedder: string, dtype: ?string, onProgress: ?Function}) => (any|Promise<any>)} [params.createProvider] -
+	 *   builds the provider an index's metadata asks for.
+	 * @param {any} [params.embeddingProvider] - use this one for every index instead (tests).
+	 * @param {(event: Object) => void} [params.onModelProgress] - passed to createProvider.
+	 */
+	constructor({ sqlite3, createProvider = null, embeddingProvider = null, onModelProgress = null } = {}) {
+		if (!sqlite3) throw new Error('BrowserSearcher: sqlite3 module is required');
+		if (!createProvider && !embeddingProvider) {
+			throw new Error('BrowserSearcher: pass createProvider or embeddingProvider');
+		}
+		this._sqlite3 = sqlite3;
+		this._createProvider = createProvider;
+		this._onModelProgress = onModelProgress;
+		this._fixedProvider = embeddingProvider;
+		this._provider = embeddingProvider;
+		this._providerKey = null;
+		this._reader = null;
+	}
+
+	/** @param {Uint8Array} bytes - the whole search_index.db file. */
+	open(bytes) {
+		const reader = new WasmIndexReader(this._sqlite3, bytes);
+		const dim = Number(reader.getMeta('dimension'));
+		if (!dim) {
+			reader.close();
+			throw new Error('This search index has no metadata — it was never built, or is empty.');
+		}
+		reader.initVectorColumn(dim);
+		this.close();
+		this._reader = reader;
+		this._dim = dim;
+		this._model = reader.getMeta('model');
+		this._embedder = embedderOfIndex({ model: this._model, embedder: reader.getMeta('embedder') });
+		this._dtype = this._embedder === EMBEDDER_TRANSFORMERS ? (reader.getMeta('dtype') || LEGACY_DTYPE) : null;
+	}
+
+	get isOpen() {
+		return this._reader !== null;
+	}
+
+	/** @returns {{model: ?string, embedder: string, dtype: ?string, dimension: number}} */
+	get info() {
+		return { model: this._model, embedder: this._embedder, dtype: this._dtype, dimension: this._dim };
+	}
+
+	/** @returns {Map<string, string>} see WasmIndexReader.getFileHashes */
+	getFileHashes() {
+		this._requireOpen();
+		return this._reader.getFileHashes();
+	}
+
+	/** @returns {boolean} whether the model the open index needs is already loaded. */
+	get isModelLoaded() {
+		if (!this._reader) return false;
+		if (this._fixedProvider) return true;
+		return this._providerKey === this._key() && !!this._provider?.isLoaded;
+	}
+
+	/** Loads the embedding model now (the slow, one-time part — a download on first use) so a
+	 *  caller can show that as its own step instead of as a slow first query. */
+	async loadModel() {
+		this._requireOpen();
+		const provider = await this._providerForIndex();
+		if (typeof provider.load === 'function') await provider.load();
+	}
+
+	/**
+	 * @param {string} query
+	 * @param {number} [k=5]
+	 */
+	async search(query, k = 5) {
+		this._requireOpen();
+		const provider = await this._providerForIndex();
+		const [queryVector] = await provider.embed([query]);
+		if (queryVector.length !== this._dim) {
+			throw new Error(
+				`Query embedding is ${queryVector.length}-dimensional but this index is ${this._dim}-dimensional — ` +
+				`the embedding model must match the one used to build it (recorded model: ${this._model})`
+			);
+		}
+		return this._reader.search(queryVector, k);
+	}
+
+	close() {
+		if (this._reader) {
+			this._reader.close();
+			this._reader = null;
+		}
+	}
+
+	_key() {
+		return `${this._embedder}|${this._model}|${this._dtype}`;
+	}
+
+	async _providerForIndex() {
+		if (this._fixedProvider) return this._fixedProvider;
+		const key = this._key();
+		if (this._providerKey !== key) {
+			this._provider = await this._createProvider({
+				model: this._model,
+				embedder: this._embedder,
+				dtype: this._dtype,
+				onProgress: this._onModelProgress,
+			});
+			this._providerKey = key;
+		}
+		return this._provider;
+	}
+
+	_requireOpen() {
+		if (!this._reader) throw new Error('BrowserSearcher: call open(bytes) first');
+	}
+}