@an5/adapters 0.2.10 → 0.2.13

package/dist/googlesheets/adapter.js

@@ -3,27 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.An5SheetsAdapter = void 0;
 exports.createAn5SheetsAdapter = createAn5SheetsAdapter;
 const config_1 = require("./config");
+const oauth_1 = require("./oauth");
 const sqlExecutor_1 = require("./sqlExecutor");
 const tableClient_1 = require("./tableClient");
 const retry_1 = require("./retry");
 const metadata_1 = require("../base/metadata");
 // ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
-function createFetchApi(spreadsheetId, accessToken, apiKey) {
+function createFetchApi(spreadsheetId, accessToken, apiKey, oauth = { spreadsheetId }) {
     const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
     const headers = { 'Content-Type': 'application/json' };
-    if (accessToken) {
-        headers['Authorization'] = `Bearer ${accessToken}`;
-    }
+    const tokenProvider = (0, oauth_1.sheetsTokenProvider)({ ...oauth, ...(accessToken ? { accessToken } : {}) });
     async function request(method, path, body) {
         let url = path.startsWith('http') ? path : `${base}${path}`;
         if (apiKey) {
             const sep = url.includes('?') ? '&' : '?';
             url += `${sep}key=${encodeURIComponent(apiKey)}`;
         }
-        const opts = { method, headers };
+        const token = await tokenProvider();
+        const opts = { method, headers: { ...headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) } };
         if (body)
             opts.body = JSON.stringify(body);
-        const res = await fetch(url, opts);
+        let res = await fetch(url, opts);
+        if (res.status === 401 && oauth.refreshToken) {
+            const refreshed = await tokenProvider(true);
+            res = await fetch(url, { ...opts, headers: { ...headers, Authorization: `Bearer ${refreshed}` } });
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => '');
             const err = new Error(`Google Sheets API error (${res.status}): ${text}`);
@@ -79,17 +83,21 @@ class An5SheetsAdapter {
         this.sheets = null;
         this.fetchApi = null;
         this.sheetsCache = null;
+        const browser = typeof window !== 'undefined' || (typeof self !== 'undefined' && typeof process === 'undefined');
+        if (browser && (config.refreshToken || config.oauthClientSecret || config.privateKey || config.credentials)) {
+            throw new Error('Browser Google Sheets connections require a user access token. Keep desktop OAuth refresh tokens and service account keys outside the browser.');
+        }
         this.config = (0, config_1.resolveConfig)(config);
         // Dynamic model access (`db.user` / `db.User`), same as An5Adapter.
         return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
     }
     get isFetchMode() {
-        return !!this.config.accessToken || !!this.config.apiKey;
+        return !!this.config.accessToken || !!this.config.refreshToken || !!this.config.apiKey;
     }
     async getSheets() {
         if (this.isFetchMode) {
             if (!this.fetchApi) {
-                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey);
+                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey, this.config);
             }
             return this.fetchApi;
         }

package/dist/googlesheets/config.d.ts

@@ -11,6 +11,11 @@ export interface An5SheetsAdapterConfig {
      * When provided, the adapter uses raw fetch() instead of googleapis JWT, making it compatible
      * with browser environments. Mutually exclusive with clientEmail/privateKey/credentials. */
     accessToken?: string;
+    /** Offline desktop OAuth credentials. Keep these in secure storage, never source control. */
+    refreshToken?: string;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    tokenExpiresAt?: number;
     /** Google API key for browser-based API access. */
     apiKey?: string;
 }
@@ -18,12 +23,20 @@ export declare function normalizeKey(key: string): string;
 export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     spreadsheetId: string;
     accessToken: string | undefined;
+    refreshToken: string | undefined;
+    oauthClientId: string | undefined;
+    oauthClientSecret: string | undefined;
+    tokenExpiresAt: number | undefined;
     apiKey: string | undefined;
     sheetMapping: Record<string, string> | undefined;
     clientEmail?: never;
     privateKey?: never;
 } | {
     accessToken?: never;
+    refreshToken?: never;
+    oauthClientId?: never;
+    oauthClientSecret?: never;
+    tokenExpiresAt?: never;
     apiKey?: never;
     spreadsheetId: string;
     clientEmail: string;

package/dist/googlesheets/config.js

@@ -12,10 +12,14 @@ function normalizeKey(key) {
     return `-----BEGIN PRIVATE KEY-----\n${lines}\n-----END PRIVATE KEY-----`;
 }
 function resolveConfig(config) {
-    if (config.accessToken || config.apiKey) {
+    if (config.accessToken || config.refreshToken || config.apiKey) {
         return {
             spreadsheetId: config.spreadsheetId,
             accessToken: config.accessToken,
+            refreshToken: config.refreshToken,
+            oauthClientId: config.oauthClientId,
+            oauthClientSecret: config.oauthClientSecret,
+            tokenExpiresAt: config.tokenExpiresAt,
             apiKey: config.apiKey,
             sheetMapping: config.sheetMapping,
         };

package/dist/googlesheets/oauth.d.ts

@@ -0,0 +1,3 @@
+import type { An5SheetsAdapterConfig } from './config';
+/** Deduplicate refresh requests within an adapter; do not expose token responses. */
+export declare function sheetsTokenProvider(config: An5SheetsAdapterConfig): (force?: boolean) => Promise<string | undefined>;

package/dist/googlesheets/oauth.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sheetsTokenProvider = sheetsTokenProvider;
+/** Deduplicate refresh requests within an adapter; do not expose token responses. */
+function sheetsTokenProvider(config) {
+    let token = config.accessToken;
+    let expiresAt = config.tokenExpiresAt;
+    let pending;
+    return async (force = false) => {
+        if (token && !force && (expiresAt === undefined || expiresAt > Date.now() + 60000))
+            return token;
+        if (!config.refreshToken || !config.oauthClientId) {
+            if (force || expiresAt !== undefined)
+                throw new Error('Google access expired. Reconnect your Google account.');
+            return token;
+        }
+        if (!pending)
+            pending = (async () => {
+                try {
+                    const response = await fetch('https://oauth2.googleapis.com/token', {
+                        method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                        body: new URLSearchParams({ grant_type: 'refresh_token', client_id: config.oauthClientId, refresh_token: config.refreshToken, ...(config.oauthClientSecret ? { client_secret: config.oauthClientSecret } : {}) }),
+                        signal: AbortSignal.timeout(20000),
+                    });
+                    if (!response.ok)
+                        throw new Error();
+                    const result = await response.json();
+                    if (!result.access_token || typeof result.access_token !== 'string' || typeof result.expires_in !== 'number' || !Number.isFinite(result.expires_in) || result.expires_in <= 0)
+                        throw new Error();
+                    token = result.access_token;
+                    expiresAt = Date.now() + result.expires_in * 1000;
+                    return token;
+                }
+                catch {
+                    throw new Error('Google access expired or was revoked. Reconnect your Google account.');
+                }
+                finally {
+                    pending = undefined;
+                }
+            })();
+        return pending;
+    };
+}

package/dist/googlesheets/parseConnectionString.js

@@ -36,6 +36,18 @@ function parseSheetsConnectionString(url) {
         result.privateKey = config.privatekey;
     if (config.accesstoken)
         result.accessToken = config.accesstoken;
+    if (config.refreshtoken)
+        result.refreshToken = config.refreshtoken;
+    if (config.oauthclientid)
+        result.oauthClientId = config.oauthclientid;
+    if (config.oauthclientsecret)
+        result.oauthClientSecret = config.oauthclientsecret;
+    if (config.tokenexpiresat) {
+        const expiry = Number(config.tokenexpiresat);
+        if (!Number.isFinite(expiry) || expiry < 0)
+            throw new Error('Invalid OAuth token expiry.');
+        result.tokenExpiresAt = expiry;
+    }
     if (config.apikey)
         result.apiKey = config.apikey;
     if (config.sheetmapping) {

package/dist/googlesheets/tableClient.js

@@ -6,11 +6,6 @@ const metadata_1 = require("../base/metadata");
 const helpers_1 = require("./helpers");
 const retry_1 = require("./retry");
 // ─── Utility ──────────────────────────────────────────────────────────────────
-function resolveIdField(fields) {
-    if (Object.prototype.hasOwnProperty.call(fields, 'id'))
-        return 'id';
-    return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
-}
 // ─── Table Client ─────────────────────────────────────────────────────────────
 class SheetsTableClient {
     constructor(adapter, modelName, sheetMapping) {
@@ -156,7 +151,7 @@ class SheetsTableClient {
         return rows.length;
     }
     assignId(data, fields) {
-        const idFieldName = resolveIdField(fields);
+        const idFieldName = (0, metadata_1.resolveIdField)(fields);
         if (!idFieldName)
             return;
         const fieldDef = fields[idFieldName];
@@ -201,23 +196,10 @@ class SheetsTableClient {
             }
             return this.rowToValues(data, headers);
         });
-        try {
-            await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
-            return { count: batchValues.length };
-        }
-        catch (e) {
-            if (!args.skipDuplicates)
-                throw e;
-            let count = 0;
-            for (const row of args.data) {
-                try {
-                    await this.create({ data: row });
-                    count++;
-                }
-                catch { /* skip */ }
-            }
-            return { count };
-        }
+        // Sheets has no unique constraints. An append failure must propagate;
+        // retrying individual rows could duplicate a batch the service accepted.
+        await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
+        return { count: batchValues.length };
     }
     async update(args) {
         const { headers, rows } = await this.readAllRows();

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { parseWhere, buildOrderBy, quote } from './base/sql';
 export { NBaseVectorClient, NBaseError, createNBaseVectorClient, createNBaseClient, parseNBaseConnectionString, buildVectorId, parseVectorId, } from './nbase';
 export type { NBaseAdapterConfig, NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats, } from './nbase';
 export type { An5AdapterConfig, AdapterMetadata, Dialect, } from './an5Adapter';
+export { encodeVector, decodeVector, vectorDistance, isVectorField, AN5_VECTOR_FUNCTIONS, SQLITE_VEC_FUNCTIONS, } from './sqlite/vector';
+export type { SqliteVectorStrategy, VectorMetric, VectorStrategyPreference, } from './sqlite/vector';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
 export { getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig, resetAdapter, } from './config';
 export type { LlmConfigData, EmbeddingConfigData, } from './config';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
+exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.SQLITE_VEC_FUNCTIONS = exports.AN5_VECTOR_FUNCTIONS = exports.isVectorField = exports.vectorDistance = exports.decodeVector = exports.encodeVector = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
 var an5Adapter_1 = require("./an5Adapter");
 Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return an5Adapter_1.An5Adapter; } });
 Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return an5Adapter_1.AdapterTableClient; } });
@@ -20,6 +20,13 @@ Object.defineProperty(exports, "createNBaseClient", { enumerable: true, get: fun
 Object.defineProperty(exports, "parseNBaseConnectionString", { enumerable: true, get: function () { return nbase_1.parseNBaseConnectionString; } });
 Object.defineProperty(exports, "buildVectorId", { enumerable: true, get: function () { return nbase_1.buildVectorId; } });
 Object.defineProperty(exports, "parseVectorId", { enumerable: true, get: function () { return nbase_1.parseVectorId; } });
+var vector_1 = require("./sqlite/vector");
+Object.defineProperty(exports, "encodeVector", { enumerable: true, get: function () { return vector_1.encodeVector; } });
+Object.defineProperty(exports, "decodeVector", { enumerable: true, get: function () { return vector_1.decodeVector; } });
+Object.defineProperty(exports, "vectorDistance", { enumerable: true, get: function () { return vector_1.vectorDistance; } });
+Object.defineProperty(exports, "isVectorField", { enumerable: true, get: function () { return vector_1.isVectorField; } });
+Object.defineProperty(exports, "AN5_VECTOR_FUNCTIONS", { enumerable: true, get: function () { return vector_1.AN5_VECTOR_FUNCTIONS; } });
+Object.defineProperty(exports, "SQLITE_VEC_FUNCTIONS", { enumerable: true, get: function () { return vector_1.SQLITE_VEC_FUNCTIONS; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "getLlmConfig", { enumerable: true, get: function () { return config_1.getLlmConfig; } });
 Object.defineProperty(exports, "setLlmConfig", { enumerable: true, get: function () { return config_1.setLlmConfig; } });

package/dist/sqlite/browserEngine.d.ts

@@ -1,4 +1,5 @@
 import type { Dialect, QueryEngine, TransactionHandle } from '../base/types';
+import { SqliteVectorSupport } from './vector';
 export interface SqliteDriver {
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> | T[];
     executeRaw?(query: string, params?: Record<string, any>): Promise<number> | number;
@@ -9,9 +10,21 @@ export interface SqliteBrowserConfig {
     driver?: SqliteDriver;
     exec?: <T = any>(query: string, params?: Record<string, any>) => Promise<T[]> | T[];
     executeRaw?: (query: string, params?: Record<string, any>) => Promise<number> | number;
+    /** Path to the sqlite-vec extension, for WASM builds that allow loading one. */
+    sqliteVec?: string;
+    /** Pin the vector search strategy instead of probing for one. */
+    vectorStrategy?: 'auto' | 'sqlite-vec' | 'udf' | 'sql' | 'memory';
+    /** Register a scalar function with the driver, when its API allows it. */
+    registerFunction?: (name: string, fn: (...args: any[]) => any) => void;
 }
 export declare class SqliteBrowserEngine implements QueryEngine {
     dialect: Dialect;
+    /**
+     * A WASM build cannot register a JS callback as an SQL function, so this only
+     * reaches the `sql` strategy (json_each in plain SQL) and the in-memory one.
+     * A custom `registerFunction` hook unlocks `udf` as well.
+     */
+    readonly vectorSupport: SqliteVectorSupport;
     private db;
     private driver;
     private customExec;

package/dist/sqlite/browserEngine.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteBrowserEngine = void 0;
 exports.createBrowserSqliteAdapter = createBrowserSqliteAdapter;
+const vector_1 = require("./vector");
 // ─── Browser SQLite Engine ──────────────────────────────────────────────────────────
 class SqliteBrowserEngine {
     constructor(config) {
@@ -10,6 +11,18 @@ class SqliteBrowserEngine {
         this.driver = null;
         this.customExec = null;
         this.customExecuteRaw = null;
+        this.vectorSupport = new vector_1.SqliteVectorSupport({
+            native: () => this.db,
+            registerFunction: (name, fn) => {
+                const register = config?.registerFunction;
+                if (typeof register === 'function')
+                    return register(name, fn);
+                const db = this.db;
+                if (db && typeof db.create_function === 'function')
+                    return db.create_function(name, fn);
+                throw new Error('this SQLite build cannot register functions');
+            },
+        }, { sqliteVec: config?.sqliteVec, vectorStrategy: config?.vectorStrategy });
         if (!config)
             return;
         if (config.exec && typeof config.exec === 'function') {

package/dist/sqlite/engine.d.ts

@@ -1,9 +1,14 @@
 import type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from '../base/types';
+import { SqliteVectorSupport } from './vector';
 export declare class SqliteEngine implements QueryEngine {
     dialect: Dialect;
+    /** Registers `an5_vec_*` and loads sqlite-vec for in-database vector search. */
+    readonly vectorSupport: SqliteVectorSupport;
     private db;
     private readonly filePath;
     constructor(adapterConfig: An5AdapterConfig);
+    /** The better-sqlite3 handle, needed for extension loading. */
+    native(): any;
     private getDb;
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
     executeRaw(query: string, params?: Record<string, any>): Promise<number>;

package/dist/sqlite/engine.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteEngine = void 0;
+const vector_1 = require("./vector");
 // ─── SQLite Engine ─────────────────────────────────────────────────────────────────
 let BetterSqlite3 = null;
 try {
@@ -17,6 +18,14 @@ class SqliteEngine {
             .replace(/^sqlite:\/\/\//i, '/')
             .replace(/^sqlite:\/\//i, '')
             .replace(/^sqlite:/i, '');
+        this.vectorSupport = new vector_1.SqliteVectorSupport({
+            native: () => this.getDb(),
+            registerFunction: (name, fn) => this.getDb().function(name, { deterministic: true }, fn),
+        }, { sqliteVec: adapterConfig.sqliteVec, vectorStrategy: adapterConfig.vectorStrategy });
+    }
+    /** The better-sqlite3 handle, needed for extension loading. */
+    native() {
+        return this.getDb();
     }
     getDb() {
         if (!this.db)
@@ -42,6 +51,7 @@ class SqliteEngine {
             this.db.close();
             this.db = null;
         }
+        this.vectorSupport.reset();
     }
     async beginTransaction() {
         const db = this.getDb();

package/dist/sqlite/index.d.ts

@@ -1,2 +1,3 @@
 export * from './engine';
 export * from './browserEngine';
+export * from './vector';

package/dist/sqlite/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./engine"), exports);
 __exportStar(require("./browserEngine"), exports);
+__exportStar(require("./vector"), exports);

package/dist/sqlite/vector.d.ts

@@ -0,0 +1,155 @@
+export type VectorMetric = 'cosine' | 'euclidean' | 'dot';
+export type SqliteVectorStrategy = 'sqlite-vec' | 'udf' | 'sql' | 'memory';
+export type VectorStrategyPreference = 'auto' | SqliteVectorStrategy;
+/** Scalar functions shipped by the sqlite-vec extension. */
+export declare const SQLITE_VEC_FUNCTIONS: Record<VectorMetric, string>;
+/** Scalar functions the adapter registers itself when the driver allows it. */
+export declare const AN5_VECTOR_FUNCTIONS: Record<VectorMetric, string>;
+/** Read a numeric array out of the shapes a driver can hand back. */
+export declare function parseVector(value: unknown): number[] | null;
+/**
+ * Decode a stored vector: a float32 BLOB, a legacy JSON text column, or an
+ * array the caller already decoded.
+ */
+export declare function decodeVector(value: unknown): number[] | null;
+/** Encode a vector as the little-endian float32 BLOB `VECTOR(n)` columns store. */
+export declare function encodeVector(values: readonly number[]): Uint8Array;
+/** True when the value still needs encoding on its way into a `VECTOR(n)` column. */
+export declare function needsVectorEncoding(value: unknown): boolean;
+/** True when a generated metadata entry describes a `VECTOR(n)` column. */
+export declare function isVectorField(def: unknown): boolean;
+/**
+ * Distance between two equal-length vectors, lower is closer. Mirrors the
+ * functions registered on the drivers so a search ranks the same way whichever
+ * strategy ran.
+ */
+export declare function vectorDistance(a: readonly number[], b: readonly number[], metric: unknown): number | null;
+export interface SqliteVectorQuery {
+    sql: string;
+    params: Record<string, any>;
+}
+interface BuildArgs {
+    strategy: SqliteVectorStrategy;
+    metric: VectorMetric;
+    /** Already quoted, e.g. `[documents]`. */
+    table: string;
+    /** Already quoted column reference. */
+    column: string;
+    /** The query embedding. */
+    vector: number[];
+    take: number;
+    /** A WHERE tail built by the caller, or empty. */
+    tail?: string;
+    /** Pre-bound WHERE parameters shared with the caller. */
+    params: Record<string, any>;
+}
+/**
+ * Ranking SQL for one strategy. `sqlite-vec` and `udf` bind the query vector as
+ * a float32 BLOB; `sql` binds it as JSON text because `json_each` reads text.
+ */
+export declare function buildSqliteVectorQuery(args: BuildArgs): SqliteVectorQuery;
+export interface SqliteVectorCapabilities {
+    /** AN5's C extension is loaded; keep its functions instead of driver callbacks. */
+    native?: boolean;
+    /** `vec_version()` answered, so the sqlite-vec extension is loaded. */
+    vec: boolean;
+    /** The adapter's own distance functions are registered with the driver. */
+    udf: boolean;
+    /** `json_each()` is available, which the pure-SQL strategy needs. */
+    json1: boolean;
+}
+export interface SqliteVectorOptions {
+    /** Path to the sqlite-vec extension binary to load before probing. */
+    sqliteVec?: string | undefined;
+    /** Pin a strategy instead of probing for the fastest one available. */
+    vectorStrategy?: VectorStrategyPreference | undefined;
+}
+/**
+ * A driver hook the engine can supply to register the distance functions and
+ * load the sqlite-vec extension. Every field is optional: a driver that offers
+ * nothing simply reports no capabilities and the search falls back.
+ */
+/**
+ * Registers a scalar function with the driver. Implementations that take a
+ * determinism flag (better-sqlite3) supply it themselves.
+ */
+export type SqliteVectorFunctionRegistrar = (name: string, fn: (...args: any[]) => any) => void;
+export interface SqliteVectorHooks {
+    /** Raw driver handle, used for `loadExtension`. */
+    native?: () => any;
+    /** Register `name` with the driver's scalar-function API. */
+    registerFunction?: SqliteVectorFunctionRegistrar;
+}
+/**
+ * Resolve the ordered list of strategies to try for this connection.
+ *
+ * `declaredType` is the column's DDL type: the JSON strategy only reaches rows
+ * stored as text, so a `BLOB` column drops it from the order.
+ */
+export declare function planSqliteVectorStrategies(caps: SqliteVectorCapabilities, declaredType: string | null, preference?: VectorStrategyPreference): SqliteVectorStrategy[];
+/**
+ * Register `an5_vec_*` on a driver and load sqlite-vec when a path is configured.
+ * Safe to call repeatedly; each driver hook is used at most once.
+ */
+export declare class SqliteVectorSupport {
+    private readonly hooks;
+    private readonly options;
+    private caps;
+    /**
+     * Declared column types and the "any binary row" probe, keyed by column.
+     *
+     * Both cost a query, and neither changes while a schema is in use. A stale
+     * answer is still safe: the probe only decides which strategy to try first, and
+     * a strategy that fails falls through to the next one rather than reporting a
+     * wrong result.
+     */
+    private readonly columnTypes;
+    private readonly binaryRows;
+    constructor(hooks: SqliteVectorHooks, options?: SqliteVectorOptions);
+    capabilities(): Promise<SqliteVectorCapabilities>;
+    /** Confirms JSON1 and a usable sqlite-vec/UDF before a query is built for them. */
+    probe(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>): Promise<SqliteVectorCapabilities>;
+    /** The column's declared DDL type, remembered per column. */
+    columnType(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string): Promise<string | null>;
+    /**
+     * Whether any row stores raw bytes, which `json_each` cannot read.
+     *
+     * Checked only for the `sql` strategy, where a legacy JSON column that has
+     * since taken new float32 rows would otherwise rank just the old ones.
+     */
+    hasBinaryRows(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string, tail: string, params: Record<string, any>): Promise<boolean>;
+    reset(): void;
+}
+/** Reads a vector column's declared DDL type, or null when it cannot be found. */
+export declare function readSqliteColumnType(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string): Promise<string | null>;
+export interface SqliteVectorSearchArgs {
+    exec: (sql: string, params?: Record<string, any>) => Promise<any[]>;
+    /** Absent when the engine cannot register functions or load extensions. */
+    vectorSupport?: SqliteVectorSupport | null;
+    /** Quoted table reference, e.g. `[documents]`. */
+    table: string;
+    /** Unquoted table name, for `pragma_table_info`. */
+    rawTable: string;
+    /** Quoted column reference. */
+    column: string;
+    /** Unquoted column name. */
+    rawColumn: string;
+    vector: number[];
+    metric: VectorMetric;
+    take: number;
+    /** A WHERE tail (leading space included) or empty. */
+    tail?: string | undefined;
+    /** Parameter object shared with the caller's WHERE clause. */
+    params: Record<string, any>;
+    preference?: VectorStrategyPreference | undefined;
+}
+/**
+ * Rank a SQLite table by distance inside the database, trying each available
+ * strategy in order. Returns null when the connection offers none, so the
+ * caller can fall back to scoring in memory.
+ */
+export declare function runSqliteVectorSearch(args: SqliteVectorSearchArgs): Promise<{
+    rows: Record<string, any>[];
+    strategy: SqliteVectorStrategy;
+} | null>;
+export {};