import { SqliteConnection } from "./connection.js";
import { EmbeddingMetaRow } from "./embedding-meta-repo.js";

//#region src/vector-table-mgr.d.ts

/**
 * Lazy-creator for per-embedder `vec0` virtual tables. The first write
 * for `(entity, embedder_id)` creates the corresponding `*_vec_<slug>`
 * virtual table; subsequent writes hit the cached existence check.
 *
 * In `'linear-fallback'` mode (sqlite-vec unavailable +
 * `onMissingSqliteVec: 'linear-fallback'`) the same table names are
 * created as PLAIN tables (`<id> TEXT PRIMARY KEY, embedding BLOB`)
 * and KNN is served by {@link VectorTableManager.linearKnn} - a
 * batched in-process cosine scan with `setImmediate` yields. A
 * database must stay in one mode: opening vec0 tables in fallback mode
 * (or plain fallback tables in vec0 mode) throws an actionable error
 * at construction.
 *
 * @stable
 */
declare class VectorTableManager {
  #private;
  constructor(conn: SqliteConnection);
  /**
   * Ensures the per-embedder vector table for `kind` exists (vec0
   * virtual table, or a plain sidecar in linear-fallback mode).
   * Returns the concrete table name (which the caller uses in their
   * `INSERT INTO` + `SELECT` statements).
   *
   * @stable
   */
  ensureTable(kind: 'facts' | 'episodes' | 'messages', meta: EmbeddingMetaRow): string;
  /** Active vector-serving mode. */
  get mode(): 'vec0' | 'linear-fallback' | 'disabled';
  /**
   * In-process cosine KNN over a plain fallback sidecar:
   * scans the table in batches of `batchSize` rows, yielding to the
   * event loop between batches (`setImmediate`) so a large scan cannot
   * monopolise it, and keeps the `k` nearest by cosine distance
   * (`1 - cos`, the same scale vec0 reports for its cosine metric).
   *
   * @stable
   */
  linearKnn(tableName: string, idColumn: string, query: Float32Array, k: number, batchSize?: number): Promise<ReadonlyArray<{
    readonly id: string;
    readonly distance: number;
  }>>;
  /** @internal */
  knownTables(): readonly string[];
  /** @internal - drop a table this manager tracks (space reclaim). */
  dropTable(tableName: string): void;
}
//#endregion
export { VectorTableManager };
//# sourceMappingURL=vector-table-mgr.d.ts.map