/**
 * Vector Store Service — v2
 *
 * Local, on-device vector storage using SQLite (better-sqlite3) with optional
 * sqlite-vec extension for native KNN search. Falls back gracefully to
 * JavaScript cosine similarity when the extension is unavailable.
 *
 * v2 improvements over v1:
 * - Binary BLOB storage (Float32Array) instead of JSON TEXT (~4× smaller, faster)
 * - Optional sqlite-vec integration for native SQL-based KNN search (cosine metric)
 * - Dimension validation ensures all vectors in a scope share the same width
 * - Prepared statement caching for repeated operations
 * - Input sanitization (NaN, Infinity rejection)
 * - Batch upsert with transaction wrapping
 * - Automatic schema migration from v1 (JSON TEXT) databases
 *
 * Storage locations:
 * - Global scope: ~/.crewly/vector-store.db
 * - Project scope: {projectPath}/.crewly/vector-store.db
 *
 * @module services/knowledge/vector-store.service
 */
/** Reset the sqlite-vec loader state (for testing). */
export declare function resetSqliteVecLoader(): void;
/** Constants for the vector store */
export declare const VECTOR_STORE_CONSTANTS: {
    /** SQLite database filename */
    readonly DB_FILENAME: "vector-store.db";
    /** Default number of results for similarity search */
    readonly DEFAULT_SEARCH_LIMIT: 10;
    /** Minimum cosine similarity threshold for search results */
    readonly DEFAULT_SIMILARITY_THRESHOLD: 0.1;
    /** Maximum metadata JSON size (bytes) */
    readonly MAX_METADATA_SIZE: 65536;
    /** Current schema version */
    readonly SCHEMA_VERSION: 2;
    /** Maximum supported embedding dimensions */
    readonly MAX_DIMENSIONS: 4096;
    /** Maximum items in a single batch upsert */
    readonly MAX_BATCH_SIZE: 500;
};
/**
 * A stored embedding record with metadata.
 */
export interface VectorRecord {
    /** Unique identifier (typically document ID) */
    id: string;
    /** The embedding vector as a Float64 array */
    embedding: number[];
    /** Optional metadata associated with the embedding */
    metadata: Record<string, unknown>;
    /** ISO timestamp of when the embedding was stored */
    createdAt: string;
    /** ISO timestamp of last update */
    updatedAt: string;
}
/**
 * A search result with cosine similarity score.
 */
export interface VectorSearchResult {
    /** Unique identifier */
    id: string;
    /** Cosine similarity score (higher is more similar) */
    score: number;
    /** Associated metadata */
    metadata: Record<string, unknown>;
}
/**
 * Convert a number array to a Float32Array Buffer for efficient BLOB storage.
 *
 * @param embedding - The embedding vector
 * @returns Buffer containing the Float32Array binary data
 */
export declare function embeddingToBlob(embedding: number[]): Buffer;
/**
 * Convert a BLOB Buffer back to a number array.
 *
 * @param blob - Buffer containing Float32Array binary data
 * @returns The embedding as a number array
 */
export declare function blobToEmbedding(blob: Buffer): number[];
/**
 * Compute cosine similarity between two vectors.
 *
 * @param a - First vector
 * @param b - Second vector
 * @returns Cosine similarity in range [-1, 1], or 0 if vectors are incompatible
 */
export declare function cosineSimilarity(a: number[], b: number[]): number;
/**
 * Validate an embedding vector for storage. Rejects empty arrays, values
 * that are not finite numbers (NaN, Infinity), and dimensions exceeding
 * the maximum.
 *
 * @param embedding - The embedding to validate
 * @throws Error if the embedding is invalid
 */
export declare function validateEmbedding(embedding: number[]): void;
/**
 * VectorStoreService provides local SQLite-based vector storage with optional
 * native KNN search via the sqlite-vec extension.
 *
 * When sqlite-vec is available, search uses a `vec0` virtual table with cosine
 * distance metric for hardware-accelerated nearest-neighbor queries. When it is
 * not available, search falls back to JavaScript cosine similarity (fully
 * portable, no native extension required).
 *
 * Each scope (global / project) gets its own database file so project data
 * stays isolated and portable.
 *
 * @example
 * ```typescript
 * const store = VectorStoreService.getInstance();
 * store.upsert('doc-123', embedding, { title: 'My Doc' }, 'global');
 * const results = store.search(queryEmbedding, 'global');
 * console.log(store.isVecEnabled('global')); // true if sqlite-vec loaded
 * ```
 */
export declare class VectorStoreService {
    private static instance;
    private readonly logger;
    /** Cache of open database connections by resolved db path */
    private readonly databases;
    private constructor();
    /**
     * Get the singleton instance.
     *
     * @returns VectorStoreService instance
     */
    static getInstance(): VectorStoreService;
    /**
     * Reset the singleton and close all open databases (for testing).
     */
    static resetInstance(): void;
    /**
     * Resolve the database file path for a given scope.
     *
     * @param scope - 'global' or 'project'
     * @param projectPath - Required when scope is 'project'
     * @returns Absolute path to the SQLite database file
     * @throws Error if projectPath is missing for project scope
     */
    private dbPath;
    /**
     * Check whether the sqlite-vec native KNN search is available for a scope.
     *
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns true if vec0 virtual table is active
     */
    isVecEnabled(scope: 'global' | 'project', projectPath?: string): boolean;
    /**
     * Get (or prepare + cache) a statement for the given database state.
     *
     * @param state - Database state to prepare on
     * @param key - Unique cache key
     * @param sql - SQL to prepare if not yet cached
     * @returns A prepared Statement
     */
    private getStmt;
    /**
     * Open or retrieve a cached database connection. Creates the parent
     * directory, schema, and vec0 table (if sqlite-vec is available) on first
     * access. Handles automatic migration from v1 databases.
     *
     * @param scope - Document scope
     * @param projectPath - Project path for project-scoped databases
     * @returns Internal DatabaseState
     */
    private getDbState;
    /**
     * Migrate database schema to v2.
     * - Creates vec_config table for tracking schema version and dimensions
     * - Adds dimensions column if missing
     * - Converts JSON TEXT embeddings to BLOB if needed
     * - Creates vec0 virtual table if sqlite-vec is available and dimensions are known
     *
     * @param db - The database to migrate
     * @param vecEnabled - Whether sqlite-vec extension is loaded
     */
    private migrateSchema;
    /**
     * Create the vec0 virtual table if it doesn't already exist and dimensions
     * are known. Returns true if the table is ready for use.
     *
     * @param db - The database
     * @param dimensions - Explicit dimensions; if omitted, reads from vec_config
     * @returns true if vec0 table exists and is ready
     */
    private ensureVecTable;
    /**
     * Copy all existing embeddings matching the target dimensions into the vec0
     * virtual table.
     *
     * @param db - The database
     * @param dimensions - Target embedding dimensions
     */
    private backfillVecTable;
    /**
     * Read the stored embedding dimensions from the vec_config table.
     *
     * @param db - The database
     * @returns Stored dimensions, or null if not yet determined
     */
    private getStoredDimensions;
    /**
     * Close all open database connections and clear caches.
     */
    closeAll(): void;
    /**
     * Store or update an embedding for a document.
     *
     * @param id - Document identifier
     * @param embedding - The embedding vector (array of numbers)
     * @param metadata - Optional metadata to associate with the embedding
     * @param scope - Storage scope ('global' or 'project')
     * @param projectPath - Required when scope is 'project'
     * @throws Error if id is empty, embedding is invalid, metadata exceeds size,
     *         or dimensions don't match previously stored embeddings
     */
    upsert(id: string, embedding: number[], metadata: Record<string, unknown>, scope: 'global' | 'project', projectPath?: string): void;
    /**
     * Sync a single embedding to the vec0 virtual table.
     * Uses CAST(? AS INTEGER) for rowid because sqlite-vec's vec0 virtual
     * table does not accept JS number params directly for primary keys.
     *
     * @param state - Database state
     * @param id - Document identifier
     * @param blob - Embedding as a Float32Array buffer
     */
    private syncToVec;
    /**
     * Batch upsert multiple embeddings in a single transaction. Significantly
     * faster than individual upserts for bulk imports.
     *
     * @param items - Array of { id, embedding, metadata } objects
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns Count of succeeded and failed inserts
     * @throws Error if batch size exceeds MAX_BATCH_SIZE
     */
    batchUpsert(items: Array<{
        id: string;
        embedding: number[];
        metadata: Record<string, unknown>;
    }>, scope: 'global' | 'project', projectPath?: string): {
        succeeded: number;
        failed: number;
    };
    /**
     * Retrieve a stored embedding by document ID.
     *
     * @param id - Document identifier
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns The vector record, or null if not found
     */
    get(id: string, scope: 'global' | 'project', projectPath?: string): VectorRecord | null;
    /**
     * Delete an embedding by document ID.
     *
     * @param id - Document identifier
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns True if a record was deleted, false if not found
     */
    delete(id: string, scope: 'global' | 'project', projectPath?: string): boolean;
    /**
     * Check whether an embedding exists for a given document ID.
     *
     * @param id - Document identifier
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns True if the embedding exists
     */
    has(id: string, scope: 'global' | 'project', projectPath?: string): boolean;
    /**
     * Return the total number of stored embeddings.
     *
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns Count of stored embeddings
     */
    count(scope: 'global' | 'project', projectPath?: string): number;
    /**
     * Search for the most similar embeddings. Uses native vec0 KNN search when
     * sqlite-vec is available, otherwise falls back to JavaScript cosine
     * similarity.
     *
     * @param queryEmbedding - The query embedding vector
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @param limit - Maximum number of results (default 10)
     * @param threshold - Minimum similarity threshold (default 0.1)
     * @returns Matching records sorted by descending similarity
     */
    search(queryEmbedding: number[], scope: 'global' | 'project', projectPath?: string, limit?: number, threshold?: number): VectorSearchResult[];
    /**
     * Native KNN search using sqlite-vec's vec0 virtual table with cosine
     * distance metric. Results are converted from cosine distance (0 = identical,
     * 1 = orthogonal) to cosine similarity (1 = identical, 0 = orthogonal).
     *
     * @param state - Database state
     * @param queryEmbedding - The query vector
     * @param limit - Max results
     * @param threshold - Minimum cosine similarity
     * @returns Sorted search results
     */
    private vecSearch;
    /**
     * JavaScript fallback search using cosine similarity on BLOB embeddings.
     * Used when sqlite-vec is not available.
     *
     * @param state - Database state
     * @param queryEmbedding - The query vector
     * @param limit - Max results
     * @param threshold - Minimum cosine similarity
     * @returns Sorted search results
     */
    private jsFallbackSearch;
    /**
     * Delete all embeddings from the store. Also resets the stored dimension
     * constraint so that subsequent inserts may use a different embedding width.
     *
     * @param scope - Storage scope
     * @param projectPath - Required when scope is 'project'
     * @returns Number of records deleted
     */
    clear(scope: 'global' | 'project', projectPath?: string): number;
}
//# sourceMappingURL=vector-store.service.d.ts.map