@camstack/system 1.2.53 → 1.2.54

package/dist/builtins/sqlite-storage/sqlite-settings.addon.mjs

@@ -1,4 +1,5 @@
-import { C as cosineSimilarity, Nt as parseJsonUnknown, St as asJsonObject, T as decodeVectorBase64, dt as errMsg, ft as BaseAddon, l as RUNTIME_DEFAULTS, lt as vectorDimFromBase64, ut as vectorStoreCapability, w as dataStoreProviderCapability } from "../../dist-f_YvZJaQ.mjs";
+import { C as dataStoreProviderCapability, Mt as parseJsonUnknown, ct as vectorDimFromBase64, dt as BaseAddon, l as RUNTIME_DEFAULTS, lt as vectorStoreCapability, ut as errMsg, w as decodeVectorBase64, xt as asJsonObject } from "../../dist-BOpRqInW.mjs";
+import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import Database from "better-sqlite3";
 //#region src/builtins/sqlite-storage/filter-compiler.ts
@@ -20,7 +21,7 @@ function fieldExprFor(field, shape) {
 	if (shape.kvBlobColumn !== null) return `json_extract("${shape.kvBlobColumn}", '$.${field}')`;
 	return null;
 }
-function compileFilter(filter, shape, mode, serialize) {
+function compileFilter$1(filter, shape, mode, serialize) {
 	const clauses = [];
 	const params = [];
 	const resolve = (field) => {
@@ -248,7 +249,7 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	async deleteWhere({ namespace, collection, filter }) {
 		const scoped = this.scopedName(namespace, collection);
 		const decl = this.requireDeclared(scoped);
-		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		const { whereSql, params } = compileFilter$1(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
 		return { deleted: this.getDb().prepare(`DELETE FROM "${scoped}"${whereSql}`).run(...params).changes };
 	}
 	/**
@@ -271,7 +272,7 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 			setValues.push(this.serializeColumnValue(value));
 		}
 		if (setClauses.length === 0) throw new UnsafeFilterError("updateWhere was given no fields to set");
-		const { whereSql, params } = compileFilter(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
+		const { whereSql, params } = compileFilter$1(filter, this.shapeOf(decl), "mutate", (v) => this.serializeColumnValue(v));
 		return { updated: this.getDb().prepare(`UPDATE "${scoped}" SET ${setClauses.join(", ")}${whereSql}`).run(...setValues, ...params).changes };
 	}
 	async count({ namespace, collection, filter }) {
@@ -304,7 +305,7 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		const shape = this.shapeOf(decl);
 		const col = fieldExprFor(field, shape);
 		if (col === null) return [];
-		const { whereSql: where, params } = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
+		const { whereSql: where, params } = compileFilter$1(filter, shape, "select", (v) => this.serializeColumnValue(v));
 		const sql = `SELECT ${`CAST((${col} - ?) / ? AS INTEGER)`} AS bucket, COUNT(*) AS count FROM "${scoped}"${where} GROUP BY bucket ORDER BY bucket`;
 		return this.getDb().prepare(sql).all(origin, bucketSize, ...params).map((r) => ({
 			bucket: r.bucket,
@@ -321,7 +322,7 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 		let sql = `SELECT ${[`"${decl.primaryKey}"`, ...[...decl.columns].map((c) => `"${c}"`)].join(", ")} FROM "${table}"`;
 		const params = [];
 		const shape = this.shapeOf(decl);
-		const compiled = compileFilter(filter, shape, "select", (v) => this.serializeColumnValue(v));
+		const compiled = compileFilter$1(filter, shape, "select", (v) => this.serializeColumnValue(v));
 		sql += compiled.whereSql;
 		params.push(...compiled.params);
 		if (filter?.orderBy) {
@@ -641,225 +642,119 @@ var SqliteSettingsBackend = class SqliteSettingsBackend {
 	}
 };
 //#endregion
-//#region src/builtins/sqlite-storage/vector-index.ts
-/**
-* SQLite-backed vector index — compact rows, exhaustive cosine ranking.
-*
-* Lives INSIDE the sqlite-settings builtin, against `SqliteSettingsBackend`
-* directly, and that placement is the point. It first shipped as its own addon
-* and that cost two round trips per write — caller → the `settings-store` door
-* → the engine ([D44](../../../../../docs/decisions/adr-0044.md)) — plus a
-* whole runner process, to reach the very database this addon already holds
-* open. Here an upsert is a function call.
-*
-* Replaceability is unaffected: it is the CAPABILITY that makes the backend
-* swappable, not the package. An ANN provider registers `vector-store` from
-* wherever it likes and `setActiveSingleton` picks it.
-*
-* This is the DEFAULT `vector-store` provider, not the final one. It exists to
-* make a row cheap; replacing exhaustive scan with a real ANN index is a
-* different provider registered against the same capability.
-*
-* What it changes versus the per-store JSON columns it replaces:
-*
-*  - the vector is a base64 Float32 TEXT column (~2.7 KB for 512 dims) instead
-*    of a JSON array of 512 numbers (~11.7 KB measured on the live hub), and
-*    decoding is a `readFloatLE` loop instead of `JSON.parse` of 512 tokens;
-*  - filterable metadata is promoted to real columns, so `deviceId` /
-*    `timestamp` / `className` prefilters are pushed into SQL and indexed
-*    rather than applied after loading everything;
-*  - a truncated scan is REPORTED (`truncated`), because a search that silently
-*    considered a subset reads as "nothing else matched".
-*
-* Metadata that is not one of the promoted columns rides in a JSON blob and is
-* returned verbatim; it cannot be filtered on. That is deliberate — a filter a
-* backend cannot push down is a filter that gets forgotten.
-*/
-/** Metadata keys promoted to real, indexable columns. */
+//#region src/builtins/sqlite-storage/vector-index-shared.ts
+/** Metadata keys promoted to real, indexable columns in every backend. */
 var PROMOTED_COLUMNS = [
 	"deviceId",
 	"timestamp",
 	"className",
 	"modelId"
 ];
-/** Ceiling on rows compared in one query, so a pathological index cannot wedge the runner. */
-var MAX_SCAN_ROWS = 2e5;
-var collectionFor = (index) => `vector-store:${index}`;
+//#endregion
+//#region src/builtins/sqlite-storage/vector-index-vec.ts
+var tableFor = (index) => `vec_${index.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+var registryTable = "vec_indexes";
+/** `vec0` speaks packed Float32; the capability speaks base64 of the same. */
+function toBlob(base64) {
+	return Buffer.from(base64, "base64");
+}
 /**
-* Where index declarations live.
+* `vec0` metadata columns are NOT NULLABLE.
 *
-* They MUST be durable. The rows survive a restart in SQLite but the `dim` and
-* `metric` that make them queryable were only ever in memory, so after a hub
-* restart `query` and `stats` both threw "index was never declared" until some
-* caller happened to write — which meant semantic search was dead from boot
-* until the next track closed. Callers declare lazily (the dimension comes from
-* the active encoder, unknown at construction), so nothing re-declared on boot.
+* Passing NULL fails the whole insert with "Expected text for TEXT metadata
+* column … received NULL", and our metadata is genuinely optional — a vector
+* may carry no className or modelId. So absence is encoded with a sentinel and
+* stripped again on read:
+*
+*  - text  → `''`. No real className or modelId is the empty string, so the
+*    round-trip is lossless.
+*  - integer → `MISSING_INT`. Chosen NEGATIVE because a device id and a
+*    millisecond timestamp are both non-negative in this system; 0 would be a
+*    plausible timestamp (1970) and could not be told from an absent one.
 */
-var INDEX_REGISTRY_COLLECTION = "vector-store:__indexes";
-var SqliteVectorIndex = class {
-	store;
+var MISSING_INT = -1;
+/**
+* Bind an integer metadata value as BigInt.
+*
+* Not defensive: `better-sqlite3` binds a plain JS number as FLOAT and `vec0`
+* refuses it outright for an INTEGER metadata column.
+*/
+function asInteger(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return BigInt(MISSING_INT);
+	return BigInt(Math.trunc(value));
+}
+function asText(value) {
+	return typeof value === "string" ? value : "";
+}
+/** The nullable read of a text column — `''` means the caller never set it. */
+function readText(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** The nullable read of an integer column — the sentinel means absent. */
+function readInt(value) {
+	const n = Number(value);
+	if (!Number.isFinite(n) || n === MISSING_INT) return null;
+	return n;
+}
+var SqliteVecVectorIndex = class {
+	db;
 	logger;
 	specs = /* @__PURE__ */ new Map();
 	constructor(deps) {
-		this.store = deps.store;
+		this.db = deps.db;
 		this.logger = deps.logger;
 	}
-	/**
-	* Load persisted index declarations. Call once at startup, BEFORE serving:
-	* without it every method on an existing index throws until a write
-	* re-declares it.
-	*/
+	/** Recover index declarations so an existing table is usable from boot. */
 	async loadIndexRegistry() {
 		try {
-			await this.store.declareCollection({
-				collection: INDEX_REGISTRY_COLLECTION,
-				columns: [
-					{
-						name: "id",
-						type: "TEXT",
-						primaryKey: true,
-						notNull: true
-					},
-					{
-						name: "dim",
-						type: "INTEGER",
-						notNull: true
-					},
-					{
-						name: "metric",
-						type: "TEXT",
-						notNull: true
-					}
-				]
-			});
-			const rows = await this.store.query({ collection: INDEX_REGISTRY_COLLECTION });
-			for (const row of rows) {
-				const dim = row.data["dim"];
-				const metric = row.data["metric"];
-				if (typeof dim !== "number") continue;
-				await this.declareIndex(row.id, dim, isMetric(metric) ? metric : "cosine");
+			this.db.exec(`CREATE TABLE IF NOT EXISTS ${registryTable} (id TEXT PRIMARY KEY, dim INTEGER NOT NULL, metric TEXT NOT NULL)`);
+			const rows = this.db.prepare(`SELECT id, dim, metric FROM ${registryTable}`).all();
+			for (const raw of rows) {
+				if (typeof raw !== "object" || raw === null) continue;
+				const row = raw;
+				const id = asText(row["id"]);
+				const dim = typeof row["dim"] === "number" ? row["dim"] : Number(row["dim"]);
+				if (id === null || !Number.isFinite(dim)) continue;
+				this.specs.set(id, {
+					dim,
+					metric: metricOf(row["metric"])
+				});
 			}
-			this.logger.info("vector-store index registry loaded", { meta: { indexes: this.specs.size } });
+			this.logger.info("sqlite-vec index registry loaded", { meta: { indexes: this.specs.size } });
 		} catch (err) {
-			this.logger.error("vector-store index registry failed to load", { meta: { error: String(err) } });
+			this.logger.error("sqlite-vec registry failed to load", { meta: { error: String(err) } });
 		}
 	}
-	/**
-	* Idempotent. Re-declaring an index with a DIFFERENT dim throws rather than
-	* wiping: silently dropping a populated index because a caller shipped a new
-	* model would destroy history that cannot be rebuilt.
-	*/
 	async declareIndex(index, dim, metric) {
 		const existing = this.specs.get(index);
 		if (existing !== void 0 && existing.dim !== dim) throw new Error(`vector-store: index "${index}" is declared with dim ${existing.dim}; refusing to redeclare as ${dim}`);
-		await this.store.declareCollection({
-			collection: collectionFor(index),
-			columns: [
-				{
-					name: "id",
-					type: "TEXT",
-					primaryKey: true,
-					notNull: true
-				},
-				{
-					name: "vector",
-					type: "TEXT",
-					notNull: true
-				},
-				{
-					name: "deviceId",
-					type: "INTEGER"
-				},
-				{
-					name: "timestamp",
-					type: "INTEGER"
-				},
-				{
-					name: "className",
-					type: "TEXT"
-				},
-				{
-					name: "modelId",
-					type: "TEXT"
-				},
-				{
-					name: "extra",
-					type: "JSON"
-				}
-			],
-			indexes: [
-				{
-					name: `idx_vec_${index}_dev_ts`,
-					columns: ["deviceId", "timestamp"]
-				},
-				{
-					name: `idx_vec_${index}_ts`,
-					columns: ["timestamp"]
-				},
-				{
-					name: `idx_vec_${index}_class`,
-					columns: ["className"]
-				}
-			]
-		});
+		this.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS ${tableFor(index)} USING vec0(
+         id TEXT PRIMARY KEY,
+         embedding float[${dim}] distance_metric=${metric === "euclidean" ? "L2" : "cosine"},
+         deviceId integer,
+         timestamp integer,
+         className text,
+         modelId text,
+         +extra text
+       )`);
+		this.db.exec(`CREATE TABLE IF NOT EXISTS ${registryTable} (id TEXT PRIMARY KEY, dim INTEGER NOT NULL, metric TEXT NOT NULL)`);
+		this.db.prepare(`INSERT OR REPLACE INTO ${registryTable}(id, dim, metric) VALUES (?, ?, ?)`).run(index, BigInt(dim), metric);
 		this.specs.set(index, {
 			dim,
 			metric
 		});
-		try {
-			await this.store.set({
-				collection: INDEX_REGISTRY_COLLECTION,
-				key: index,
-				value: {
-					dim,
-					metric
-				}
-			});
-		} catch (err) {
-			this.logger.warn("vector-store index declaration not persisted", { meta: {
-				index,
-				dim,
-				error: String(err)
-			} });
-		}
 	}
-	/**
-	* Resolve an index's spec, recovering it from stored rows when the registry
-	* has no entry.
-	*
-	* The recovery is not belt-and-braces, it is required: indexes created before
-	* the registry existed have rows and no declaration, and so would be
-	* permanently unqueryable — which is exactly how this was found, with 8,494
-	* live vectors that `stats` refused to look at. The dimension is derivable
-	* from any stored vector, so derive it and persist it rather than demanding
-	* the caller redeclare. The metric is NOT derivable and falls back to
-	* `cosine`, which is what every current caller declares.
-	*/
-	async resolveSpec(index) {
-		const known = this.specs.get(index);
-		if (known !== void 0) return known;
-		const sample = (await this.store.query({
-			collection: collectionFor(index),
-			filter: { limit: 1 }
-		}))[0];
-		const vector = sample === void 0 ? void 0 : readRow(sample.data)?.vector;
-		if (vector === void 0) throw new Error(`vector-store: index "${index}" was never declared`);
-		const dim = vectorDimFromBase64(vector);
-		this.logger.warn("vector-store recovered an undeclared index from its rows", { meta: {
-			index,
-			dim,
-			metric: "cosine"
-		} });
-		await this.declareIndex(index, dim, "cosine");
-		return {
-			dim,
-			metric: "cosine"
-		};
+	specOf(index) {
+		const spec = this.specs.get(index);
+		if (spec === void 0) throw new Error(`vector-store: index "${index}" was never declared`);
+		return spec;
 	}
-	/** Upsert items, refusing any whose vector length disagrees with the index. */
 	async upsert(index, items) {
-		const spec = await this.resolveSpec(index);
-		const collection = collectionFor(index);
+		const spec = this.specOf(index);
+		const del = this.db.prepare(`DELETE FROM ${tableFor(index)} WHERE id = ?`);
+		const stmt = this.db.prepare(`INSERT INTO ${tableFor(index)}
+       (id, embedding, deviceId, timestamp, className, modelId, extra)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
 		let upserted = 0;
 		let rejected = 0;
 		for (const item of items) {
@@ -867,34 +762,22 @@ var SqliteVectorIndex = class {
 				rejected += 1;
 				continue;
 			}
-			const { deviceId, timestamp, className, modelId, extra } = splitMetadata(item.metadata);
 			try {
-				await this.store.set({
-					collection,
-					key: item.id,
-					value: {
-						vector: item.vector,
-						deviceId,
-						timestamp,
-						className,
-						modelId,
-						extra
-					}
-				});
+				const extra = {};
+				for (const [k, v] of Object.entries(item.metadata)) if (!isPromoted(k)) extra[k] = v;
+				del.run(item.id);
+				stmt.run(item.id, toBlob(item.vector), asInteger(item.metadata["deviceId"]), asInteger(item.metadata["timestamp"]), asText(item.metadata["className"]), asText(item.metadata["modelId"]), JSON.stringify(extra));
 				upserted += 1;
 			} catch (err) {
 				rejected += 1;
-				this.logger.warn("vector-store upsert failed", {
-					...deviceId !== null ? { tags: { deviceId } } : {},
-					meta: {
-						index,
-						id: item.id,
-						error: String(err)
-					}
-				});
+				this.logger.warn("sqlite-vec upsert failed", { meta: {
+					index,
+					id: item.id,
+					error: String(err)
+				} });
 			}
 		}
-		if (rejected > 0) this.logger.warn("vector-store rejected items on upsert", { meta: {
+		if (rejected > 0) this.logger.warn("sqlite-vec rejected items on upsert", { meta: {
 			index,
 			rejected,
 			expectedDim: spec.dim
@@ -904,237 +787,168 @@ var SqliteVectorIndex = class {
 			rejected
 		};
 	}
-	/** Exhaustive ranked search over the rows a prefilter admits. */
 	async query(params) {
-		const spec = await this.resolveSpec(params.index);
-		const queryVec = decodeVectorBase64(params.vector);
-		if (queryVec.length !== spec.dim) throw new Error(`vector-store: query vector has ${queryVec.length} dims, index "${params.index}" has ${spec.dim}`);
-		const rows = await this.store.query({
-			collection: collectionFor(params.index),
-			filter: {
-				...buildSqlFilter(params.filter),
-				orderBy: {
-					field: "timestamp",
-					direction: "desc"
-				},
-				limit: MAX_SCAN_ROWS
-			}
-		});
+		const spec = this.specOf(params.index);
+		if (decodeVectorBase64(params.vector).length !== spec.dim) throw new Error(`vector-store: query vector has ${decodeVectorBase64(params.vector).length} dims, index "${params.index}" has ${spec.dim}`);
+		const { clauses, values, unpushable } = compileFilter(params.filter);
+		const where = clauses.length > 0 ? ` AND ${clauses.join(" AND ")}` : "";
+		const rows = this.db.prepare(`SELECT id, distance, deviceId, timestamp, className, modelId, extra
+         FROM ${tableFor(params.index)}
+         WHERE embedding MATCH ? AND k = ?${where}
+         ORDER BY distance`).all(toBlob(params.vector), BigInt(params.topK), ...values);
 		const minScore = params.minScore ?? Number.NEGATIVE_INFINITY;
-		const scored = [];
-		for (const row of rows) {
-			const stored = readRow(row.data);
-			if (stored === null) continue;
-			if (!passesUnpushedFilter(stored, params.filter)) continue;
-			const vec = decodeVectorBase64(stored.vector);
-			if (vec.length !== spec.dim) continue;
-			const score = scoreFor(spec.metric, queryVec, vec);
+		const matches = [];
+		for (const raw of rows) {
+			if (typeof raw !== "object" || raw === null) continue;
+			const row = raw;
+			const id = asText(row["id"]);
+			const distance = typeof row["distance"] === "number" ? row["distance"] : Number(row["distance"]);
+			if (id === null || !Number.isFinite(distance)) continue;
+			const metadata = rebuild(row);
+			if (!passesUnpushable(metadata, unpushable)) continue;
+			const score = spec.metric === "euclidean" ? -distance : 1 - distance;
 			if (score < minScore) continue;
-			scored.push({
-				id: row.id,
+			matches.push({
+				id,
 				score,
-				metadata: rebuildMetadata(stored)
+				metadata
 			});
 		}
-		scored.sort((a, b) => b.score - a.score);
 		return {
-			matches: scored.slice(0, params.topK),
+			matches,
 			scanned: rows.length,
-			truncated: rows.length >= MAX_SCAN_ROWS
+			truncated: false
 		};
 	}
-	/**
-	* Metadata for the given ids, WITHOUT decoding their vectors.
-	*
-	* The caller is a best-of gate comparing confidences, so the vector is dead
-	* weight on that path — reading it would reintroduce exactly the per-row cost
-	* this index exists to remove. Missing ids are absent from the result rather
-	* than present with an empty metadata object.
-	*/
 	async getByIds(index, ids) {
-		await this.resolveSpec(index);
+		this.specOf(index);
 		if (ids.length === 0) return [];
-		const rows = await this.store.query({
-			collection: collectionFor(index),
-			filter: { limit: MAX_SCAN_ROWS }
-		});
-		const wanted = new Set(ids);
+		const placeholders = ids.map(() => "?").join(",");
+		const rows = this.db.prepare(`SELECT id, deviceId, timestamp, className, modelId, extra
+         FROM ${tableFor(index)} WHERE id IN (${placeholders})`).all(...ids);
 		const out = [];
-		for (const row of rows) {
-			if (!wanted.has(row.id)) continue;
-			const stored = readRow(row.data);
-			if (stored === null) continue;
+		for (const raw of rows) {
+			if (typeof raw !== "object" || raw === null) continue;
+			const row = raw;
+			const id = asText(row["id"]);
+			if (id === null) continue;
 			out.push({
-				id: row.id,
-				metadata: rebuildMetadata(stored)
+				id,
+				metadata: rebuild(row)
 			});
 		}
 		return out;
 	}
 	async deleteByIds(index, ids) {
-		const collection = collectionFor(index);
-		let deleted = 0;
-		for (const id of ids) try {
-			await this.store.delete({
-				collection,
-				key: id
-			});
-			deleted += 1;
-		} catch (err) {
-			this.logger.warn("vector-store delete failed", { meta: {
-				index,
-				id,
-				error: String(err)
-			} });
-		}
-		return deleted;
+		this.specOf(index);
+		if (ids.length === 0) return 0;
+		const placeholders = ids.map(() => "?").join(",");
+		return this.db.prepare(`DELETE FROM ${tableFor(index)} WHERE id IN (${placeholders})`).run(...ids).changes;
 	}
-	/**
-	* Delete every row the filter admits.
-	*
-	* When every clause is pushable, this is ONE bulk statement. When the filter
-	* touches a non-promoted key it falls back to select-then-delete, because
-	* those clauses live in the JSON remainder and only JS can evaluate them —
-	* and an unapplied clause would delete rows the caller wanted kept, which is
-	* the one failure mode a delete must not have.
-	*/
 	async deleteByFilter(index, filter) {
-		await this.resolveSpec(index);
-		const sqlFilter = buildSqlFilter(filter);
-		if (isFullyPushable(filter)) return (await this.store.deleteWhere({
-			collection: collectionFor(index),
-			filter: sqlFilter
-		})).deleted;
-		const ids = (await this.store.query({
-			collection: collectionFor(index),
-			filter: {
-				...sqlFilter,
-				limit: MAX_SCAN_ROWS
-			}
-		})).filter((r) => {
-			const stored = readRow(r.data);
-			return stored !== null && passesUnpushedFilter(stored, filter);
-		}).map((r) => r.id);
-		return this.deleteByIds(index, ids);
+		this.specOf(index);
+		const { clauses, values, unpushable } = compileFilter(filter);
+		if (unpushable.length === 0) {
+			const where = clauses.length > 0 ? clauses.join(" AND ") : "1=1";
+			return this.db.prepare(`DELETE FROM ${tableFor(index)} WHERE ${where}`).run(...values).changes;
+		}
+		const rows = this.db.prepare(`SELECT id, deviceId, timestamp, className, modelId, extra FROM ${tableFor(index)}${clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : ""}`).all(...values);
+		const doomed = [];
+		for (const raw of rows) {
+			if (typeof raw !== "object" || raw === null) continue;
+			const row = raw;
+			const id = asText(row["id"]);
+			if (id !== null && passesUnpushable(rebuild(row), unpushable)) doomed.push(id);
+		}
+		return this.deleteByIds(index, doomed);
 	}
 	async stats(index) {
-		const spec = await this.resolveSpec(index);
+		const spec = this.specOf(index);
+		const row = this.db.prepare(`SELECT count(*) AS c FROM ${tableFor(index)}`).get();
+		const count = typeof row === "object" && row !== null ? Number(row["c"]) : 0;
 		return {
-			backend: "sqlite-bruteforce",
-			count: (await this.store.query({
-				collection: collectionFor(index),
-				filter: { limit: MAX_SCAN_ROWS }
-			})).length,
+			backend: "sqlite-vec",
+			count: Number.isFinite(count) ? count : 0,
 			dim: spec.dim,
 			metric: spec.metric,
 			exact: true
 		};
 	}
 };
-/** Split caller metadata into promoted columns plus a verbatim remainder. */
-function splitMetadata(metadata) {
-	const extra = {};
-	for (const [key, value] of Object.entries(metadata)) if (!isPromoted(key)) extra[key] = value;
-	return {
-		deviceId: numberOrNull(metadata["deviceId"]),
-		timestamp: numberOrNull(metadata["timestamp"]),
-		className: stringOrNull(metadata["className"]),
-		modelId: stringOrNull(metadata["modelId"]),
-		extra
-	};
-}
 function isPromoted(key) {
-	for (const promoted of PROMOTED_COLUMNS) if (promoted === key) return true;
+	for (const p of PROMOTED_COLUMNS) if (p === key) return true;
 	return false;
 }
-function numberOrNull(value) {
-	return typeof value === "number" ? value : null;
-}
-function stringOrNull(value) {
-	return typeof value === "string" ? value : null;
+function metricOf(value) {
+	return value === "euclidean" || value === "dot" ? value : "cosine";
 }
-/** Rebuild the caller's metadata from the promoted columns plus the remainder. */
-function rebuildMetadata(row) {
-	const out = { ...row.extra };
-	if (row.deviceId !== null) out["deviceId"] = row.deviceId;
-	if (row.timestamp !== null) out["timestamp"] = row.timestamp;
-	if (row.className !== null) out["className"] = row.className;
-	if (row.modelId !== null) out["modelId"] = row.modelId;
-	return out;
-}
-/** The part of a filter SQLite can apply: promoted columns only. */
-function buildSqlFilter(filter) {
-	if (filter === void 0) return {};
-	const where = {};
-	const whereBetween = {};
-	for (const [key, value] of Object.entries(filter.equals ?? {})) if (isPromoted(key)) where[key] = value;
-	for (const [key, range] of Object.entries(filter.between ?? {})) if (isPromoted(key)) whereBetween[key] = range;
-	return {
-		...Object.keys(where).length > 0 ? { where } : {},
-		...Object.keys(whereBetween).length > 0 ? { whereBetween } : {}
+/** Split a filter into SQL clauses and the remainder JS must apply. */
+function compileFilter(filter) {
+	const clauses = [];
+	const values = [];
+	const unpushable = [];
+	if (filter === void 0) return {
+		clauses,
+		values,
+		unpushable
 	};
-}
-/**
-* Apply the clauses SQL could not.
-*
-* A filter key that is not a promoted column lives inside the `extra` JSON
-* blob, so it is checked here in JS. It is applied rather than ignored — an
-* unapplied filter returns rows the caller will treat as matches.
-*/
-function passesUnpushedFilter(row, filter) {
-	if (filter === void 0) return true;
-	for (const [key, expected] of Object.entries(filter.equals ?? {})) {
-		if (isPromoted(key)) continue;
-		if (row.extra[key] !== expected) return false;
+	for (const [key, value] of Object.entries(filter.equals ?? {})) {
+		if (!isPromoted(key)) {
+			unpushable.push({
+				key,
+				equals: value
+			});
+			continue;
+		}
+		clauses.push(`${key} = ?`);
+		values.push(typeof value === "number" ? BigInt(Math.trunc(value)) : value);
 	}
 	for (const [key, [lo, hi]] of Object.entries(filter.between ?? {})) {
-		if (isPromoted(key)) continue;
-		const actual = row.extra[key];
-		if (typeof actual !== "number" || actual < lo || actual > hi) return false;
+		if (!isPromoted(key)) {
+			unpushable.push({
+				key,
+				between: [lo, hi]
+			});
+			continue;
+		}
+		clauses.push(`${key} BETWEEN ? AND ?`);
+		values.push(BigInt(Math.trunc(lo)), BigInt(Math.trunc(hi)));
 	}
-	return true;
-}
-function readRow(data) {
-	const vector = data["vector"];
-	if (typeof vector !== "string" || vector.length === 0) return null;
-	const extra = data["extra"];
 	return {
-		vector,
-		deviceId: numberOrNull(data["deviceId"]),
-		timestamp: numberOrNull(data["timestamp"]),
-		className: stringOrNull(data["className"]),
-		modelId: stringOrNull(data["modelId"]),
-		extra: isMetadata(extra) ? extra : {}
+		clauses,
+		values,
+		unpushable
 	};
 }
-function isMetadata(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** True when every clause of the filter maps to a promoted column. */
-function isFullyPushable(filter) {
-	for (const key of Object.keys(filter.equals ?? {})) if (!isPromoted(key)) return false;
-	for (const key of Object.keys(filter.between ?? {})) if (!isPromoted(key)) return false;
+function passesUnpushable(metadata, unpushable) {
+	for (const clause of unpushable) {
+		const actual = metadata[clause.key];
+		if (clause.equals !== void 0 && actual !== clause.equals) return false;
+		if (clause.between !== void 0) {
+			const [lo, hi] = clause.between;
+			if (typeof actual !== "number" || actual < lo || actual > hi) return false;
+		}
+	}
 	return true;
 }
-/** Narrow a stored metric string back to the enum. */
-function isMetric(value) {
-	return value === "cosine" || value === "dot" || value === "euclidean";
-}
-/** Score two vectors under the index's metric. Higher is nearer in every case. */
-function scoreFor(metric, a, b) {
-	if (metric === "cosine") return cosineSimilarity(a, b);
-	if (metric === "dot") {
-		let sum = 0;
-		for (let i = 0; i < a.length; i += 1) sum += (a[i] ?? 0) * (b[i] ?? 0);
-		return sum;
-	}
-	let sum = 0;
-	for (let i = 0; i < a.length; i += 1) {
-		const d = (a[i] ?? 0) - (b[i] ?? 0);
-		sum += d * d;
-	}
-	const distance = Math.sqrt(sum);
-	return distance === 0 ? 0 : -distance;
+/** Rebuild caller metadata from the promoted columns plus the JSON remainder. */
+function rebuild(row) {
+	let extra = {};
+	const rawExtra = row["extra"];
+	if (typeof rawExtra === "string" && rawExtra.length > 0) try {
+		const parsed = JSON.parse(rawExtra);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) extra = parsed;
+	} catch {}
+	const out = { ...extra };
+	const deviceId = readInt(row["deviceId"]);
+	const timestamp = readInt(row["timestamp"]);
+	const className = readText(row["className"]);
+	const modelId = readText(row["modelId"]);
+	if (deviceId !== null) out["deviceId"] = deviceId;
+	if (timestamp !== null) out["timestamp"] = timestamp;
+	if (className !== null) out["className"] = className;
+	if (modelId !== null) out["modelId"] = modelId;
+	return out;
 }
 //#endregion
 //#region src/builtins/sqlite-storage/sqlite-settings.addon.ts
@@ -1180,10 +994,7 @@ var SqliteSettingsAddon = class extends BaseAddon {
 		this.ctx.logger.info("DB file status", { meta: { dbExists } });
 		this.backend = new SqliteSettingsBackend(dbPath, { ...RUNTIME_DEFAULTS });
 		await this.backend.initialize();
-		const vectorIndex = new SqliteVectorIndex({
-			store: this.backend,
-			logger: this.ctx.logger.child("VectorIndex")
-		});
+		const vectorIndex = this.createVectorIndex(this.backend);
 		await vectorIndex.loadIndexRegistry();
 		this.vectorIndex = vectorIndex;
 		const vectorProvider = {
@@ -1218,6 +1029,32 @@ var SqliteSettingsAddon = class extends BaseAddon {
 	getBackend() {
 		return this.backend;
 	}
+	/**
+	* Build the vector index.
+	*
+	* ONE implementation, deliberately. A second backend behind a flag means two
+	* code paths that can disagree, two sets of gotchas, and a silent fallback
+	* that turns "the extension is missing" into "search is mysteriously slow" —
+	* the failure this codebase keeps paying for. The capability is the swap
+	* point: another provider replaces this one wholesale, it does not hide
+	* inside it.
+	*
+	* So a failed extension load THROWS. A node without the native binary must
+	* fail at boot with a message naming sqlite-vec, not serve degraded results
+	* nobody knows are degraded.
+	*/
+	createVectorIndex(backend) {
+		const logger = this.ctx.logger.child("VectorIndex");
+		const db = backend.getDatabase();
+		if (db === null) throw new Error("vector-store: the SQLite database is not open");
+		const sv = createRequire(import.meta.url)("sqlite-vec");
+		db.loadExtension(sv.getLoadablePath());
+		logger.info("sqlite-vec extension loaded");
+		return new SqliteVecVectorIndex({
+			db,
+			logger
+		});
+	}
 	/** Exposed for tests; null before `onInitialize`. */
 	getVectorIndex() {
 		return this.vectorIndex;