@atscript/db-sqlite 0.1.163 → 0.1.165

package/dist/index.cjs

@@ -379,8 +379,8 @@ function haversineDistanceExpr(quotedCol, point) {
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
-function buildSelect(table, where, controls) {
-	return (0, _atscript_db_sql_tools.buildSelect)(sqliteDialect, table, where, controls);
+function buildSelect(table, where, controls, defaultOrder) {
+	return (0, _atscript_db_sql_tools.buildSelect)(sqliteDialect, table, where, controls, void 0, defaultOrder);
 }
 /**
 * Builds an UPDATE ... SET ... WHERE statement.
@@ -1011,32 +1011,42 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 	* Wraps a write operation to catch native SQLite constraint errors
 	* and rethrow as structured `DbError`.
 	*/
-	_wrapConstraintError(fn) {
+	_wrapConstraintError(fn, row) {
 		try {
 			return fn();
 		} catch (error) {
 			if (error instanceof Error) {
-				if (error.message.includes("FOREIGN KEY constraint failed")) throw new _atscript_db.DbError("FK_VIOLATION", [{
-					path: "",
-					message: error.message
-				}]);
-				const uniqueMatch = error.message.match(/UNIQUE constraint failed:\s*\S+\.(\S+)/);
-				if (uniqueMatch) throw new _atscript_db.DbError("CONFLICT", [{
-					path: uniqueMatch[1],
-					message: error.message
-				}]);
-				if (error.message.includes("UNIQUE constraint failed")) throw new _atscript_db.DbError("CONFLICT", [{
-					path: "",
-					message: error.message
-				}]);
+				if (error.message.includes("FOREIGN KEY constraint failed")) {
+					const columns = row ? this._probeFkViolation(row) : void 0;
+					throw (0, _atscript_db.constraintViolation)("FK_VIOLATION", columns ? { columns } : {}, error.message);
+				}
+				const unique = error.message.match(/UNIQUE constraint failed:\s*(.+)$/);
+				if (unique) throw (0, _atscript_db.constraintViolation)("CONFLICT", { columns: unique[1].split(",").map((c) => c.trim().replace(/^.*\./, "")).filter(Boolean) }, error.message);
 			}
 			throw error;
 		}
 	}
+	/**
+	* The physical columns of the first foreign key whose (non-null) value in
+	* `row` names no target row — what SQLite's `FOREIGN KEY constraint
+	* failed` leaves out. Runs only on that error path.
+	*/
+	_probeFkViolation(row) {
+		for (const fk of this._table.foreignKeys.values()) {
+			const columns = fk.physicalFields ?? fk.fields;
+			const values = columns.map((c) => row[c]);
+			if (values.some((v) => v === null || v === void 0)) continue;
+			const where = (fk.physicalTargetFields ?? fk.targetFields).map((c) => `"${esc(c)}" = ?`).join(" AND ");
+			const sql = `SELECT 1 AS hit FROM "${esc(fk.targetTable)}" WHERE ${where} LIMIT 1`;
+			try {
+				if (!this.driver.get(sql, values)) return [...columns];
+			} catch {}
+		}
+	}
 	async insertOne(data) {
 		const { sql, params } = this._insertSql.build(this.resolveTableName(), data);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return { insertedId: this._resolveInsertedId(data, result.lastInsertRowid) };
 	}
 	async insertMany(data) {
@@ -1054,7 +1064,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 				for (const row of data) {
 					const { sql, params } = this._insertSql.build(tableName, row);
 					this._log(sql, params);
-					const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+					const result = this._wrapConstraintError(() => this.driver.run(sql, params), row);
 					out.push(this._resolveInsertedId(row, result.lastInsertRowid));
 				}
 				return out;
@@ -1082,7 +1092,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 				const sql = `${built.sql} ON CONFLICT DO NOTHING`;
 				const params = built.params;
 				this._log(sql, params);
-				const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+				const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), row));
 				slots.push(result.changes === 0 ? null : { insertedId: this._resolveInsertedId(row, result.lastInsertRowid) });
 			}
 			return slots;
@@ -1163,7 +1173,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 			params: where.params
 		}, ops, versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1191,7 +1201,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 		const versionColumn = this._versionColumnFor(opts);
 		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, ops, versionColumn);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1201,12 +1211,13 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 		const where = buildWhere(filter);
 		const tableName = this.resolveTableName();
 		const versionColumn = this._table.versionColumnPhysical;
-		const { sql, params } = buildUpdate(tableName, (0, _atscript_db_sql_tools.fillReplacePayload)(data, (0, _atscript_db_sql_tools.replaceColumnsFor)(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn, this._table.onUpdateIncPhysical), {
+		const full = (0, _atscript_db_sql_tools.fillReplacePayload)(data, (0, _atscript_db_sql_tools.replaceColumnsFor)(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn, this._table.onUpdateIncPhysical);
+		const { sql, params } = buildUpdate(tableName, full, {
 			sql: `rowid = (SELECT rowid FROM "${esc(tableName)}" WHERE ${where.sql} LIMIT 1)`,
 			params: where.params
 		}, this._onUpdateIncOps(), versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), full));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1217,7 +1228,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 		const versionColumn = this._table.versionColumnPhysical;
 		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, this._onUpdateIncOps(), versionColumn);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1582,19 +1593,56 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
 		const plan = this._searchPlan(text, indexName);
-		if (!plan.join) {
-			const { sql, params } = buildSelect(this.resolveTableName(), andWhere(plan.predicate, buildWhere(query.filter)), query.controls);
+		const controls = query.controls || {};
+		const sorted = (0, _atscript_db_sql_tools.orderByList)(sqliteDialect, controls.$sort, controls.$nulls, "t.");
+		if (!plan.join && (sorted || plan.textFields === 0)) {
+			const { sql, params } = buildSelect(this.resolveTableName(), andWhere(plan.predicate, buildWhere(query.filter)), query.controls, (0, _atscript_db_sql_tools.searchRankOrder)(sqliteDialect, {
+				...plan.exact,
+				pkColumns: this._pkColumns()
+			}));
 			this._log(sql, params);
 			return this._stmt(() => this.driver.all(sql, params));
 		}
-		const base = this._buildFtsBase(text, query.filter, indexName);
-		const controls = query.controls || {};
+		const fts = this._ftsTableName(plan.index.name);
+		let head;
+		let params;
+		let textRank;
+		if (plan.join) {
+			const base = this._buildFtsBase(text, query.filter, plan.index);
+			head = base.fromWhere;
+			params = [...base.params];
+			textRank = {
+				sql: `${this._bm25Expr(`fts."${esc(fts)}"`, plan.index)} ASC`,
+				params: []
+			};
+		} else {
+			const where = buildPrefixedWhere("t", query.filter);
+			const eqs = plan.exact.exactEqualities.map((eq) => `t.${eq}`);
+			head = `FROM "${esc(this.resolveTableName())}" AS t LEFT JOIN m ON m.__atscript_r = t.rowid WHERE (m.__atscript_r IS NOT NULL OR ${eqs.join(" OR ")})` + (where.sql === "1=1" ? "" : ` AND (${where.sql})`);
+			params = [
+				quoteFtsTerm(text),
+				...eqs.map(() => plan.exact.n),
+				...where.params
+			];
+			textRank = {
+				sql: "m.__atscript_s ASC",
+				params: []
+			};
+		}
+		const order = sorted ? {
+			sql: sorted,
+			params: []
+		} : (0, _atscript_db_sql_tools.searchRankOrder)(sqliteDialect, {
+			exactEqualities: plan.join ? [] : plan.exact.exactEqualities.map((eq) => `t.${eq}`),
+			n: plan.exact.n,
+			textRank,
+			pkColumns: this._pkColumns(),
+			prefix: "t."
+		});
 		let cols = "t.*";
 		if (controls.$select?.asArray?.length) cols = controls.$select.asArray.map((c) => `t."${esc(c)}"`).join(", ");
-		let sql = `SELECT ${cols} ${base.fromWhere}`;
-		const params = [...base.params];
-		const orderBy = (0, _atscript_db_sql_tools.orderByList)(sqliteDialect, controls.$sort, controls.$nulls, "t.");
-		if (orderBy) sql += ` ORDER BY ${orderBy}`;
+		let sql = `${plan.join ? "" : `WITH m AS MATERIALIZED (SELECT rowid AS __atscript_r, ${this._bm25Expr(`"${esc(fts)}"`, plan.index)} AS __atscript_s FROM "${esc(fts)}" WHERE "${esc(fts)}" MATCH ?) `}SELECT ${cols} ${head} ORDER BY ${order.sql}`;
+		params.push(...order.params);
 		if (controls.$limit !== void 0) {
 			sql += ` LIMIT ?`;
 			params.push(controls.$limit);
@@ -1617,7 +1665,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 		let countSql;
 		let countParams;
 		if (plan.join) {
-			const base = this._buildFtsBase(text, query.filter, indexName);
+			const base = this._buildFtsBase(text, query.filter, plan.index);
 			countSql = `SELECT COUNT(*) as cnt ${base.fromWhere}`;
 			countParams = base.params;
 		} else {
@@ -1681,6 +1729,7 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 		const index = this._resolveFtsIndex(indexName);
 		const { text: textFields, integer: integerFields } = (0, _atscript_db.splitFulltextFields)(index);
 		const n = integerFields.length > 0 ? (0, _atscript_db.searchTermInteger)(text) : void 0;
+		const equalities = n === void 0 ? [] : integerFields.map((f) => `"${esc(f.name)}" = ?`);
 		const parts = [];
 		const params = [];
 		if (textFields.length > 0) {
@@ -1688,21 +1737,39 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 			parts.push(`rowid IN (SELECT rowid FROM ${quoted} WHERE ${quoted} MATCH ?)`);
 			params.push(quoteFtsTerm(text));
 		}
-		if (n !== void 0) for (const f of integerFields) {
-			parts.push(`"${esc(f.name)}" = ?`);
+		for (const eq of equalities) {
+			parts.push(eq);
 			params.push(n);
 		}
 		return {
+			index,
 			predicate: (0, _atscript_db_sql_tools.orFragment)(parts, params),
-			join: textFields.length > 0 && n === void 0
+			join: textFields.length > 0 && n === void 0,
+			textFields: textFields.length,
+			exact: {
+				exactEqualities: equalities,
+				n
+			}
 		};
 	}
 	/**
+	* `bm25(<hidden column>[, w…])` over an index's text members (lower = better). The
+	* per-column weights follow the FTS5 table's column order; omitted when
+	* every member has the default weight.
+	*/
+	_bm25Expr(hidden, index) {
+		const weights = (0, _atscript_db.splitFulltextFields)(index).text.map((f) => f.weight ?? 1);
+		return weights.every((w) => w === 1) ? `bm25(${hidden})` : `bm25(${hidden}, ${weights.map((w) => String(w)).join(", ")})`;
+	}
+	/** The physical primary-key columns — the relevance tie-breaker. */
+	_pkColumns() {
+		return this._table.primaryKeys.map((key) => this._table.physicalPath(key));
+	}
+	/**
 	* Builds the shared FROM+JOIN+WHERE fragment for FTS5 queries.
 	* Both data and count queries reuse this to avoid duplicating index resolution and filter translation.
 	*/
-	_buildFtsBase(text, filter, indexName) {
-		const ftsIndex = this._resolveFtsIndex(indexName);
+	_buildFtsBase(text, filter, ftsIndex) {
 		const ftsTable = this._ftsTableName(ftsIndex.name);
 		const tableName = this.resolveTableName();
 		const where = buildPrefixedWhere("t", filter);

package/dist/index.d.cts

@@ -385,6 +385,12 @@ declare class SqliteAdapter extends BaseDbAdapter {
    * and rethrow as structured `DbError`.
    */
   private _wrapConstraintError;
+  /**
+   * The physical columns of the first foreign key whose (non-null) value in
+   * `row` names no target row — what SQLite's `FOREIGN KEY constraint
+   * failed` leaves out. Runs only on that error path.
+   */
+  private _probeFkViolation;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -519,6 +525,14 @@ declare class SqliteAdapter extends BaseDbAdapter {
    * behavior change for text-only searches).
    */
   private _searchPlan;
+  /**
+   * `bm25(<hidden column>[, w…])` over an index's text members (lower = better). The
+   * per-column weights follow the FTS5 table's column order; omitted when
+   * every member has the default weight.
+   */
+  private _bm25Expr;
+  /** The physical primary-key columns — the relevance tie-breaker. */
+  private _pkColumns;
   /**
    * Builds the shared FROM+JOIN+WHERE fragment for FTS5 queries.
    * Both data and count queries reuse this to avoid duplicating index resolution and filter translation.

package/dist/index.d.mts

@@ -385,6 +385,12 @@ declare class SqliteAdapter extends BaseDbAdapter {
    * and rethrow as structured `DbError`.
    */
   private _wrapConstraintError;
+  /**
+   * The physical columns of the first foreign key whose (non-null) value in
+   * `row` names no target row — what SQLite's `FOREIGN KEY constraint
+   * failed` leaves out. Runs only on that error path.
+   */
+  private _probeFkViolation;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -519,6 +525,14 @@ declare class SqliteAdapter extends BaseDbAdapter {
    * behavior change for text-only searches).
    */
   private _searchPlan;
+  /**
+   * `bm25(<hidden column>[, w…])` over an index's text members (lower = better). The
+   * per-column weights follow the FTS5 table's column order; omitted when
+   * every member has the default weight.
+   */
+  private _bm25Expr;
+  /** The physical primary-key columns — the relevance tie-breaker. */
+  private _pkColumns;
   /**
    * Builds the shared FROM+JOIN+WHERE fragment for FTS5 queries.
    * Both data and count queries reuse this to avoid duplicating index resolution and filter translation.

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, createChangeRecorder, defaultFulltextIndex, describeFulltext, fkColumns, searchIndexNotFoundMessage, searchTermInteger, splitFulltextFields, vectorIndexNotFoundMessage } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, constraintViolation, createChangeRecorder, defaultFulltextIndex, describeFulltext, fkColumns, searchIndexNotFoundMessage, searchTermInteger, splitFulltextFields, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { EMPTY_AND, InsertSqlCache, SEARCH_SOURCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, fromSourceSql, geoWindowFromControls, jsonDollarPath, orFragment, orderByList, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, viewReadSource, writeLimitWhere } from "@atscript/db-sql-tools";
+import { EMPTY_AND, InsertSqlCache, SEARCH_SOURCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, fromSourceSql, geoWindowFromControls, jsonDollarPath, orFragment, orderByList, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, searchRankOrder, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, viewReadSource, writeLimitWhere } from "@atscript/db-sql-tools";
 import { bucketer } from "@uniqu/core";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/better-sqlite3-driver.ts
@@ -378,8 +378,8 @@ function haversineDistanceExpr(quotedCol, point) {
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
-function buildSelect$1(table, where, controls) {
-	return buildSelect(sqliteDialect, table, where, controls);
+function buildSelect$1(table, where, controls, defaultOrder) {
+	return buildSelect(sqliteDialect, table, where, controls, void 0, defaultOrder);
 }
 /**
 * Builds an UPDATE ... SET ... WHERE statement.
@@ -1010,32 +1010,42 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	* Wraps a write operation to catch native SQLite constraint errors
 	* and rethrow as structured `DbError`.
 	*/
-	_wrapConstraintError(fn) {
+	_wrapConstraintError(fn, row) {
 		try {
 			return fn();
 		} catch (error) {
 			if (error instanceof Error) {
-				if (error.message.includes("FOREIGN KEY constraint failed")) throw new DbError("FK_VIOLATION", [{
-					path: "",
-					message: error.message
-				}]);
-				const uniqueMatch = error.message.match(/UNIQUE constraint failed:\s*\S+\.(\S+)/);
-				if (uniqueMatch) throw new DbError("CONFLICT", [{
-					path: uniqueMatch[1],
-					message: error.message
-				}]);
-				if (error.message.includes("UNIQUE constraint failed")) throw new DbError("CONFLICT", [{
-					path: "",
-					message: error.message
-				}]);
+				if (error.message.includes("FOREIGN KEY constraint failed")) {
+					const columns = row ? this._probeFkViolation(row) : void 0;
+					throw constraintViolation("FK_VIOLATION", columns ? { columns } : {}, error.message);
+				}
+				const unique = error.message.match(/UNIQUE constraint failed:\s*(.+)$/);
+				if (unique) throw constraintViolation("CONFLICT", { columns: unique[1].split(",").map((c) => c.trim().replace(/^.*\./, "")).filter(Boolean) }, error.message);
 			}
 			throw error;
 		}
 	}
+	/**
+	* The physical columns of the first foreign key whose (non-null) value in
+	* `row` names no target row — what SQLite's `FOREIGN KEY constraint
+	* failed` leaves out. Runs only on that error path.
+	*/
+	_probeFkViolation(row) {
+		for (const fk of this._table.foreignKeys.values()) {
+			const columns = fk.physicalFields ?? fk.fields;
+			const values = columns.map((c) => row[c]);
+			if (values.some((v) => v === null || v === void 0)) continue;
+			const where = (fk.physicalTargetFields ?? fk.targetFields).map((c) => `"${esc(c)}" = ?`).join(" AND ");
+			const sql = `SELECT 1 AS hit FROM "${esc(fk.targetTable)}" WHERE ${where} LIMIT 1`;
+			try {
+				if (!this.driver.get(sql, values)) return [...columns];
+			} catch {}
+		}
+	}
 	async insertOne(data) {
 		const { sql, params } = this._insertSql.build(this.resolveTableName(), data);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return { insertedId: this._resolveInsertedId(data, result.lastInsertRowid) };
 	}
 	async insertMany(data) {
@@ -1053,7 +1063,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 				for (const row of data) {
 					const { sql, params } = this._insertSql.build(tableName, row);
 					this._log(sql, params);
-					const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+					const result = this._wrapConstraintError(() => this.driver.run(sql, params), row);
 					out.push(this._resolveInsertedId(row, result.lastInsertRowid));
 				}
 				return out;
@@ -1081,7 +1091,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 				const sql = `${built.sql} ON CONFLICT DO NOTHING`;
 				const params = built.params;
 				this._log(sql, params);
-				const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+				const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), row));
 				slots.push(result.changes === 0 ? null : { insertedId: this._resolveInsertedId(row, result.lastInsertRowid) });
 			}
 			return slots;
@@ -1162,7 +1172,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 			params: where.params
 		}, ops, versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1190,7 +1200,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const versionColumn = this._versionColumnFor(opts);
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, ops, versionColumn);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1200,12 +1210,13 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const where = buildWhere(filter);
 		const tableName = this.resolveTableName();
 		const versionColumn = this._table.versionColumnPhysical;
-		const { sql, params } = buildUpdate$1(tableName, fillReplacePayload(data, replaceColumnsFor(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn, this._table.onUpdateIncPhysical), {
+		const full = fillReplacePayload(data, replaceColumnsFor(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn, this._table.onUpdateIncPhysical);
+		const { sql, params } = buildUpdate$1(tableName, full, {
 			sql: `rowid = (SELECT rowid FROM "${esc(tableName)}" WHERE ${where.sql} LIMIT 1)`,
 			params: where.params
 		}, this._onUpdateIncOps(), versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), full));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1216,7 +1227,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const versionColumn = this._table.versionColumnPhysical;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, this._onUpdateIncOps(), versionColumn);
 		this._log(sql, params);
-		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params), data));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -1581,19 +1592,56 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
 		const plan = this._searchPlan(text, indexName);
-		if (!plan.join) {
-			const { sql, params } = buildSelect$1(this.resolveTableName(), andWhere(plan.predicate, buildWhere(query.filter)), query.controls);
+		const controls = query.controls || {};
+		const sorted = orderByList(sqliteDialect, controls.$sort, controls.$nulls, "t.");
+		if (!plan.join && (sorted || plan.textFields === 0)) {
+			const { sql, params } = buildSelect$1(this.resolveTableName(), andWhere(plan.predicate, buildWhere(query.filter)), query.controls, searchRankOrder(sqliteDialect, {
+				...plan.exact,
+				pkColumns: this._pkColumns()
+			}));
 			this._log(sql, params);
 			return this._stmt(() => this.driver.all(sql, params));
 		}
-		const base = this._buildFtsBase(text, query.filter, indexName);
-		const controls = query.controls || {};
+		const fts = this._ftsTableName(plan.index.name);
+		let head;
+		let params;
+		let textRank;
+		if (plan.join) {
+			const base = this._buildFtsBase(text, query.filter, plan.index);
+			head = base.fromWhere;
+			params = [...base.params];
+			textRank = {
+				sql: `${this._bm25Expr(`fts."${esc(fts)}"`, plan.index)} ASC`,
+				params: []
+			};
+		} else {
+			const where = buildPrefixedWhere("t", query.filter);
+			const eqs = plan.exact.exactEqualities.map((eq) => `t.${eq}`);
+			head = `FROM "${esc(this.resolveTableName())}" AS t LEFT JOIN m ON m.__atscript_r = t.rowid WHERE (m.__atscript_r IS NOT NULL OR ${eqs.join(" OR ")})` + (where.sql === "1=1" ? "" : ` AND (${where.sql})`);
+			params = [
+				quoteFtsTerm(text),
+				...eqs.map(() => plan.exact.n),
+				...where.params
+			];
+			textRank = {
+				sql: "m.__atscript_s ASC",
+				params: []
+			};
+		}
+		const order = sorted ? {
+			sql: sorted,
+			params: []
+		} : searchRankOrder(sqliteDialect, {
+			exactEqualities: plan.join ? [] : plan.exact.exactEqualities.map((eq) => `t.${eq}`),
+			n: plan.exact.n,
+			textRank,
+			pkColumns: this._pkColumns(),
+			prefix: "t."
+		});
 		let cols = "t.*";
 		if (controls.$select?.asArray?.length) cols = controls.$select.asArray.map((c) => `t."${esc(c)}"`).join(", ");
-		let sql = `SELECT ${cols} ${base.fromWhere}`;
-		const params = [...base.params];
-		const orderBy = orderByList(sqliteDialect, controls.$sort, controls.$nulls, "t.");
-		if (orderBy) sql += ` ORDER BY ${orderBy}`;
+		let sql = `${plan.join ? "" : `WITH m AS MATERIALIZED (SELECT rowid AS __atscript_r, ${this._bm25Expr(`"${esc(fts)}"`, plan.index)} AS __atscript_s FROM "${esc(fts)}" WHERE "${esc(fts)}" MATCH ?) `}SELECT ${cols} ${head} ORDER BY ${order.sql}`;
+		params.push(...order.params);
 		if (controls.$limit !== void 0) {
 			sql += ` LIMIT ?`;
 			params.push(controls.$limit);
@@ -1616,7 +1664,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		let countSql;
 		let countParams;
 		if (plan.join) {
-			const base = this._buildFtsBase(text, query.filter, indexName);
+			const base = this._buildFtsBase(text, query.filter, plan.index);
 			countSql = `SELECT COUNT(*) as cnt ${base.fromWhere}`;
 			countParams = base.params;
 		} else {
@@ -1680,6 +1728,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const index = this._resolveFtsIndex(indexName);
 		const { text: textFields, integer: integerFields } = splitFulltextFields(index);
 		const n = integerFields.length > 0 ? searchTermInteger(text) : void 0;
+		const equalities = n === void 0 ? [] : integerFields.map((f) => `"${esc(f.name)}" = ?`);
 		const parts = [];
 		const params = [];
 		if (textFields.length > 0) {
@@ -1687,21 +1736,39 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 			parts.push(`rowid IN (SELECT rowid FROM ${quoted} WHERE ${quoted} MATCH ?)`);
 			params.push(quoteFtsTerm(text));
 		}
-		if (n !== void 0) for (const f of integerFields) {
-			parts.push(`"${esc(f.name)}" = ?`);
+		for (const eq of equalities) {
+			parts.push(eq);
 			params.push(n);
 		}
 		return {
+			index,
 			predicate: orFragment(parts, params),
-			join: textFields.length > 0 && n === void 0
+			join: textFields.length > 0 && n === void 0,
+			textFields: textFields.length,
+			exact: {
+				exactEqualities: equalities,
+				n
+			}
 		};
 	}
 	/**
+	* `bm25(<hidden column>[, w…])` over an index's text members (lower = better). The
+	* per-column weights follow the FTS5 table's column order; omitted when
+	* every member has the default weight.
+	*/
+	_bm25Expr(hidden, index) {
+		const weights = splitFulltextFields(index).text.map((f) => f.weight ?? 1);
+		return weights.every((w) => w === 1) ? `bm25(${hidden})` : `bm25(${hidden}, ${weights.map((w) => String(w)).join(", ")})`;
+	}
+	/** The physical primary-key columns — the relevance tie-breaker. */
+	_pkColumns() {
+		return this._table.primaryKeys.map((key) => this._table.physicalPath(key));
+	}
+	/**
 	* Builds the shared FROM+JOIN+WHERE fragment for FTS5 queries.
 	* Both data and count queries reuse this to avoid duplicating index resolution and filter translation.
 	*/
-	_buildFtsBase(text, filter, indexName) {
-		const ftsIndex = this._resolveFtsIndex(indexName);
+	_buildFtsBase(text, filter, ftsIndex) {
 		const ftsTable = this._ftsTableName(ftsIndex.name);
 		const tableName = this.resolveTableName();
 		const where = buildPrefixedWhere("t", filter);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sqlite",
-  "version": "0.1.163",
+  "version": "0.1.165",
   "description": "SQLite adapter for @atscript/db with swappable driver support.",
   "keywords": [
     "atscript",
@@ -36,21 +36,21 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.109",
-    "@atscript/typescript": "^0.1.109",
+    "@atscript/core": "^0.2.1",
+    "@atscript/typescript": "^0.2.1",
     "@types/better-sqlite3": "^7.6.13",
     "@uniqu/core": "^0.1.15",
     "better-sqlite3": "^12.6.2",
     "sqlite-vec": "^0.1.9",
-    "unplugin-atscript": "^0.1.109"
+    "unplugin-atscript": "^0.2.1"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.109",
-    "@atscript/typescript": "^0.1.109",
+    "@atscript/core": "^0.2.1",
+    "@atscript/typescript": "^0.2.1",
     "@uniqu/core": "^0.1.15",
     "better-sqlite3": ">=11.0.0",
-    "@atscript/db": "^0.1.163",
-    "@atscript/db-sql-tools": "^0.1.163"
+    "@atscript/db": "^0.1.165",
+    "@atscript/db-sql-tools": "^0.1.165"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {