kiokuko 1.0.0

package/dist/db/sqlite-retry.d.ts

@@ -0,0 +1,11 @@
+/** Match only node:sqlite errors whose SQLite primary result code is BUSY or LOCKED. */
+export declare function isSqliteLockError(error: unknown): boolean;
+/** Match only native node:sqlite operational failures discovery may safely report as bounded degradation. */
+export declare function isSqliteOperationalError(error: unknown): boolean;
+/** Match database bytes that SQLite itself reports as corrupt or not a database. */
+export declare function isSqliteCorruptionError(error: unknown): boolean;
+/** Match one exact PRIMARY KEY/UNIQUE target; trigger text cannot spoof this check. */
+export declare function isSqliteUniqueConstraintError(error: unknown, targets: readonly string[]): boolean;
+/** Retry a synchronous operation at most five total attempts, and only for SQLite BUSY/LOCKED. */
+export declare function withSqliteLockRetry<T>(operation: () => T): T;
+//# sourceMappingURL=sqlite-retry.d.ts.map

package/dist/db/sqlite-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-retry.d.ts","sourceRoot":"","sources":["../../src/db/sqlite-retry.ts"],"names":[],"mappings":"AAyBA,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED,6GAA6G;AAC7G,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/D;AAED,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIjG;AAOD,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAgB5D"}

package/dist/db/sqlite-retry.js

@@ -0,0 +1,70 @@
+import { KiokukoError } from '../errors.js';
+const LOCK_ATTEMPT_LIMIT = 5;
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+const SQLITE_CONSTRAINT_PRIMARYKEY = 1555;
+const SQLITE_CONSTRAINT_UNIQUE = 2067;
+const SQLITE_OPERATIONAL_CODES = new Set([SQLITE_BUSY, SQLITE_LOCKED, 8, 10, 13, 14]);
+function sqliteErrorCode(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const sqliteError = error;
+    if (sqliteError.code !== 'ERR_SQLITE_ERROR'
+        || typeof sqliteError.errcode !== 'number'
+        || !Number.isSafeInteger(sqliteError.errcode)
+        || sqliteError.errcode < 0) {
+        return undefined;
+    }
+    return sqliteError.errcode;
+}
+/** Match only node:sqlite errors whose SQLite primary result code is BUSY or LOCKED. */
+export function isSqliteLockError(error) {
+    const code = sqliteErrorCode(error);
+    if (code === undefined)
+        return false;
+    const primaryResultCode = code & 0xff;
+    return primaryResultCode === SQLITE_BUSY || primaryResultCode === SQLITE_LOCKED;
+}
+/** Match only native node:sqlite operational failures discovery may safely report as bounded degradation. */
+export function isSqliteOperationalError(error) {
+    const code = sqliteErrorCode(error);
+    return code !== undefined && SQLITE_OPERATIONAL_CODES.has(code & 0xff);
+}
+/** Match database bytes that SQLite itself reports as corrupt or not a database. */
+export function isSqliteCorruptionError(error) {
+    const code = sqliteErrorCode(error);
+    if (code === undefined)
+        return false;
+    const primaryResultCode = code & 0xff;
+    return primaryResultCode === SQLITE_CORRUPT || primaryResultCode === SQLITE_NOTADB;
+}
+/** Match one exact PRIMARY KEY/UNIQUE target; trigger text cannot spoof this check. */
+export function isSqliteUniqueConstraintError(error, targets) {
+    const code = sqliteErrorCode(error);
+    if (code !== SQLITE_CONSTRAINT_PRIMARYKEY && code !== SQLITE_CONSTRAINT_UNIQUE)
+        return false;
+    return error instanceof Error && targets.some((target) => error.message === `UNIQUE constraint failed: ${target}`);
+}
+function waitForRetry(attempt) {
+    const buffer = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buffer, 0, 0, attempt * 25);
+}
+/** Retry a synchronous operation at most five total attempts, and only for SQLite BUSY/LOCKED. */
+export function withSqliteLockRetry(operation) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!isSqliteLockError(error))
+                throw error;
+            if (attempt >= LOCK_ATTEMPT_LIMIT) {
+                throw new KiokukoError('BACKPRESSURE', 'SQLite remained busy after bounded retry', { retryAfterSeconds: 1 });
+            }
+            waitForRetry(attempt);
+        }
+    }
+}
+//# sourceMappingURL=sqlite-retry.js.map

package/dist/db/sqlite-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-retry.js","sourceRoot":"","sources":["../../src/db/sqlite-retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAC7B,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAC1C,MAAM,wBAAwB,GAAG,IAAI,CAAC;AACtC,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAEtF,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,WAAW,GAAG,KAAsD,CAAC;IAC3E,IACE,WAAW,CAAC,IAAI,KAAK,kBAAkB;WACpC,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ;WACvC,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,OAAO,CAAC;WAC1C,WAAW,CAAC,OAAO,GAAG,CAAC,EAC1B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,WAAW,CAAC,OAAO,CAAC;AAC7B,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IACtC,OAAO,iBAAiB,KAAK,WAAW,IAAI,iBAAiB,KAAK,aAAa,CAAC;AAClF,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,IAAI,KAAK,SAAS,IAAI,wBAAwB,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IACtC,OAAO,iBAAiB,KAAK,cAAc,IAAI,iBAAiB,KAAK,aAAa,CAAC;AACrF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,6BAA6B,CAAC,KAAc,EAAE,OAA0B;IACtF,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,4BAA4B,IAAI,IAAI,KAAK,wBAAwB;QAAE,OAAO,KAAK,CAAC;IAC7F,OAAO,KAAK,YAAY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,6BAA6B,MAAM,EAAE,CAAC,CAAC;AACrH,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,mBAAmB,CAAI,SAAkB;IACvD,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,SAAS,EAAE,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC3C,IAAI,OAAO,IAAI,kBAAkB,EAAE,CAAC;gBAClC,MAAM,IAAI,YAAY,CACpB,cAAc,EACd,0CAA0C,EAC1C,EAAE,iBAAiB,EAAE,CAAC,EAAE,CACzB,CAAC;YACJ,CAAC;YACD,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/db/transaction.d.ts

@@ -0,0 +1,17 @@
+import type { SqliteDatabase } from './adapter.js';
+/**
+ * COMMIT threw and the subsequent ROLLBACK also threw. The caller must treat
+ * the transaction as possibly committed: compensating durable side effects
+ * could otherwise turn an uncertain outcome into split-brain state.
+ */
+export declare class TransactionCommitUncertainError extends AggregateError {
+    readonly commitError: unknown;
+    readonly rollbackError: unknown;
+    constructor(commitError: unknown, rollbackError: unknown);
+}
+export declare function rollbackFailedTransaction(database: SqliteDatabase, operationError: unknown): never;
+/** Run a synchronous write transaction with bounded retry for SQLite lock errors only. */
+export declare function withImmediateTransaction<T>(database: SqliteDatabase, operation: () => T): T;
+/** Run synchronous reads against one SQLite snapshot without reserving a writer lock. */
+export declare function withDeferredReadTransaction<T>(database: SqliteDatabase, operation: () => T): T;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/db/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;GAIG;AACH,qBAAa,+BAAgC,SAAQ,cAAc;IACjE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO;CASzD;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,GAAG,KAAK,CAUlG;AAeD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAY3F;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAU9F"}

package/dist/db/transaction.js

@@ -0,0 +1,68 @@
+import { withSqliteLockRetry } from './sqlite-retry.js';
+/**
+ * COMMIT threw and the subsequent ROLLBACK also threw. The caller must treat
+ * the transaction as possibly committed: compensating durable side effects
+ * could otherwise turn an uncertain outcome into split-brain state.
+ */
+export class TransactionCommitUncertainError extends AggregateError {
+    commitError;
+    rollbackError;
+    constructor(commitError, rollbackError) {
+        super([commitError, rollbackError], 'Transaction commit outcome is uncertain because commit and rollback both failed');
+        this.name = 'TransactionCommitUncertainError';
+        this.commitError = commitError;
+        this.rollbackError = rollbackError;
+    }
+}
+export function rollbackFailedTransaction(database, operationError) {
+    try {
+        database.exec('ROLLBACK');
+    }
+    catch (rollbackError) {
+        throw new AggregateError([operationError, rollbackError], 'Transaction operation failed and rollback also failed');
+    }
+    throw operationError;
+}
+function commitOrRollback(database) {
+    try {
+        database.exec('COMMIT');
+    }
+    catch (commitError) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch (rollbackError) {
+            throw new TransactionCommitUncertainError(commitError, rollbackError);
+        }
+        throw commitError;
+    }
+}
+/** Run a synchronous write transaction with bounded retry for SQLite lock errors only. */
+export function withImmediateTransaction(database, operation) {
+    return withSqliteLockRetry(() => {
+        database.exec('BEGIN IMMEDIATE');
+        let result;
+        try {
+            result = operation();
+        }
+        catch (error) {
+            rollbackFailedTransaction(database, error);
+        }
+        commitOrRollback(database);
+        return result;
+    });
+}
+/** Run synchronous reads against one SQLite snapshot without reserving a writer lock. */
+export function withDeferredReadTransaction(database, operation) {
+    database.exec('BEGIN DEFERRED');
+    let result;
+    try {
+        result = operation();
+    }
+    catch (error) {
+        rollbackFailedTransaction(database, error);
+    }
+    commitOrRollback(database);
+    return result;
+}
+//# sourceMappingURL=transaction.js.map

package/dist/db/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,OAAO,+BAAgC,SAAQ,cAAc;IACxD,WAAW,CAAU;IACrB,aAAa,CAAU;IAEhC,YAAY,WAAoB,EAAE,aAAsB;QACtD,KAAK,CACH,CAAC,WAAW,EAAE,aAAa,CAAC,EAC5B,iFAAiF,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CAAC,QAAwB,EAAE,cAAuB;IACzF,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,aAAa,EAAE,CAAC;QACvB,MAAM,IAAI,cAAc,CACtB,CAAC,cAAc,EAAE,aAAa,CAAC,EAC/B,uDAAuD,CACxD,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,CAAC;AACvB,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAwB;IAChD,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,WAAW,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,+BAA+B,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,WAAW,CAAC;IACpB,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAI,QAAwB,EAAE,SAAkB;IACtF,OAAO,mBAAmB,CAAC,GAAG,EAAE;QAC9B,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACjC,IAAI,MAAS,CAAC;QACd,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,EAAE,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,2BAA2B,CAAI,QAAwB,EAAE,SAAkB;IACzF,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAChC,IAAI,MAAS,CAAC;IACd,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IACD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/embedding/backend.d.ts

@@ -0,0 +1,27 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import { type ConnectionOptions } from '../db/connection.js';
+import { KiokukoError } from '../errors.js';
+import { type SqliteVecLoader } from './sqlite-vec-loader.js';
+import type { EmbeddingConfig, VectorSearchBackend } from './types.js';
+export type EmbeddingDatabaseOpener = (databasePath: string, options?: ConnectionOptions) => SqliteDatabase | PromiseLike<SqliteDatabase>;
+export interface OpenEmbeddingDatabaseOptions {
+    readonly config?: EmbeddingConfig;
+    readonly openDatabase?: EmbeddingDatabaseOpener;
+    readonly createLoader?: () => Promise<SqliteVecLoader | null>;
+    readonly backend?: VectorSearchBackend;
+}
+export interface OpenEmbeddingDatabaseResult {
+    readonly database: SqliteDatabase;
+    readonly backend: VectorSearchBackend | undefined;
+}
+/** A forced backend could not be selected; doctor may convert this to a finding. */
+export declare class EmbeddingBackendUnavailableError extends KiokukoError {
+    constructor();
+}
+/**
+ * Open one owned database connection and select the backend that is actually
+ * usable on that connection. Only the package-owned sqlite-vec loader can
+ * create an extension-enabled connection.
+ */
+export declare function openEmbeddingDatabase(databasePath: string, options: OpenEmbeddingDatabaseOptions): Promise<OpenEmbeddingDatabaseResult>;
+//# sourceMappingURL=backend.d.ts.map

package/dist/embedding/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/embedding/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAsC,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGrF,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,MAAM,uBAAuB,GAAG,CACpC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,iBAAiB,KACxB,cAAc,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;AAElD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACnD;AAED,oFAAoF;AACpF,qBAAa,gCAAiC,SAAQ,YAAY;;CAKjE;AAMD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC"}

package/dist/embedding/backend.js

@@ -0,0 +1,67 @@
+import { openConnection, SqliteVecLoadError } from '../db/connection.js';
+import { KiokukoError } from '../errors.js';
+import { JavaScriptVectorSearchBackend } from './javascript-backend.js';
+import { createSqliteVecLoader } from './sqlite-vec-loader.js';
+import { SqliteVecVectorSearchBackend } from './sqlite-vec-backend.js';
+import { defaultEmbeddingConfig, readPersistedEmbeddingSettings } from './settings.js';
+/** A forced backend could not be selected; doctor may convert this to a finding. */
+export class EmbeddingBackendUnavailableError extends KiokukoError {
+    constructor() {
+        super('SERVICE_UNAVAILABLE', 'The configured sqlite-vec backend is unavailable');
+        this.name = 'EmbeddingBackendUnavailableError';
+    }
+}
+function forcedSqliteVecUnavailable() {
+    throw new EmbeddingBackendUnavailableError();
+}
+/**
+ * Open one owned database connection and select the backend that is actually
+ * usable on that connection. Only the package-owned sqlite-vec loader can
+ * create an extension-enabled connection.
+ */
+export async function openEmbeddingDatabase(databasePath, options) {
+    const openDatabase = options.openDatabase ?? openConnection;
+    if (options.backend !== undefined) {
+        return { database: await openDatabase(databasePath), backend: options.backend };
+    }
+    let config = options.config;
+    if (config === undefined) {
+        const probe = await openDatabase(databasePath);
+        try {
+            try {
+                config = readPersistedEmbeddingSettings(probe);
+            }
+            catch {
+                config = defaultEmbeddingConfig();
+            }
+        }
+        finally {
+            probe.close();
+        }
+    }
+    if (config.mode === 'off') {
+        return { database: await openDatabase(databasePath), backend: undefined };
+    }
+    const javascriptBackend = new JavaScriptVectorSearchBackend();
+    if (config.vectorBackend === 'javascript') {
+        return { database: await openDatabase(databasePath), backend: javascriptBackend };
+    }
+    const loader = await (options.createLoader ?? createSqliteVecLoader)();
+    if (loader === null) {
+        if (config.vectorBackend === 'sqlite-vec')
+            forcedSqliteVecUnavailable();
+        return { database: await openDatabase(databasePath), backend: javascriptBackend };
+    }
+    try {
+        const database = await openDatabase(databasePath, { sqliteVecLoader: loader });
+        return { database, backend: new SqliteVecVectorSearchBackend() };
+    }
+    catch (error) {
+        if (!(error instanceof SqliteVecLoadError))
+            throw error;
+        if (config.vectorBackend === 'sqlite-vec')
+            forcedSqliteVecUnavailable();
+        return { database: await openDatabase(databasePath), backend: javascriptBackend };
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/embedding/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/embedding/backend.ts"],"names":[],"mappings":"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"}

package/dist/embedding/config.d.ts

@@ -0,0 +1,7 @@
+import type { EmbeddingConfig, EnabledEmbeddingConfig } from './types.js';
+/** Normalize and validate an embedding endpoint without retaining credentials. */
+export declare function normalizeEmbeddingBaseUrl(value: string, allowRemote: boolean): string;
+export declare function isEnabledEmbeddingConfig(config: EmbeddingConfig): config is EnabledEmbeddingConfig;
+export declare function requireEnabledEmbeddingConfig(config: EmbeddingConfig): EnabledEmbeddingConfig;
+export declare function parseEmbeddingConfig(environment?: NodeJS.ProcessEnv): EmbeddingConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/embedding/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/embedding/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAwC,sBAAsB,EAA2B,MAAM,YAAY,CAAC;AAwDzI,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAoBrF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,IAAI,sBAAsB,CAMlG;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,eAAe,GAAG,sBAAsB,CAG7F;AAED,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CAgClG"}

package/dist/embedding/config.js

@@ -0,0 +1,125 @@
+import { KiokukoError } from '../errors.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_BATCH_SIZE = 16;
+const MAX_MODEL_LENGTH = 256;
+const MAX_API_KEY_LENGTH = 4_096;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+function invalid(message) {
+    throw new KiokukoError('VALIDATION_ERROR', message);
+}
+function enumValue(value, fallback, allowed, field) {
+    const selected = value === undefined ? fallback : value;
+    if (!allowed.includes(selected))
+        invalid(`${field} has an unsupported value`);
+    return selected;
+}
+function boundedText(value, field, maxLength) {
+    const normalized = value.normalize('NFKC').trim();
+    if (normalized.length === 0 || normalized.length > maxLength || /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        invalid(`${field} is invalid`);
+    }
+    return normalized;
+}
+function optionalText(value, field, maxLength) {
+    return value === undefined || value.length === 0 ? undefined : boundedText(value, field, maxLength);
+}
+function integerValue(value, fallback, minimum, maximum, field) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d+$/u.test(value))
+        invalid(`${field} must be an integer in the supported range`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+        invalid(`${field} must be an integer in the supported range`);
+    }
+    return parsed;
+}
+function distanceCeilingValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^(?:\d+\.?\d*|\.\d+)$/u.test(value))
+        invalid('KIOKUKO_EMBEDDING_DISTANCE_CEILING is invalid');
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed >= 2) {
+        invalid('KIOKUKO_EMBEDDING_DISTANCE_CEILING is invalid');
+    }
+    return parsed;
+}
+function booleanValue(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (value !== 'true' && value !== 'false')
+        invalid(`${field} must be true or false`);
+    return value === 'true';
+}
+/** Normalize and validate an embedding endpoint without retaining credentials. */
+export function normalizeEmbeddingBaseUrl(value, allowRemote) {
+    const input = boundedText(value, 'KIOKUKO_EMBEDDING_BASE_URL', 2_048);
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        invalid('KIOKUKO_EMBEDDING_BASE_URL must be an absolute URL');
+    }
+    if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {
+        invalid('KIOKUKO_EMBEDDING_BASE_URL must not contain credentials, query, or fragment data');
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/gu, '').toLowerCase();
+    if (url.protocol === 'http:') {
+        if (!LOOPBACK_HOSTS.has(hostname))
+            invalid('HTTP embedding endpoints must use a loopback host');
+    }
+    else if (url.protocol === 'https:') {
+        if (!allowRemote)
+            invalid('HTTPS embedding endpoints require explicit remote opt-in');
+    }
+    else {
+        invalid('KIOKUKO_EMBEDDING_BASE_URL must use HTTP or HTTPS');
+    }
+    return url.toString();
+}
+export function isEnabledEmbeddingConfig(config) {
+    return config.mode !== 'off'
+        && config.baseUrl !== undefined
+        && config.model !== undefined
+        && config.dimensions !== undefined
+        && config.distanceCeiling !== undefined;
+}
+export function requireEnabledEmbeddingConfig(config) {
+    if (!isEnabledEmbeddingConfig(config))
+        invalid('Embedding configuration is disabled or incomplete');
+    return config;
+}
+export function parseEmbeddingConfig(environment = process.env) {
+    const mode = enumValue(environment.KIOKUKO_EMBEDDINGS, 'off', ['off', 'optional', 'required'], 'KIOKUKO_EMBEDDINGS');
+    const provider = enumValue(environment.KIOKUKO_EMBEDDING_PROVIDER, 'openai-compatible', ['openai-compatible'], 'KIOKUKO_EMBEDDING_PROVIDER');
+    const allowRemote = booleanValue(environment.KIOKUKO_EMBEDDING_ALLOW_REMOTE, false, 'KIOKUKO_EMBEDDING_ALLOW_REMOTE');
+    const vectorBackend = enumValue(environment.KIOKUKO_VECTOR_BACKEND, 'auto', ['auto', 'javascript', 'sqlite-vec'], 'KIOKUKO_VECTOR_BACKEND');
+    const baseUrl = environment.KIOKUKO_EMBEDDING_BASE_URL === undefined
+        ? undefined
+        : normalizeEmbeddingBaseUrl(environment.KIOKUKO_EMBEDDING_BASE_URL, allowRemote);
+    const model = optionalText(environment.KIOKUKO_EMBEDDING_MODEL, 'KIOKUKO_EMBEDDING_MODEL', MAX_MODEL_LENGTH);
+    const dimensions = integerValue(environment.KIOKUKO_EMBEDDING_DIMENSIONS, 0, 2, 8_192, 'KIOKUKO_EMBEDDING_DIMENSIONS');
+    const configuredDistanceCeiling = distanceCeilingValue(environment.KIOKUKO_EMBEDDING_DISTANCE_CEILING);
+    const timeoutMs = integerValue(environment.KIOKUKO_EMBEDDING_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 120_000, 'KIOKUKO_EMBEDDING_TIMEOUT_MS');
+    const batchSize = integerValue(environment.KIOKUKO_EMBEDDING_BATCH_SIZE, DEFAULT_BATCH_SIZE, 1, 64, 'KIOKUKO_EMBEDDING_BATCH_SIZE');
+    const apiKey = optionalText(environment.KIOKUKO_EMBEDDING_API_KEY, 'KIOKUKO_EMBEDDING_API_KEY', MAX_API_KEY_LENGTH);
+    if (mode !== 'off' && (baseUrl === undefined || model === undefined || dimensions === 0 || configuredDistanceCeiling === undefined)) {
+        invalid('Enabled embeddings require base URL, model, dimensions, and distance ceiling');
+    }
+    return {
+        mode,
+        provider,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        ...(model === undefined ? {} : { model }),
+        ...(dimensions === 0 ? {} : { dimensions }),
+        ...(configuredDistanceCeiling === undefined ? {} : { distanceCeiling: configuredDistanceCeiling }),
+        ...(apiKey === undefined ? {} : { apiKey }),
+        allowRemote,
+        vectorBackend,
+        timeoutMs,
+        batchSize,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/embedding/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/embedding/config.ts"],"names":[],"mappings":"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"}

package/dist/embedding/diagnostics.d.ts

@@ -0,0 +1,34 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import type { EmbeddingConfig, EmbeddingMode, VectorSearchBackend } from './types.js';
+export interface EmbeddingStatus {
+    readonly mode: EmbeddingMode;
+    readonly activeProfileId: string | null;
+    readonly providerKind: string | null;
+    readonly model: string | null;
+    readonly dimensions: number | null;
+    readonly distanceMetric: string | null;
+    readonly distanceCeiling: number | null;
+    readonly backend: string | null;
+    readonly backendVersion: string | null;
+    readonly eligibleEntries: number;
+    readonly readyVectors: number;
+    readonly staleVectors: number;
+    readonly missingVectors: number;
+    readonly pendingJobs: number;
+    readonly leasedJobs: number;
+    readonly failedJobs: number;
+    readonly blockedJobs: number;
+    readonly coverageRatio: number;
+    readonly queryCacheRows: number;
+}
+export interface EmbeddingHealth {
+    readonly status: EmbeddingStatus;
+    readonly check: {
+        readonly ok: boolean;
+        readonly count: number;
+        readonly detail: string;
+    };
+}
+export declare function readEmbeddingStatus(database: SqliteDatabase, config?: EmbeddingConfig, backend?: VectorSearchBackend): EmbeddingStatus;
+export declare function inspectEmbeddingHealth(database: SqliteDatabase, environment?: NodeJS.ProcessEnv | EmbeddingConfig, backend?: VectorSearchBackend): EmbeddingHealth;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/embedding/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/embedding/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,kBAAkB,CAAC;AAMlE,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAoB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAiBxG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;QACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA+GD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EACxB,MAAM,GAAE,eAA0D,EAClE,OAAO,CAAC,EAAE,mBAAmB,GAC5B,eAAe,CAOjB;AAwGD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,WAAW,GAAE,MAAM,CAAC,UAAU,GAAG,eAA0D,EAC3F,OAAO,CAAC,EAAE,mBAAmB,GAC5B,eAAe,CAmDjB"}