@atscript/db-sqlite 0.1.72 → 0.1.74

package/README.md

@@ -20,6 +20,9 @@ SQLite adapter for `@atscript/db` with a swappable driver architecture. Ships wi
 
 ```bash
 pnpm add @atscript/db-sqlite better-sqlite3
+
+# Optional — enables @db.search.vector via the sqlite-vec extension:
+pnpm add sqlite-vec
 ```
 
 ## Quick Start
@@ -37,10 +40,11 @@ await users.insertOne({ name: "John", email: "john@example.com" });
 ## Features
 
 - Swappable driver via `TSqliteDriver` interface (5 methods)
-- Built-in `BetterSqlite3Driver` for immediate use
+- Built-in `BetterSqlite3Driver` for immediate use (with optional `{ vector: true }` and `loadExtensions` hooks)
 - MongoDB-style filter translation to parameterized SQL (no injection risk)
 - Automatic schema management from `@db.*` annotations
 - FTS5 full-text search support
+- Vector similarity search via [`sqlite-vec`](https://github.com/asg017/sqlite-vec) — `vec0` shadow tables with AI/AU/AD sync triggers, KNN with partition push-down, threshold control
 - Embedded object flattening and `@db.json` storage
 - Schema sync via `@atscript/db/sync`
 

package/dist/index.cjs

@@ -18,6 +18,9 @@ let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
 * // File-based database
 * const driver = new BetterSqlite3Driver('./my-data.db')
 *
+* // With sqlite-vec extension loaded
+* const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+*
 * // Pre-created instance
 * import Database from 'better-sqlite3'
 * const db = new Database(':memory:', { verbose: console.log })
@@ -28,12 +31,27 @@ let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
 * ```bash
 * pnpm add better-sqlite3
 * ```
+*
+* Vector search support requires the optional `sqlite-vec` package:
+* ```bash
+* pnpm add sqlite-vec
+* ```
 */
 var BetterSqlite3Driver = class {
 	db;
+	hasVectorExt = false;
 	constructor(pathOrDb, options) {
-		if (typeof pathOrDb === "string") this.db = new ((0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("better-sqlite3"))(pathOrDb, options);
-		else this.db = pathOrDb;
+		const { vector, loadExtensions, ...nativeOptions } = options ?? {};
+		const req = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+		if (typeof pathOrDb === "string") {
+			const Database = req("better-sqlite3");
+			this.db = new Database(pathOrDb, nativeOptions);
+		} else this.db = pathOrDb;
+		for (const ext of loadExtensions ?? []) this.db.loadExtension(ext);
+		if (vector) {
+			req("sqlite-vec").load(this.db);
+			this.hasVectorExt = true;
+		}
 	}
 	run(sql, params) {
 		const stmt = this.db.prepare(sql);
@@ -216,6 +234,27 @@ function buildAggregateCount(table, where, controls) {
 	return (0, _atscript_db_sql_tools.buildAggregateCount)(sqliteDialect, table, where, controls);
 }
 /**
+* Converts an Atlas-style similarity score (1 = exact, 0 = orthogonal) to a
+* vec0 distance threshold.
+*
+* - cosine / dotProduct (mapped to cosine in DDL): vec0 distance = 1 - cos_sim,
+*   normalized score = (1 + cos_sim) / 2, so distance = 2 * (1 - score).
+* - euclidean (l2): vec0 distance is unbounded; the value is treated as a max
+*   distance directly (same convention as pgvector).
+*/
+function thresholdToVecDistance(threshold, similarity) {
+	if (similarity === "euclidean") return threshold;
+	return 2 * (1 - threshold);
+}
+/**
+* Maps an Atscript `@db.search.vector` similarity value to a sqlite-vec `vec0` metric.
+* `dotProduct` falls back to `cosine` because vec0 has no dedicated dot-product metric.
+*/
+function similarityToVecMetric(s) {
+	if (s === "euclidean") return "l2";
+	return "cosine";
+}
+/**
 * Maps Atscript design types to SQLite storage types.
 */
 function sqliteTypeFromDesignType(designType) {
@@ -232,12 +271,12 @@ function sqliteTypeFromDesignType(designType) {
 * Builds a CREATE TABLE IF NOT EXISTS statement from field descriptors.
 * Uses pre-computed {@link TDbFieldMeta} — no raw type introspection needed.
 */
-function buildCreateTable(table, fields, foreignKeys) {
+function buildCreateTable(table, fields, foreignKeys, options) {
 	const colDefs = [];
 	const primaryKeys = fields.filter((f) => f.isPrimaryKey);
 	for (const field of fields) {
 		if (field.ignored) continue;
-		const sqlType = field.isPrimaryKey && (field.designType === "number" || field.designType === "integer") ? "INTEGER" : sqliteTypeFromDesignType(field.designType);
+		const sqlType = options?.typeMapper?.(field) ?? (field.isPrimaryKey && (field.designType === "number" || field.designType === "integer") ? "INTEGER" : sqliteTypeFromDesignType(field.designType));
 		let def = `"${esc(field.physicalName)}" ${sqlType}`;
 		if (field.isPrimaryKey && primaryKeys.length === 1) {
 			def += " PRIMARY KEY";
@@ -302,15 +341,82 @@ function buildPrefixedWhere(alias, filter) {
 * const users = new AtscriptDbTable(UsersType, adapter)
 * ```
 */
-var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
+var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 	supportsNativeValueDefaults() {
 		return true;
 	}
+	/** Whether the SQLite connection has the sqlite-vec extension loaded. */
+	_supportsVector;
+	/** Vector fields: field path → { dimensions, similarity, indexName }. */
+	_vectorFields = /* @__PURE__ */ new Map();
+	/** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+	_vectorThresholds = /* @__PURE__ */ new Map();
+	/** Partition filter fields per vector index (from @db.search.filter). Field paths. */
+	_vectorPartitionFields = /* @__PURE__ */ new Map();
 	constructor(driver) {
 		super();
 		this.driver = driver;
 		this.driver.exec("PRAGMA foreign_keys = ON");
 	}
+	onFieldScanned(field, _type, metadata) {
+		const vectorMeta = metadata.get("db.search.vector");
+		if (vectorMeta) {
+			const indexName = vectorMeta.indexName || field;
+			this._vectorFields.set(field, {
+				dimensions: vectorMeta.dimensions,
+				similarity: vectorMeta.similarity || "cosine",
+				indexName
+			});
+			const threshold = metadata.get("db.search.vector.threshold");
+			if (threshold !== void 0) this._vectorThresholds.set(indexName, threshold);
+		}
+		for (const indexName of metadata.get("db.search.filter") || []) {
+			const list = this._vectorPartitionFields.get(indexName);
+			if (list) list.push(field);
+			else this._vectorPartitionFields.set(indexName, [field]);
+		}
+	}
+	formatValue(field) {
+		if (!this._vectorFields.has(field.path)) return;
+		if (this._detectVectorSupport()) return {
+			toStorage: (value) => Array.isArray(value) ? Buffer.from(new Float32Array(value).buffer) : value,
+			fromStorage: (value) => {
+				if (value instanceof Buffer || value instanceof Uint8Array) {
+					const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+					const arr = new Float32Array(buf.buffer, buf.byteOffset, Math.floor(buf.byteLength / 4));
+					return Array.from(arr);
+				}
+				return value;
+			}
+		};
+		return {
+			toStorage: (value) => Array.isArray(value) ? JSON.stringify(value) : value,
+			fromStorage: (value) => {
+				if (typeof value === "string") try {
+					return JSON.parse(value);
+				} catch {
+					return value;
+				}
+				return value;
+			}
+		};
+	}
+	isVectorSearchable() {
+		if (this._vectorFields.size === 0) return false;
+		return this._detectVectorSupport();
+	}
+	_detectVectorSupport() {
+		if (this._supportsVector !== void 0) return this._supportsVector;
+		if (this.driver.hasVectorExt !== void 0) this._supportsVector = this.driver.hasVectorExt;
+		else try {
+			this.driver.get("SELECT vec_version()");
+			this._supportsVector = true;
+		} catch {
+			this._supportsVector = false;
+		}
+		if (!this._supportsVector && this._vectorFields.size > 0) this._log("[atscript-db-sqlite] sqlite-vec extension not available — vector fields will be stored as JSON TEXT (no similarity search).");
+		return this._supportsVector;
+	}
 	async _beginTransaction() {
 		this._log("BEGIN");
 		this.driver.exec("BEGIN");
@@ -478,7 +584,7 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async ensureTable() {
 		if (this._table instanceof _atscript_db.AtscriptDbView) return this.ensureView();
-		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys);
+		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
 		this._log(sql);
 		this.driver.exec(sql);
 		this._seedIncrementStart();
@@ -539,10 +645,11 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 		const tableName = this.resolveTableName();
 		const tempName = `${tableName}__tmp_${Date.now()}`;
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		this.driver.exec("PRAGMA foreign_keys = OFF");
 		this.driver.exec("PRAGMA legacy_alter_table = ON");
 		try {
-			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys);
+			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
 			this._log(createSql);
 			this.driver.exec(createSql);
 			const oldCols = (await this.getExistingColumns()).map((c) => c.name);
@@ -576,6 +683,7 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 	async dropTable() {
 		const tableName = this.resolveTableName();
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
 		this._log(ddl);
 		this.driver.exec(ddl);
@@ -592,6 +700,7 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 	}
 	async dropTableByName(tableName) {
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
 		this._log(ddl);
 		this.driver.exec(ddl);
@@ -608,6 +717,7 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 		this.driver.exec(ddl);
 	}
 	typeMapper(field) {
+		if (this._vectorFields.has(field.path)) return this._detectVectorSupport() ? "BLOB" : "TEXT";
 		if (field.isPrimaryKey && (field.designType === "number" || field.designType === "integer")) return "INTEGER";
 		return sqliteTypeFromDesignType(field.designType);
 	}
@@ -639,13 +749,21 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 			shouldSkipType: (type) => type === "fulltext"
 		});
 		this._syncFtsIndexes(tableName);
+		this._syncVecIndexes(tableName);
 	}
 	getSearchIndexes() {
-		return this._getFulltextIndexes().map((idx) => ({
+		const indexes = [];
+		for (const idx of this._getFulltextIndexes()) indexes.push({
 			name: idx.name,
 			description: `FTS5 index (${idx.fields.map((f) => f.name).join(", ")})`,
 			type: "text"
-		}));
+		});
+		for (const [field, vec] of this._vectorFields) indexes.push({
+			name: vec.indexName,
+			description: `vec0 index on ${field} (${vec.dimensions}, ${vec.similarity})`,
+			type: "vector"
+		});
+		return indexes;
 	}
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
@@ -781,6 +899,225 @@ var SqliteAdapter = class extends _atscript_db.BaseDbAdapter {
 		const ftsTables = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__fts__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE"));
 		for (const { name } of ftsTables) this._dropFtsTable(name);
 	}
+	static _RESIDUAL_OVERFETCH = 4;
+	async vectorSearch(vector, query, indexName) {
+		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
+		const base = this._buildVectorSearchBase(vector, query, indexName);
+		return this._runVectorSearch(base);
+	}
+	async vectorSearchWithCount(vector, query, indexName) {
+		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
+		const base = this._buildVectorSearchBase(vector, query, indexName);
+		const data = this._runVectorSearch(base);
+		const countSql = `SELECT COUNT(*) AS cnt ${base.fromWhere}`;
+		this._log(countSql, base.params);
+		return {
+			data,
+			count: this.driver.get(countSql, base.params)?.cnt ?? 0
+		};
+	}
+	_runVectorSearch(base) {
+		let sql = `SELECT * ${base.fromWhere} ORDER BY _distance ASC LIMIT ?`;
+		const params = [...base.params, base.limit];
+		if (base.skip > 0) {
+			sql += ` OFFSET ?`;
+			params.push(base.skip);
+		}
+		this._log(sql, params);
+		return this.driver.all(sql, params);
+	}
+	/** Resolves a vector index (by name or first available) and its partition fields. */
+	_resolveVectorIndex(indexName) {
+		let entry;
+		if (indexName) {
+			for (const [f, v] of this._vectorFields) if (v.indexName === indexName) {
+				entry = [f, v];
+				break;
+			}
+			if (!entry) throw new Error(`Vector index "${indexName}" not found`);
+		} else {
+			const first = this._vectorFields.entries().next();
+			if (first.done) throw new Error("No vector fields defined");
+			entry = first.value;
+		}
+		const [field, vec] = entry;
+		const partitionPhysicalNames = /* @__PURE__ */ new Set();
+		for (const logicalPath of this._vectorPartitionFields.get(vec.indexName) ?? []) {
+			const descriptor = this._table.fieldDescriptors.find((f) => f.path === logicalPath);
+			partitionPhysicalNames.add(descriptor?.physicalName ?? logicalPath);
+		}
+		return {
+			field,
+			vec,
+			partitionPhysicalNames
+		};
+	}
+	/** Query-time `$threshold` overrides the schema-level threshold (mirrors postgres precedence). */
+	_resolveVectorThreshold(controls, indexName) {
+		const queryThreshold = controls.$threshold;
+		if (queryThreshold !== void 0) return queryThreshold;
+		return this._vectorThresholds.get(indexName);
+	}
+	/**
+	* Splits the (already physical-name) filter into partition equality push-down
+	* vs. residual filter. Only top-level primitive equality is pushed down.
+	*/
+	_splitVectorFilter(filter, partitionPhysicalNames) {
+		const partition = [];
+		const residual = {};
+		if (!filter || typeof filter !== "object") return {
+			partition,
+			residual: filter
+		};
+		for (const [key, value] of Object.entries(filter)) if (partitionPhysicalNames.has(key) && value !== null && (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")) partition.push({
+			name: key,
+			value
+		});
+		else residual[key] = value;
+		return {
+			partition,
+			residual
+		};
+	}
+	/**
+	* Builds the shared FROM+WHERE fragment for vec0 KNN queries (without ORDER/LIMIT).
+	* Both `vectorSearch` and `vectorSearchWithCount` reuse this — the former appends
+	* ORDER BY + LIMIT/OFFSET, the latter wraps it in a COUNT(*).
+	*/
+	_buildVectorSearchBase(vector, query, indexName) {
+		const { vec, partitionPhysicalNames } = this._resolveVectorIndex(indexName);
+		if (vector.length !== vec.dimensions) throw new Error(`Vector dimension mismatch: index "${vec.indexName}" expects ${vec.dimensions}, got ${vector.length}`);
+		const vecBuf = Buffer.from(new Float32Array(vector).buffer);
+		const controls = query.controls || {};
+		const limit = controls.$limit ?? 20;
+		const skip = controls.$skip ?? 0;
+		const threshold = this._resolveVectorThreshold(controls, vec.indexName);
+		const { partition, residual } = this._splitVectorFilter(query.filter, partitionPhysicalNames);
+		const residualWhere = buildPrefixedWhere("_vs", residual);
+		const hasResidual = residualWhere.sql !== "1=1";
+		const hasThreshold = threshold !== void 0;
+		const k = (limit + skip) * (hasResidual || hasThreshold ? SqliteAdapter._RESIDUAL_OVERFETCH : 1);
+		const tableName = this.resolveTableName();
+		const vecTable = this._vecTableName(vec.indexName);
+		const innerWhereParts = ["v.embedding MATCH ?", "v.k = ?"];
+		const params = [vecBuf, k];
+		for (const p of partition) {
+			innerWhereParts.push(`v."${esc(p.name)}" = ?`);
+			params.push(p.value);
+		}
+		let fromWhere = `FROM (${`SELECT t.*, v.distance AS _distance FROM "${esc(vecTable)}" v JOIN "${esc(tableName)}" t ON t.rowid = v.rowid WHERE ${innerWhereParts.join(" AND ")}`}) _vs`;
+		const outerWhereParts = [];
+		if (hasThreshold) {
+			outerWhereParts.push(`_distance <= ?`);
+			params.push(thresholdToVecDistance(threshold, vec.similarity));
+		}
+		if (hasResidual) {
+			outerWhereParts.push(`(${residualWhere.sql})`);
+			params.push(...residualWhere.params);
+		}
+		if (outerWhereParts.length > 0) fromWhere += ` WHERE ${outerWhereParts.join(" AND ")}`;
+		return {
+			fromWhere,
+			params,
+			limit,
+			skip
+		};
+	}
+	/** Builds vec0 shadow table name from index name: `<table>__vec__<indexName>`. */
+	_vecTableName(indexName) {
+		return `${this.resolveTableName()}__vec__${indexName}`;
+	}
+	/**
+	* Creates/drops vec0 virtual shadow tables and sync triggers to match desired vector fields.
+	*/
+	_syncVecIndexes(tableName) {
+		if (this._vectorFields.size === 0) return;
+		if (!this._detectVectorSupport()) {
+			this._log("[atscript-db-sqlite] sqlite-vec not available, skipping vec0 shadow table sync (vector fields stored as JSON)");
+			return;
+		}
+		const desiredVecTables = /* @__PURE__ */ new Map();
+		for (const [fieldPath, meta] of this._vectorFields.entries()) desiredVecTables.set(this._vecTableName(meta.indexName), {
+			field: fieldPath,
+			meta
+		});
+		const existingVec = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__vec__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE")).map((r) => r.name);
+		for (const name of existingVec) if (!desiredVecTables.has(name)) this._dropVecTable(name);
+		const existingSet = new Set(existingVec);
+		for (const [vecTable, { field, meta }] of desiredVecTables.entries()) if (!existingSet.has(vecTable)) this._createVecTable(tableName, vecTable, field, meta);
+	}
+	/** Creates a vec0 virtual shadow table with sync triggers and seeds it from existing rows. */
+	_createVecTable(tableName, vecTable, field, vec) {
+		const metric = similarityToVecMetric(vec.similarity);
+		const embeddingCol = this._table.fieldDescriptors.find((f) => f.path === field)?.physicalName ?? field;
+		const partitionFieldPaths = this._vectorPartitionFields.get(vec.indexName) ?? [];
+		const partitionCols = [];
+		for (const logicalPath of partitionFieldPaths) {
+			const descriptor = this._table.fieldDescriptors.find((f) => f.path === logicalPath);
+			if (!descriptor) {
+				this._log(`[atscript-db-sqlite] vec0 partition field "${logicalPath}" not found for index "${vec.indexName}", defaulting to TEXT`);
+				partitionCols.push({
+					physicalName: logicalPath,
+					sqlType: "TEXT"
+				});
+			} else partitionCols.push({
+				physicalName: descriptor.physicalName,
+				sqlType: this.typeMapper(descriptor)
+			});
+		}
+		for (const c of partitionCols) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(c.physicalName)) throw new Error(`vec0 partition column name "${c.physicalName}" is not a safe identifier (only [A-Za-z_][A-Za-z0-9_]* is allowed for @db.search.filter fields on SQLite).`);
+		const ddlCols = [partitionCols.map((c) => `${c.physicalName} ${c.sqlType} partition key`).join(", "), `embedding float[${vec.dimensions}] distance_metric=${metric}`].filter(Boolean).join(", ");
+		const createSql = `CREATE VIRTUAL TABLE IF NOT EXISTS "${esc(vecTable)}" USING vec0(${ddlCols})`;
+		this._log(createSql);
+		this.driver.exec(createSql);
+		const partCols = partitionCols.map((c) => `"${esc(c.physicalName)}"`);
+		const embCol = `"${esc(embeddingCol)}"`;
+		const insertCols = [
+			"rowid",
+			...partCols,
+			"embedding"
+		].join(", ");
+		const insertNewVals = [
+			"new.rowid",
+			...partitionCols.map((c) => `new."${esc(c.physicalName)}"`),
+			`new.${embCol}`
+		].join(", ");
+		const seedColList = [
+			"rowid",
+			...partCols,
+			embCol
+		].join(", ");
+		const ev = esc(vecTable);
+		const et = esc(tableName);
+		const aiSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__ai")}" AFTER INSERT ON "${et}" WHEN new.${embCol} IS NOT NULL BEGIN INSERT INTO "${ev}"(${insertCols}) VALUES(${insertNewVals}); END`;
+		this._log(aiSql);
+		this.driver.exec(aiSql);
+		const adSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__ad")}" AFTER DELETE ON "${et}" BEGIN DELETE FROM "${ev}" WHERE rowid = old.rowid; END`;
+		this._log(adSql);
+		this.driver.exec(adSql);
+		const auSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__au")}" AFTER UPDATE ON "${et}" BEGIN DELETE FROM "${ev}" WHERE rowid = old.rowid; INSERT INTO "${ev}"(${insertCols}) SELECT ${insertNewVals} WHERE new.${embCol} IS NOT NULL; END`;
+		this._log(auSql);
+		this.driver.exec(auSql);
+		const seedSql = `INSERT INTO "${ev}"(${insertCols}) SELECT ${seedColList} FROM "${et}" WHERE ${embCol} IS NOT NULL`;
+		this._log(seedSql);
+		this.driver.exec(seedSql);
+	}
+	/** Drops a vec0 virtual table and its sync triggers. */
+	_dropVecTable(vecTable) {
+		for (const suffix of [
+			"__ai",
+			"__ad",
+			"__au"
+		]) this.driver.exec(`DROP TRIGGER IF EXISTS "${esc(vecTable + suffix)}"`);
+		const sql = `DROP TABLE IF EXISTS "${esc(vecTable)}"`;
+		this._log(sql);
+		this.driver.exec(sql);
+	}
+	/** Drops all vec0 virtual shadow tables and triggers for a content table. */
+	_dropAllVecTables(tableName) {
+		const vecTables = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__vec__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE"));
+		for (const { name } of vecTables) this._dropVecTable(name);
+	}
 };
 /** Normalizes SQLite PRAGMA dflt_value to match serialized format.
 *  PRAGMA returns `'active'` (SQL-quoted), we store `active` (raw). */

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult } from "@atscript/db";
-import * as better_sqlite30 from "better-sqlite3";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { TMetadataMap } from "@atscript/typescript/utils";
+import * as _$better_sqlite30 from "better-sqlite3";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
 
@@ -47,6 +48,11 @@ interface TSqliteDriver {
    * Close the database connection.
    */
   close(): void;
+  /**
+   * Whether a vector search extension (e.g., `sqlite-vec`) is loaded.
+   * Consumers gate vec0 virtual tables and KNN queries on this flag.
+   */
+  readonly hasVectorExt?: boolean;
 }
 //#endregion
 //#region src/sqlite-adapter.d.ts
@@ -68,7 +74,19 @@ interface TSqliteDriver {
 declare class SqliteAdapter extends BaseDbAdapter {
   protected readonly driver: TSqliteDriver;
   supportsNativeValueDefaults(): boolean;
+  /** Whether the SQLite connection has the sqlite-vec extension loaded. */
+  private _supportsVector;
+  /** Vector fields: field path → { dimensions, similarity, indexName }. */
+  private _vectorFields;
+  /** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+  private _vectorThresholds;
+  /** Partition filter fields per vector index (from @db.search.filter). Field paths. */
+  private _vectorPartitionFields;
   constructor(driver: TSqliteDriver);
+  onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
+  formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;
+  isVectorSearchable(): boolean;
+  private _detectVectorSupport;
   protected _beginTransaction(): Promise<unknown>;
   protected _commitTransaction(): Promise<void>;
   protected _rollbackTransaction(): Promise<void>;
@@ -110,10 +128,7 @@ declare class SqliteAdapter extends BaseDbAdapter {
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
-  typeMapper(field: {
-    designType: string;
-    isPrimaryKey: boolean;
-  }): string;
+  typeMapper(field: TDbFieldMeta): string;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
   syncIndexes(): Promise<void>;
   getSearchIndexes(): TSearchIndexInfo[];
@@ -143,9 +158,49 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _dropFtsTable;
   /** Drops all FTS virtual tables and triggers for a content table. */
   private _dropAllFtsTables;
+  private static readonly _RESIDUAL_OVERFETCH;
+  vectorSearch(vector: number[], query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
+  vectorSearchWithCount(vector: number[], query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  private _runVectorSearch;
+  /** Resolves a vector index (by name or first available) and its partition fields. */
+  private _resolveVectorIndex;
+  /** Query-time `$threshold` overrides the schema-level threshold (mirrors postgres precedence). */
+  private _resolveVectorThreshold;
+  /**
+   * Splits the (already physical-name) filter into partition equality push-down
+   * vs. residual filter. Only top-level primitive equality is pushed down.
+   */
+  private _splitVectorFilter;
+  /**
+   * Builds the shared FROM+WHERE fragment for vec0 KNN queries (without ORDER/LIMIT).
+   * Both `vectorSearch` and `vectorSearchWithCount` reuse this — the former appends
+   * ORDER BY + LIMIT/OFFSET, the latter wraps it in a COUNT(*).
+   */
+  private _buildVectorSearchBase;
+  /** Builds vec0 shadow table name from index name: `<table>__vec__<indexName>`. */
+  private _vecTableName;
+  /**
+   * Creates/drops vec0 virtual shadow tables and sync triggers to match desired vector fields.
+   */
+  private _syncVecIndexes;
+  /** Creates a vec0 virtual shadow table with sync triggers and seeds it from existing rows. */
+  private _createVecTable;
+  /** Drops a vec0 virtual table and its sync triggers. */
+  private _dropVecTable;
+  /** Drops all vec0 virtual shadow tables and triggers for a content table. */
+  private _dropAllVecTables;
 }
 //#endregion
 //#region src/better-sqlite3-driver.d.ts
+interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
+  /** Load the optional `sqlite-vec` extension. */
+  vector?: boolean;
+  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
+  loadExtensions?: string[];
+}
 /**
  * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
  *
@@ -161,6 +216,9 @@ declare class SqliteAdapter extends BaseDbAdapter {
  * // File-based database
  * const driver = new BetterSqlite3Driver('./my-data.db')
  *
+ * // With sqlite-vec extension loaded
+ * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+ *
  * // Pre-created instance
  * import Database from 'better-sqlite3'
  * const db = new Database(':memory:', { verbose: console.log })
@@ -171,10 +229,16 @@ declare class SqliteAdapter extends BaseDbAdapter {
  * ```bash
  * pnpm add better-sqlite3
  * ```
+ *
+ * Vector search support requires the optional `sqlite-vec` package:
+ * ```bash
+ * pnpm add sqlite-vec
+ * ```
  */
 declare class BetterSqlite3Driver implements TSqliteDriver {
   private db;
-  constructor(pathOrDb: string | better_sqlite30.Database, options?: Record<string, unknown>);
+  readonly hasVectorExt: boolean;
+  constructor(pathOrDb: string | _$better_sqlite30.Database, options?: TBetterSqlite3DriverOptions);
   run(sql: string, params?: unknown[]): TSqliteRunResult;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult } from "@atscript/db";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
-import * as better_sqlite30 from "better-sqlite3";
+import { TMetadataMap } from "@atscript/typescript/utils";
+import * as _$better_sqlite30 from "better-sqlite3";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 
 //#region src/types.d.ts
@@ -47,6 +48,11 @@ interface TSqliteDriver {
    * Close the database connection.
    */
   close(): void;
+  /**
+   * Whether a vector search extension (e.g., `sqlite-vec`) is loaded.
+   * Consumers gate vec0 virtual tables and KNN queries on this flag.
+   */
+  readonly hasVectorExt?: boolean;
 }
 //#endregion
 //#region src/sqlite-adapter.d.ts
@@ -68,7 +74,19 @@ interface TSqliteDriver {
 declare class SqliteAdapter extends BaseDbAdapter {
   protected readonly driver: TSqliteDriver;
   supportsNativeValueDefaults(): boolean;
+  /** Whether the SQLite connection has the sqlite-vec extension loaded. */
+  private _supportsVector;
+  /** Vector fields: field path → { dimensions, similarity, indexName }. */
+  private _vectorFields;
+  /** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+  private _vectorThresholds;
+  /** Partition filter fields per vector index (from @db.search.filter). Field paths. */
+  private _vectorPartitionFields;
   constructor(driver: TSqliteDriver);
+  onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
+  formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;
+  isVectorSearchable(): boolean;
+  private _detectVectorSupport;
   protected _beginTransaction(): Promise<unknown>;
   protected _commitTransaction(): Promise<void>;
   protected _rollbackTransaction(): Promise<void>;
@@ -110,10 +128,7 @@ declare class SqliteAdapter extends BaseDbAdapter {
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
-  typeMapper(field: {
-    designType: string;
-    isPrimaryKey: boolean;
-  }): string;
+  typeMapper(field: TDbFieldMeta): string;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
   syncIndexes(): Promise<void>;
   getSearchIndexes(): TSearchIndexInfo[];
@@ -143,9 +158,49 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _dropFtsTable;
   /** Drops all FTS virtual tables and triggers for a content table. */
   private _dropAllFtsTables;
+  private static readonly _RESIDUAL_OVERFETCH;
+  vectorSearch(vector: number[], query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
+  vectorSearchWithCount(vector: number[], query: DbQuery, indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  private _runVectorSearch;
+  /** Resolves a vector index (by name or first available) and its partition fields. */
+  private _resolveVectorIndex;
+  /** Query-time `$threshold` overrides the schema-level threshold (mirrors postgres precedence). */
+  private _resolveVectorThreshold;
+  /**
+   * Splits the (already physical-name) filter into partition equality push-down
+   * vs. residual filter. Only top-level primitive equality is pushed down.
+   */
+  private _splitVectorFilter;
+  /**
+   * Builds the shared FROM+WHERE fragment for vec0 KNN queries (without ORDER/LIMIT).
+   * Both `vectorSearch` and `vectorSearchWithCount` reuse this — the former appends
+   * ORDER BY + LIMIT/OFFSET, the latter wraps it in a COUNT(*).
+   */
+  private _buildVectorSearchBase;
+  /** Builds vec0 shadow table name from index name: `<table>__vec__<indexName>`. */
+  private _vecTableName;
+  /**
+   * Creates/drops vec0 virtual shadow tables and sync triggers to match desired vector fields.
+   */
+  private _syncVecIndexes;
+  /** Creates a vec0 virtual shadow table with sync triggers and seeds it from existing rows. */
+  private _createVecTable;
+  /** Drops a vec0 virtual table and its sync triggers. */
+  private _dropVecTable;
+  /** Drops all vec0 virtual shadow tables and triggers for a content table. */
+  private _dropAllVecTables;
 }
 //#endregion
 //#region src/better-sqlite3-driver.d.ts
+interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
+  /** Load the optional `sqlite-vec` extension. */
+  vector?: boolean;
+  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
+  loadExtensions?: string[];
+}
 /**
  * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
  *
@@ -161,6 +216,9 @@ declare class SqliteAdapter extends BaseDbAdapter {
  * // File-based database
  * const driver = new BetterSqlite3Driver('./my-data.db')
  *
+ * // With sqlite-vec extension loaded
+ * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+ *
  * // Pre-created instance
  * import Database from 'better-sqlite3'
  * const db = new Database(':memory:', { verbose: console.log })
@@ -171,10 +229,16 @@ declare class SqliteAdapter extends BaseDbAdapter {
  * ```bash
  * pnpm add better-sqlite3
  * ```
+ *
+ * Vector search support requires the optional `sqlite-vec` package:
+ * ```bash
+ * pnpm add sqlite-vec
+ * ```
  */
 declare class BetterSqlite3Driver implements TSqliteDriver {
   private db;
-  constructor(pathOrDb: string | better_sqlite30.Database, options?: Record<string, unknown>);
+  readonly hasVectorExt: boolean;
+  constructor(pathOrDb: string | _$better_sqlite30.Database, options?: TBetterSqlite3DriverOptions);
   run(sql: string, params?: unknown[]): TSqliteRunResult;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;

package/dist/index.mjs

@@ -17,6 +17,9 @@ import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete
 * // File-based database
 * const driver = new BetterSqlite3Driver('./my-data.db')
 *
+* // With sqlite-vec extension loaded
+* const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+*
 * // Pre-created instance
 * import Database from 'better-sqlite3'
 * const db = new Database(':memory:', { verbose: console.log })
@@ -27,12 +30,27 @@ import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete
 * ```bash
 * pnpm add better-sqlite3
 * ```
+*
+* Vector search support requires the optional `sqlite-vec` package:
+* ```bash
+* pnpm add sqlite-vec
+* ```
 */
 var BetterSqlite3Driver = class {
 	db;
+	hasVectorExt = false;
 	constructor(pathOrDb, options) {
-		if (typeof pathOrDb === "string") this.db = new (createRequire(import.meta.url)("better-sqlite3"))(pathOrDb, options);
-		else this.db = pathOrDb;
+		const { vector, loadExtensions, ...nativeOptions } = options ?? {};
+		const req = createRequire(import.meta.url);
+		if (typeof pathOrDb === "string") {
+			const Database = req("better-sqlite3");
+			this.db = new Database(pathOrDb, nativeOptions);
+		} else this.db = pathOrDb;
+		for (const ext of loadExtensions ?? []) this.db.loadExtension(ext);
+		if (vector) {
+			req("sqlite-vec").load(this.db);
+			this.hasVectorExt = true;
+		}
 	}
 	run(sql, params) {
 		const stmt = this.db.prepare(sql);
@@ -215,6 +233,27 @@ function buildAggregateCount$1(table, where, controls) {
 	return buildAggregateCount(sqliteDialect, table, where, controls);
 }
 /**
+* Converts an Atlas-style similarity score (1 = exact, 0 = orthogonal) to a
+* vec0 distance threshold.
+*
+* - cosine / dotProduct (mapped to cosine in DDL): vec0 distance = 1 - cos_sim,
+*   normalized score = (1 + cos_sim) / 2, so distance = 2 * (1 - score).
+* - euclidean (l2): vec0 distance is unbounded; the value is treated as a max
+*   distance directly (same convention as pgvector).
+*/
+function thresholdToVecDistance(threshold, similarity) {
+	if (similarity === "euclidean") return threshold;
+	return 2 * (1 - threshold);
+}
+/**
+* Maps an Atscript `@db.search.vector` similarity value to a sqlite-vec `vec0` metric.
+* `dotProduct` falls back to `cosine` because vec0 has no dedicated dot-product metric.
+*/
+function similarityToVecMetric(s) {
+	if (s === "euclidean") return "l2";
+	return "cosine";
+}
+/**
 * Maps Atscript design types to SQLite storage types.
 */
 function sqliteTypeFromDesignType(designType) {
@@ -231,12 +270,12 @@ function sqliteTypeFromDesignType(designType) {
 * Builds a CREATE TABLE IF NOT EXISTS statement from field descriptors.
 * Uses pre-computed {@link TDbFieldMeta} — no raw type introspection needed.
 */
-function buildCreateTable(table, fields, foreignKeys) {
+function buildCreateTable(table, fields, foreignKeys, options) {
 	const colDefs = [];
 	const primaryKeys = fields.filter((f) => f.isPrimaryKey);
 	for (const field of fields) {
 		if (field.ignored) continue;
-		const sqlType = field.isPrimaryKey && (field.designType === "number" || field.designType === "integer") ? "INTEGER" : sqliteTypeFromDesignType(field.designType);
+		const sqlType = options?.typeMapper?.(field) ?? (field.isPrimaryKey && (field.designType === "number" || field.designType === "integer") ? "INTEGER" : sqliteTypeFromDesignType(field.designType));
 		let def = `"${esc(field.physicalName)}" ${sqlType}`;
 		if (field.isPrimaryKey && primaryKeys.length === 1) {
 			def += " PRIMARY KEY";
@@ -301,15 +340,82 @@ function buildPrefixedWhere(alias, filter) {
 * const users = new AtscriptDbTable(UsersType, adapter)
 * ```
 */
-var SqliteAdapter = class extends BaseDbAdapter {
+var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	supportsNativeValueDefaults() {
 		return true;
 	}
+	/** Whether the SQLite connection has the sqlite-vec extension loaded. */
+	_supportsVector;
+	/** Vector fields: field path → { dimensions, similarity, indexName }. */
+	_vectorFields = /* @__PURE__ */ new Map();
+	/** Default similarity thresholds per vector index (from @db.search.vector.threshold). */
+	_vectorThresholds = /* @__PURE__ */ new Map();
+	/** Partition filter fields per vector index (from @db.search.filter). Field paths. */
+	_vectorPartitionFields = /* @__PURE__ */ new Map();
 	constructor(driver) {
 		super();
 		this.driver = driver;
 		this.driver.exec("PRAGMA foreign_keys = ON");
 	}
+	onFieldScanned(field, _type, metadata) {
+		const vectorMeta = metadata.get("db.search.vector");
+		if (vectorMeta) {
+			const indexName = vectorMeta.indexName || field;
+			this._vectorFields.set(field, {
+				dimensions: vectorMeta.dimensions,
+				similarity: vectorMeta.similarity || "cosine",
+				indexName
+			});
+			const threshold = metadata.get("db.search.vector.threshold");
+			if (threshold !== void 0) this._vectorThresholds.set(indexName, threshold);
+		}
+		for (const indexName of metadata.get("db.search.filter") || []) {
+			const list = this._vectorPartitionFields.get(indexName);
+			if (list) list.push(field);
+			else this._vectorPartitionFields.set(indexName, [field]);
+		}
+	}
+	formatValue(field) {
+		if (!this._vectorFields.has(field.path)) return;
+		if (this._detectVectorSupport()) return {
+			toStorage: (value) => Array.isArray(value) ? Buffer.from(new Float32Array(value).buffer) : value,
+			fromStorage: (value) => {
+				if (value instanceof Buffer || value instanceof Uint8Array) {
+					const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+					const arr = new Float32Array(buf.buffer, buf.byteOffset, Math.floor(buf.byteLength / 4));
+					return Array.from(arr);
+				}
+				return value;
+			}
+		};
+		return {
+			toStorage: (value) => Array.isArray(value) ? JSON.stringify(value) : value,
+			fromStorage: (value) => {
+				if (typeof value === "string") try {
+					return JSON.parse(value);
+				} catch {
+					return value;
+				}
+				return value;
+			}
+		};
+	}
+	isVectorSearchable() {
+		if (this._vectorFields.size === 0) return false;
+		return this._detectVectorSupport();
+	}
+	_detectVectorSupport() {
+		if (this._supportsVector !== void 0) return this._supportsVector;
+		if (this.driver.hasVectorExt !== void 0) this._supportsVector = this.driver.hasVectorExt;
+		else try {
+			this.driver.get("SELECT vec_version()");
+			this._supportsVector = true;
+		} catch {
+			this._supportsVector = false;
+		}
+		if (!this._supportsVector && this._vectorFields.size > 0) this._log("[atscript-db-sqlite] sqlite-vec extension not available — vector fields will be stored as JSON TEXT (no similarity search).");
+		return this._supportsVector;
+	}
 	async _beginTransaction() {
 		this._log("BEGIN");
 		this.driver.exec("BEGIN");
@@ -477,7 +583,7 @@ var SqliteAdapter = class extends BaseDbAdapter {
 	}
 	async ensureTable() {
 		if (this._table instanceof AtscriptDbView) return this.ensureView();
-		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys);
+		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
 		this._log(sql);
 		this.driver.exec(sql);
 		this._seedIncrementStart();
@@ -538,10 +644,11 @@ var SqliteAdapter = class extends BaseDbAdapter {
 		const tableName = this.resolveTableName();
 		const tempName = `${tableName}__tmp_${Date.now()}`;
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		this.driver.exec("PRAGMA foreign_keys = OFF");
 		this.driver.exec("PRAGMA legacy_alter_table = ON");
 		try {
-			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys);
+			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
 			this._log(createSql);
 			this.driver.exec(createSql);
 			const oldCols = (await this.getExistingColumns()).map((c) => c.name);
@@ -575,6 +682,7 @@ var SqliteAdapter = class extends BaseDbAdapter {
 	async dropTable() {
 		const tableName = this.resolveTableName();
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
 		this._log(ddl);
 		this.driver.exec(ddl);
@@ -591,6 +699,7 @@ var SqliteAdapter = class extends BaseDbAdapter {
 	}
 	async dropTableByName(tableName) {
 		this._dropAllFtsTables(tableName);
+		this._dropAllVecTables(tableName);
 		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
 		this._log(ddl);
 		this.driver.exec(ddl);
@@ -607,6 +716,7 @@ var SqliteAdapter = class extends BaseDbAdapter {
 		this.driver.exec(ddl);
 	}
 	typeMapper(field) {
+		if (this._vectorFields.has(field.path)) return this._detectVectorSupport() ? "BLOB" : "TEXT";
 		if (field.isPrimaryKey && (field.designType === "number" || field.designType === "integer")) return "INTEGER";
 		return sqliteTypeFromDesignType(field.designType);
 	}
@@ -638,13 +748,21 @@ var SqliteAdapter = class extends BaseDbAdapter {
 			shouldSkipType: (type) => type === "fulltext"
 		});
 		this._syncFtsIndexes(tableName);
+		this._syncVecIndexes(tableName);
 	}
 	getSearchIndexes() {
-		return this._getFulltextIndexes().map((idx) => ({
+		const indexes = [];
+		for (const idx of this._getFulltextIndexes()) indexes.push({
 			name: idx.name,
 			description: `FTS5 index (${idx.fields.map((f) => f.name).join(", ")})`,
 			type: "text"
-		}));
+		});
+		for (const [field, vec] of this._vectorFields) indexes.push({
+			name: vec.indexName,
+			description: `vec0 index on ${field} (${vec.dimensions}, ${vec.similarity})`,
+			type: "vector"
+		});
+		return indexes;
 	}
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
@@ -780,6 +898,225 @@ var SqliteAdapter = class extends BaseDbAdapter {
 		const ftsTables = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__fts__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE"));
 		for (const { name } of ftsTables) this._dropFtsTable(name);
 	}
+	static _RESIDUAL_OVERFETCH = 4;
+	async vectorSearch(vector, query, indexName) {
+		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
+		const base = this._buildVectorSearchBase(vector, query, indexName);
+		return this._runVectorSearch(base);
+	}
+	async vectorSearchWithCount(vector, query, indexName) {
+		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
+		const base = this._buildVectorSearchBase(vector, query, indexName);
+		const data = this._runVectorSearch(base);
+		const countSql = `SELECT COUNT(*) AS cnt ${base.fromWhere}`;
+		this._log(countSql, base.params);
+		return {
+			data,
+			count: this.driver.get(countSql, base.params)?.cnt ?? 0
+		};
+	}
+	_runVectorSearch(base) {
+		let sql = `SELECT * ${base.fromWhere} ORDER BY _distance ASC LIMIT ?`;
+		const params = [...base.params, base.limit];
+		if (base.skip > 0) {
+			sql += ` OFFSET ?`;
+			params.push(base.skip);
+		}
+		this._log(sql, params);
+		return this.driver.all(sql, params);
+	}
+	/** Resolves a vector index (by name or first available) and its partition fields. */
+	_resolveVectorIndex(indexName) {
+		let entry;
+		if (indexName) {
+			for (const [f, v] of this._vectorFields) if (v.indexName === indexName) {
+				entry = [f, v];
+				break;
+			}
+			if (!entry) throw new Error(`Vector index "${indexName}" not found`);
+		} else {
+			const first = this._vectorFields.entries().next();
+			if (first.done) throw new Error("No vector fields defined");
+			entry = first.value;
+		}
+		const [field, vec] = entry;
+		const partitionPhysicalNames = /* @__PURE__ */ new Set();
+		for (const logicalPath of this._vectorPartitionFields.get(vec.indexName) ?? []) {
+			const descriptor = this._table.fieldDescriptors.find((f) => f.path === logicalPath);
+			partitionPhysicalNames.add(descriptor?.physicalName ?? logicalPath);
+		}
+		return {
+			field,
+			vec,
+			partitionPhysicalNames
+		};
+	}
+	/** Query-time `$threshold` overrides the schema-level threshold (mirrors postgres precedence). */
+	_resolveVectorThreshold(controls, indexName) {
+		const queryThreshold = controls.$threshold;
+		if (queryThreshold !== void 0) return queryThreshold;
+		return this._vectorThresholds.get(indexName);
+	}
+	/**
+	* Splits the (already physical-name) filter into partition equality push-down
+	* vs. residual filter. Only top-level primitive equality is pushed down.
+	*/
+	_splitVectorFilter(filter, partitionPhysicalNames) {
+		const partition = [];
+		const residual = {};
+		if (!filter || typeof filter !== "object") return {
+			partition,
+			residual: filter
+		};
+		for (const [key, value] of Object.entries(filter)) if (partitionPhysicalNames.has(key) && value !== null && (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")) partition.push({
+			name: key,
+			value
+		});
+		else residual[key] = value;
+		return {
+			partition,
+			residual
+		};
+	}
+	/**
+	* Builds the shared FROM+WHERE fragment for vec0 KNN queries (without ORDER/LIMIT).
+	* Both `vectorSearch` and `vectorSearchWithCount` reuse this — the former appends
+	* ORDER BY + LIMIT/OFFSET, the latter wraps it in a COUNT(*).
+	*/
+	_buildVectorSearchBase(vector, query, indexName) {
+		const { vec, partitionPhysicalNames } = this._resolveVectorIndex(indexName);
+		if (vector.length !== vec.dimensions) throw new Error(`Vector dimension mismatch: index "${vec.indexName}" expects ${vec.dimensions}, got ${vector.length}`);
+		const vecBuf = Buffer.from(new Float32Array(vector).buffer);
+		const controls = query.controls || {};
+		const limit = controls.$limit ?? 20;
+		const skip = controls.$skip ?? 0;
+		const threshold = this._resolveVectorThreshold(controls, vec.indexName);
+		const { partition, residual } = this._splitVectorFilter(query.filter, partitionPhysicalNames);
+		const residualWhere = buildPrefixedWhere("_vs", residual);
+		const hasResidual = residualWhere.sql !== "1=1";
+		const hasThreshold = threshold !== void 0;
+		const k = (limit + skip) * (hasResidual || hasThreshold ? SqliteAdapter._RESIDUAL_OVERFETCH : 1);
+		const tableName = this.resolveTableName();
+		const vecTable = this._vecTableName(vec.indexName);
+		const innerWhereParts = ["v.embedding MATCH ?", "v.k = ?"];
+		const params = [vecBuf, k];
+		for (const p of partition) {
+			innerWhereParts.push(`v."${esc(p.name)}" = ?`);
+			params.push(p.value);
+		}
+		let fromWhere = `FROM (${`SELECT t.*, v.distance AS _distance FROM "${esc(vecTable)}" v JOIN "${esc(tableName)}" t ON t.rowid = v.rowid WHERE ${innerWhereParts.join(" AND ")}`}) _vs`;
+		const outerWhereParts = [];
+		if (hasThreshold) {
+			outerWhereParts.push(`_distance <= ?`);
+			params.push(thresholdToVecDistance(threshold, vec.similarity));
+		}
+		if (hasResidual) {
+			outerWhereParts.push(`(${residualWhere.sql})`);
+			params.push(...residualWhere.params);
+		}
+		if (outerWhereParts.length > 0) fromWhere += ` WHERE ${outerWhereParts.join(" AND ")}`;
+		return {
+			fromWhere,
+			params,
+			limit,
+			skip
+		};
+	}
+	/** Builds vec0 shadow table name from index name: `<table>__vec__<indexName>`. */
+	_vecTableName(indexName) {
+		return `${this.resolveTableName()}__vec__${indexName}`;
+	}
+	/**
+	* Creates/drops vec0 virtual shadow tables and sync triggers to match desired vector fields.
+	*/
+	_syncVecIndexes(tableName) {
+		if (this._vectorFields.size === 0) return;
+		if (!this._detectVectorSupport()) {
+			this._log("[atscript-db-sqlite] sqlite-vec not available, skipping vec0 shadow table sync (vector fields stored as JSON)");
+			return;
+		}
+		const desiredVecTables = /* @__PURE__ */ new Map();
+		for (const [fieldPath, meta] of this._vectorFields.entries()) desiredVecTables.set(this._vecTableName(meta.indexName), {
+			field: fieldPath,
+			meta
+		});
+		const existingVec = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__vec__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE")).map((r) => r.name);
+		for (const name of existingVec) if (!desiredVecTables.has(name)) this._dropVecTable(name);
+		const existingSet = new Set(existingVec);
+		for (const [vecTable, { field, meta }] of desiredVecTables.entries()) if (!existingSet.has(vecTable)) this._createVecTable(tableName, vecTable, field, meta);
+	}
+	/** Creates a vec0 virtual shadow table with sync triggers and seeds it from existing rows. */
+	_createVecTable(tableName, vecTable, field, vec) {
+		const metric = similarityToVecMetric(vec.similarity);
+		const embeddingCol = this._table.fieldDescriptors.find((f) => f.path === field)?.physicalName ?? field;
+		const partitionFieldPaths = this._vectorPartitionFields.get(vec.indexName) ?? [];
+		const partitionCols = [];
+		for (const logicalPath of partitionFieldPaths) {
+			const descriptor = this._table.fieldDescriptors.find((f) => f.path === logicalPath);
+			if (!descriptor) {
+				this._log(`[atscript-db-sqlite] vec0 partition field "${logicalPath}" not found for index "${vec.indexName}", defaulting to TEXT`);
+				partitionCols.push({
+					physicalName: logicalPath,
+					sqlType: "TEXT"
+				});
+			} else partitionCols.push({
+				physicalName: descriptor.physicalName,
+				sqlType: this.typeMapper(descriptor)
+			});
+		}
+		for (const c of partitionCols) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(c.physicalName)) throw new Error(`vec0 partition column name "${c.physicalName}" is not a safe identifier (only [A-Za-z_][A-Za-z0-9_]* is allowed for @db.search.filter fields on SQLite).`);
+		const ddlCols = [partitionCols.map((c) => `${c.physicalName} ${c.sqlType} partition key`).join(", "), `embedding float[${vec.dimensions}] distance_metric=${metric}`].filter(Boolean).join(", ");
+		const createSql = `CREATE VIRTUAL TABLE IF NOT EXISTS "${esc(vecTable)}" USING vec0(${ddlCols})`;
+		this._log(createSql);
+		this.driver.exec(createSql);
+		const partCols = partitionCols.map((c) => `"${esc(c.physicalName)}"`);
+		const embCol = `"${esc(embeddingCol)}"`;
+		const insertCols = [
+			"rowid",
+			...partCols,
+			"embedding"
+		].join(", ");
+		const insertNewVals = [
+			"new.rowid",
+			...partitionCols.map((c) => `new."${esc(c.physicalName)}"`),
+			`new.${embCol}`
+		].join(", ");
+		const seedColList = [
+			"rowid",
+			...partCols,
+			embCol
+		].join(", ");
+		const ev = esc(vecTable);
+		const et = esc(tableName);
+		const aiSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__ai")}" AFTER INSERT ON "${et}" WHEN new.${embCol} IS NOT NULL BEGIN INSERT INTO "${ev}"(${insertCols}) VALUES(${insertNewVals}); END`;
+		this._log(aiSql);
+		this.driver.exec(aiSql);
+		const adSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__ad")}" AFTER DELETE ON "${et}" BEGIN DELETE FROM "${ev}" WHERE rowid = old.rowid; END`;
+		this._log(adSql);
+		this.driver.exec(adSql);
+		const auSql = `CREATE TRIGGER IF NOT EXISTS "${esc(vecTable + "__au")}" AFTER UPDATE ON "${et}" BEGIN DELETE FROM "${ev}" WHERE rowid = old.rowid; INSERT INTO "${ev}"(${insertCols}) SELECT ${insertNewVals} WHERE new.${embCol} IS NOT NULL; END`;
+		this._log(auSql);
+		this.driver.exec(auSql);
+		const seedSql = `INSERT INTO "${ev}"(${insertCols}) SELECT ${seedColList} FROM "${et}" WHERE ${embCol} IS NOT NULL`;
+		this._log(seedSql);
+		this.driver.exec(seedSql);
+	}
+	/** Drops a vec0 virtual table and its sync triggers. */
+	_dropVecTable(vecTable) {
+		for (const suffix of [
+			"__ai",
+			"__ad",
+			"__au"
+		]) this.driver.exec(`DROP TRIGGER IF EXISTS "${esc(vecTable + suffix)}"`);
+		const sql = `DROP TABLE IF EXISTS "${esc(vecTable)}"`;
+		this._log(sql);
+		this.driver.exec(sql);
+	}
+	/** Drops all vec0 virtual shadow tables and triggers for a content table. */
+	_dropAllVecTables(tableName) {
+		const vecTables = this.driver.all(`SELECT name, sql FROM sqlite_master WHERE type='table' AND name LIKE ?`, [`${tableName}__vec__%`]).filter((r) => r.sql.startsWith("CREATE VIRTUAL TABLE"));
+		for (const { name } of vecTables) this._dropVecTable(name);
+	}
 };
 /** Normalizes SQLite PRAGMA dflt_value to match serialized format.
 *  PRAGMA returns `'active'` (SQL-quoted), we store `active` (raw). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sqlite",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "description": "SQLite adapter for @atscript/db with swappable driver support.",
   "keywords": [
     "atscript",
@@ -41,6 +41,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@uniqu/core": "^0.1.6",
     "better-sqlite3": "^12.6.2",
+    "sqlite-vec": "^0.1.9",
     "unplugin-atscript": "^0.1.53"
   },
   "peerDependencies": {
@@ -48,14 +49,17 @@
     "@atscript/typescript": "^0.1.53",
     "@uniqu/core": "^0.1.6",
     "better-sqlite3": ">=11.0.0",
-    "@atscript/db": "^0.1.72",
-    "@atscript/db-sql-tools": "^0.1.72"
+    "@atscript/db-sql-tools": "^0.1.74",
+    "@atscript/db": "^0.1.74"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {
       "optional": true
     }
   },
+  "optionalDependencies": {
+    "sqlite-vec": "^0.1.9"
+  },
   "scripts": {
     "postinstall": "asc -f dts",
     "build": "vp pack",