@skillsmith/core 0.5.6 → 0.5.8

package/dist/embeddings/hnsw-store.d.ts

@@ -1,72 +0,0 @@
-/**
- * SMI-1519: HNSW Embedding Store
- *
- * High-performance vector storage using HNSW index for fast ANN search.
- * Uses brute-force search (V3 VectorDB unavailable after claude-flow rename).
- *
- * Enable via: SKILLSMITH_USE_HNSW=true
- * @see ADR-009: Embedding Service Fallback Strategy
- */
-import type { SimilarityResult } from './index.js';
-export type { HierarchicalNSW, HNSWSearchResult, HierarchicalNSWConstructor, HNSWConfig, HNSWEmbeddingStoreOptions, HNSWIndexStats, BatchInsertResult, IEmbeddingStore, } from './hnsw-store.types.js';
-export { DEFAULT_HNSW_CONFIG, HNSW_PRESETS } from './hnsw-store.types.js';
-export { createHNSWStore, isHNSWAvailable, loadHNSWLib } from './hnsw-store.helpers.js';
-import type { HNSWConfig, HNSWEmbeddingStoreOptions, HNSWIndexStats, BatchInsertResult, IEmbeddingStore } from './hnsw-store.types.js';
-/**
- * High-performance embedding storage using HNSW index.
- * Provides O(log n) approximate nearest neighbor search with SQLite persistence.
- */
-export declare class HNSWEmbeddingStore implements IEmbeddingStore {
-    private db;
-    private index;
-    private readonly hnswEnabled;
-    private readonly config;
-    private readonly maxElements;
-    private readonly indexPath;
-    private readonly distanceMetric;
-    private readonly autoSave;
-    private skillIdToLabel;
-    private labelToSkillId;
-    private nextLabel;
-    private vectorDB;
-    private initPromise;
-    /**
-     * @deprecated If dbPath is passed, use HNSWEmbeddingStore.create(options) instead —
-     * the async factory supports both native and WASM SQLite. Passing dbPath to this
-     * constructor throws to prevent silent data loss.
-     */
-    constructor(options?: HNSWEmbeddingStoreOptions);
-    /**
-     * Async factory — supports both native and WASM SQLite.
-     *
-     * @param options - Store options; dbPath is opened via createDatabaseAsync
-     * @returns Fully initialised HNSWEmbeddingStore instance
-     */
-    static create(options?: HNSWEmbeddingStoreOptions): Promise<HNSWEmbeddingStore>;
-    ensureInitialized(): Promise<void>;
-    storeEmbedding(skillId: string, embedding: Float32Array, text: string): void;
-    getEmbedding(skillId: string): Float32Array | null;
-    getAllEmbeddings(): Map<string, Float32Array>;
-    findSimilar(queryEmbedding: Float32Array, topK?: number): SimilarityResult[];
-    findSimilarAsync(queryEmbedding: Float32Array, topK?: number): Promise<SimilarityResult[]>;
-    cosineSimilarity(a: Float32Array, b: Float32Array): number;
-    isUsingFallback(): boolean;
-    close(): void;
-    getStats(): HNSWIndexStats;
-    batchInsert(embeddings: Array<{
-        skillId: string;
-        embedding: Float32Array;
-        text: string;
-    }>): BatchInsertResult;
-    removeEmbedding(skillId: string): boolean;
-    saveIndex(): void;
-    loadIndex(): void;
-    rebuildIndex(newConfig?: Partial<HNSWConfig>): Promise<void>;
-    setEfSearch(efSearch: number): void;
-    private initDatabase;
-    private initDatabaseAsync;
-    private initEmbeddingsTable;
-    private initHNSWIndex;
-    private distanceToSimilarity;
-}
-//# sourceMappingURL=hnsw-store.d.ts.map

package/dist/embeddings/hnsw-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hnsw-store.d.ts","sourceRoot":"","sources":["../../src/embeddings/hnsw-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAMlD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,UAAU,EACV,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGzE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAGvF,OAAO,KAAK,EACV,UAAU,EACV,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,eAAe,EAEhB,MAAM,uBAAuB,CAAA;AAI9B;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAA6B;IAEhD;;;;OAIG;gBACS,OAAO,GAAE,yBAA8B;IAqBnD;;;;;OAKG;WACU,MAAM,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAUnF,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAsB5E,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAalD,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC;IAiB7C,WAAW,CAAC,cAAc,EAAE,YAAY,EAAE,IAAI,GAAE,MAAW,GAAG,gBAAgB,EAAE;IA0B1E,gBAAgB,CACpB,cAAc,EAAE,YAAY,EAC5B,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB9B,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;IAgB1D,eAAe,IAAI,OAAO;IAI1B,KAAK,IAAI,IAAI;IAOb,QAAQ,IAAI,cAAc;IA4B1B,WAAW,CACT,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5E,iBAAiB;IAqDpB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAmBzC,SAAS,IAAI,IAAI;IAKjB,SAAS,IAAI,IAAI;IAKX,YAAY,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOnC,OAAO,CAAC,YAAY;YAKN,iBAAiB;IAK/B,OAAO,CAAC,mBAAmB;YAYb,aAAa;IAM3B,OAAO,CAAC,oBAAoB;CAI7B"}

package/dist/embeddings/hnsw-store.helpers.d.ts

@@ -1,83 +0,0 @@
-/**
- * HNSW Embedding Store Helper Functions
- * @module @skillsmith/core/embeddings/hnsw-store.helpers
- */
-import type { HierarchicalNSWConstructor, HNSWEmbeddingStoreOptions } from './hnsw-store.types.js';
-import { HNSW_PRESETS } from './hnsw-store.types.js';
-import { HNSWEmbeddingStore } from './hnsw-store.js';
-/**
- * Create an HNSWEmbeddingStore with a preset configuration.
- *
- * @param preset - Preset name ('small', 'medium', 'large', 'xlarge')
- * @param options - Additional options (merged with preset); dbPath is opened async
- * @returns Promise resolving to a configured HNSWEmbeddingStore instance
- *
- * @example
- * ```typescript
- * const store = await createHNSWStore('large', {
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- * });
- * ```
- */
-export declare function createHNSWStore(preset: keyof typeof HNSW_PRESETS, options?: Omit<HNSWEmbeddingStoreOptions, 'hnswConfig'>): Promise<HNSWEmbeddingStore>;
-/**
- * Check if hnswlib-node is available.
- * Useful for conditional logic or graceful degradation.
- *
- * @returns true if hnswlib-node can be loaded
- */
-export declare function isHNSWAvailable(): Promise<boolean>;
-/**
- * Dynamically load hnswlib-node module.
- *
- * @returns The HierarchicalNSW constructor, or null if unavailable
- * @internal
- */
-export declare function loadHNSWLib(): Promise<{
-    HierarchicalNSW: HierarchicalNSWConstructor;
-} | null>;
-/**
- * Compute cosine similarity between two embeddings.
- * Standalone version for use outside of HNSWEmbeddingStore.
- *
- * @param a - First embedding
- * @param b - Second embedding
- * @returns Similarity score between -1 and 1
- */
-export declare function computeCosineSimilarity(a: Float32Array, b: Float32Array): number;
-/**
- * Convert HNSW distance to similarity score.
- * HNSW returns distances, we need similarities (higher = more similar).
- *
- * @param distance - Distance value from HNSW
- * @param metric - Distance metric used
- * @returns Similarity score
- */
-export declare function distanceToSimilarity(distance: number, metric?: 'cosine' | 'l2' | 'ip'): number;
-/**
- * Estimate memory usage for an HNSW index.
- *
- * @param vectorCount - Number of vectors
- * @param dimensions - Vector dimensionality
- * @param m - HNSW M parameter
- * @returns Estimated memory usage in bytes
- */
-export declare function estimateMemoryUsage(vectorCount: number, dimensions: number, m: number): number;
-/**
- * Validate embedding dimensions.
- *
- * @param embedding - Embedding to validate
- * @param expectedDimensions - Expected dimension count
- * @param context - Context for error message (default: 'Query')
- * @throws Error if dimensions don't match
- */
-export declare function validateDimensions(embedding: Float32Array, expectedDimensions: number, context?: string): void;
-/**
- * Determine whether to use HNSW based on explicit option or environment.
- *
- * @param explicit - Explicit useHNSW option (if provided)
- * @returns Whether to enable HNSW
- */
-export declare function shouldUseHNSW(explicit?: boolean): boolean;
-//# sourceMappingURL=hnsw-store.helpers.d.ts.map

package/dist/embeddings/hnsw-store.helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hnsw-store.helpers.d.ts","sourceRoot":"","sources":["../../src/embeddings/hnsw-store.helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAMpD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,OAAO,YAAY,EACjC,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAM,GAC1D,OAAO,CAAC,kBAAkB,CAAC,CAK7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAOxD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,eAAe,EAAE,0BAA0B,CAAA;CAC5C,GAAG,IAAI,CAAC,CASR;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,QAAQ,GAAG,IAAI,GAAG,IAAe,GACxC,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,YAAY,EACvB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,GAAE,MAAgB,GACxB,IAAI,CAMN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAYzD"}

package/dist/embeddings/hnsw-store.helpers.js

@@ -1,147 +0,0 @@
-/**
- * HNSW Embedding Store Helper Functions
- * @module @skillsmith/core/embeddings/hnsw-store.helpers
- */
-import { HNSW_PRESETS } from './hnsw-store.types.js';
-import { HNSWEmbeddingStore } from './hnsw-store.js';
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Create an HNSWEmbeddingStore with a preset configuration.
- *
- * @param preset - Preset name ('small', 'medium', 'large', 'xlarge')
- * @param options - Additional options (merged with preset); dbPath is opened async
- * @returns Promise resolving to a configured HNSWEmbeddingStore instance
- *
- * @example
- * ```typescript
- * const store = await createHNSWStore('large', {
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- * });
- * ```
- */
-export async function createHNSWStore(preset, options = {}) {
-    return HNSWEmbeddingStore.create({
-        ...options,
-        hnswConfig: HNSW_PRESETS[preset],
-    });
-}
-/**
- * Check if hnswlib-node is available.
- * Useful for conditional logic or graceful degradation.
- *
- * @returns true if hnswlib-node can be loaded
- */
-export async function isHNSWAvailable() {
-    try {
-        await Function('return import("hnswlib-node")')();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Dynamically load hnswlib-node module.
- *
- * @returns The HierarchicalNSW constructor, or null if unavailable
- * @internal
- */
-export async function loadHNSWLib() {
-    try {
-        const mod = await Function('return import("hnswlib-node")')();
-        return mod;
-    }
-    catch {
-        return null;
-    }
-}
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * Compute cosine similarity between two embeddings.
- * Standalone version for use outside of HNSWEmbeddingStore.
- *
- * @param a - First embedding
- * @param b - Second embedding
- * @returns Similarity score between -1 and 1
- */
-export function computeCosineSimilarity(a, b) {
-    if (a.length !== b.length) {
-        throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}`);
-    }
-    let dotProduct = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dotProduct += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    if (normA === 0 || normB === 0)
-        return 0;
-    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
-}
-/**
- * Convert HNSW distance to similarity score.
- * HNSW returns distances, we need similarities (higher = more similar).
- *
- * @param distance - Distance value from HNSW
- * @param metric - Distance metric used
- * @returns Similarity score
- */
-export function distanceToSimilarity(distance, metric = 'cosine') {
-    if (metric === 'cosine') {
-        // For cosine space, HNSW returns 1 - cosine_similarity
-        return 1 - distance;
-    }
-    // For L2/IP, need different conversion
-    return 1 / (1 + distance);
-}
-/**
- * Estimate memory usage for an HNSW index.
- *
- * @param vectorCount - Number of vectors
- * @param dimensions - Vector dimensionality
- * @param m - HNSW M parameter
- * @returns Estimated memory usage in bytes
- */
-export function estimateMemoryUsage(vectorCount, dimensions, m) {
-    // HNSW uses ~(4 * dimensions + M * 4 * 2) bytes per vector
-    const bytesPerVector = 4 * dimensions + m * 8;
-    return vectorCount * bytesPerVector;
-}
-/**
- * Validate embedding dimensions.
- *
- * @param embedding - Embedding to validate
- * @param expectedDimensions - Expected dimension count
- * @param context - Context for error message (default: 'Query')
- * @throws Error if dimensions don't match
- */
-export function validateDimensions(embedding, expectedDimensions, context = 'Query') {
-    if (embedding.length !== expectedDimensions) {
-        throw new Error(`${context} dimension mismatch: got ${embedding.length}, expected ${expectedDimensions}`);
-    }
-}
-/**
- * Determine whether to use HNSW based on explicit option or environment.
- *
- * @param explicit - Explicit useHNSW option (if provided)
- * @returns Whether to enable HNSW
- */
-export function shouldUseHNSW(explicit) {
-    if (explicit !== undefined) {
-        return explicit;
-    }
-    const envValue = process.env.SKILLSMITH_USE_HNSW;
-    if (envValue !== undefined) {
-        return envValue === 'true' || envValue === '1';
-    }
-    // Default to false for backward compatibility
-    return false;
-}
-//# sourceMappingURL=hnsw-store.helpers.js.map

package/dist/embeddings/hnsw-store.helpers.js.map

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

package/dist/embeddings/hnsw-store.js

@@ -1,352 +0,0 @@
-/**
- * SMI-1519: HNSW Embedding Store
- *
- * High-performance vector storage using HNSW index for fast ANN search.
- * Uses brute-force search (V3 VectorDB unavailable after claude-flow rename).
- *
- * Enable via: SKILLSMITH_USE_HNSW=true
- * @see ADR-009: Embedding Service Fallback Strategy
- */
-import { createDatabaseSync, createDatabaseAsync } from '../db/createDatabase.js';
-export { DEFAULT_HNSW_CONFIG, HNSW_PRESETS } from './hnsw-store.types.js';
-// Re-export factory functions
-export { createHNSWStore, isHNSWAvailable, loadHNSWLib } from './hnsw-store.helpers.js';
-import { DEFAULT_HNSW_CONFIG } from './hnsw-store.types.js';
-import { shouldUseHNSW, validateDimensions, estimateMemoryUsage } from './hnsw-store.helpers.js';
-/**
- * High-performance embedding storage using HNSW index.
- * Provides O(log n) approximate nearest neighbor search with SQLite persistence.
- */
-export class HNSWEmbeddingStore {
-    db = null;
-    index = null;
-    hnswEnabled;
-    config;
-    maxElements;
-    indexPath;
-    distanceMetric;
-    autoSave;
-    skillIdToLabel = new Map();
-    labelToSkillId = new Map();
-    nextLabel = 0;
-    vectorDB = null;
-    initPromise = null;
-    /**
-     * @deprecated If dbPath is passed, use HNSWEmbeddingStore.create(options) instead —
-     * the async factory supports both native and WASM SQLite. Passing dbPath to this
-     * constructor throws to prevent silent data loss.
-     */
-    constructor(options = {}) {
-        if (options.dbPath) {
-            throw new Error('[HNSWEmbeddingStore] Cannot open a database file in the sync constructor. ' +
-                'Use await HNSWEmbeddingStore.create(options) instead.');
-        }
-        this.hnswEnabled = shouldUseHNSW(options.useHNSW);
-        this.config = { ...DEFAULT_HNSW_CONFIG, ...options.hnswConfig };
-        this.maxElements = options.maxElements ?? 100000;
-        this.indexPath = options.indexPath;
-        this.distanceMetric = options.distanceMetric ?? 'cosine';
-        this.autoSave = options.autoSave ?? false;
-        // IMPORTANT: Keep dynamic import here for V3 lazy loading / graceful degradation
-        if (this.hnswEnabled) {
-            this.initPromise = this.initHNSWIndex();
-        }
-    }
-    /**
-     * Async factory — supports both native and WASM SQLite.
-     *
-     * @param options - Store options; dbPath is opened via createDatabaseAsync
-     * @returns Fully initialised HNSWEmbeddingStore instance
-     */
-    static async create(options = {}) {
-        // Bypass the throwing constructor by omitting dbPath
-        const { dbPath, ...rest } = options;
-        const instance = new HNSWEmbeddingStore(rest);
-        if (dbPath) {
-            await instance.initDatabaseAsync(dbPath);
-        }
-        return instance;
-    }
-    async ensureInitialized() {
-        if (this.initPromise)
-            await this.initPromise;
-    }
-    storeEmbedding(skillId, embedding, text) {
-        validateDimensions(embedding, this.config.dimensions, 'Embedding');
-        if (this.db) {
-            const buffer = Buffer.from(embedding.buffer);
-            const stmt = this.db.prepare(`
-        INSERT OR REPLACE INTO skill_embeddings (skill_id, embedding, text, created_at)
-        VALUES (?, ?, ?, unixepoch())
-      `);
-            stmt.run(skillId, buffer, text);
-        }
-        if (this.vectorDB) {
-            const result = this.vectorDB.insert(embedding, skillId, { text });
-            if (result instanceof Promise) {
-                result.catch((err) => {
-                    console.warn(`[HNSWEmbeddingStore] Failed to insert into VectorDB: ${err}`);
-                });
-            }
-        }
-    }
-    getEmbedding(skillId) {
-        if (!this.db)
-            return null;
-        const stmt = this.db.prepare('SELECT embedding FROM skill_embeddings WHERE skill_id = ?');
-        const row = stmt.get(skillId);
-        if (!row)
-            return null;
-        return new Float32Array(row.embedding.buffer.slice(row.embedding.byteOffset, row.embedding.byteOffset + row.embedding.byteLength));
-    }
-    getAllEmbeddings() {
-        if (!this.db)
-            return new Map();
-        const stmt = this.db.prepare('SELECT skill_id, embedding FROM skill_embeddings');
-        const rows = stmt.all();
-        const result = new Map();
-        for (const row of rows) {
-            const embedding = new Float32Array(row.embedding.buffer.slice(row.embedding.byteOffset, row.embedding.byteOffset + row.embedding.byteLength));
-            result.set(row.skill_id, embedding);
-        }
-        return result;
-    }
-    findSimilar(queryEmbedding, topK = 10) {
-        validateDimensions(queryEmbedding, this.config.dimensions);
-        if (this.vectorDB) {
-            try {
-                const searchResult = this.vectorDB.search(queryEmbedding, topK);
-                if (searchResult instanceof Promise) {
-                    console.warn('[HNSWEmbeddingStore] VectorDB.search returned Promise, using brute-force');
-                }
-                else {
-                    return searchResult.map((r) => ({ skillId: r.id, score: r.score }));
-                }
-            }
-            catch (err) {
-                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back: ${err}`);
-            }
-        }
-        // Brute-force fallback
-        const allEmbeddings = this.getAllEmbeddings();
-        const results = [];
-        for (const [skillId, embedding] of allEmbeddings) {
-            results.push({ skillId, score: this.cosineSimilarity(queryEmbedding, embedding) });
-        }
-        results.sort((a, b) => b.score - a.score);
-        return results.slice(0, topK);
-    }
-    async findSimilarAsync(queryEmbedding, topK = 10) {
-        await this.ensureInitialized();
-        validateDimensions(queryEmbedding, this.config.dimensions);
-        if (this.vectorDB) {
-            try {
-                const searchResult = this.vectorDB.search(queryEmbedding, topK);
-                const results = searchResult instanceof Promise ? await searchResult : searchResult;
-                return results.map((r) => ({ skillId: r.id, score: r.score }));
-            }
-            catch (err) {
-                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back: ${err}`);
-            }
-        }
-        return this.findSimilar(queryEmbedding, topK);
-    }
-    cosineSimilarity(a, b) {
-        if (a.length !== b.length) {
-            throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}`);
-        }
-        let dotProduct = 0, normA = 0, normB = 0;
-        for (let i = 0; i < a.length; i++) {
-            dotProduct += a[i] * b[i];
-            normA += a[i] * a[i];
-            normB += b[i] * b[i];
-        }
-        if (normA === 0 || normB === 0)
-            return 0;
-        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
-    }
-    isUsingFallback() {
-        return !this.hnswEnabled || this.index === null;
-    }
-    close() {
-        if (this.db) {
-            this.db.close();
-            this.db = null;
-        }
-    }
-    getStats() {
-        let vectorCount = 0;
-        if (this.db) {
-            const stmt = this.db.prepare('SELECT COUNT(*) as count FROM skill_embeddings');
-            vectorCount = stmt.get().count;
-        }
-        if (this.vectorDB) {
-            try {
-                const size = this.vectorDB.size();
-                if (!(size instanceof Promise))
-                    vectorCount = Math.max(vectorCount, size);
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        return {
-            vectorCount,
-            maxCapacity: this.maxElements,
-            utilizationPercent: Math.round((vectorCount / this.maxElements) * 10000) / 100,
-            m: this.config.m,
-            efConstruction: this.config.efConstruction,
-            efSearch: this.config.efSearch,
-            dimensions: this.config.dimensions,
-            memoryUsageBytes: estimateMemoryUsage(vectorCount, this.config.dimensions, this.config.m),
-            isHNSWEnabled: this.vectorDB !== null,
-            indexPath: this.indexPath,
-        };
-    }
-    batchInsert(embeddings) {
-        const startTime = Date.now();
-        const result = {
-            inserted: 0,
-            updated: 0,
-            failed: 0,
-            errors: [],
-            durationMs: 0,
-        };
-        if (!this.db) {
-            result.errors.push({ skillId: '*', error: 'Database not initialized' });
-            result.durationMs = Date.now() - startTime;
-            return result;
-        }
-        const insertStmt = this.db.prepare(`
-      INSERT OR REPLACE INTO skill_embeddings (skill_id, embedding, text, created_at)
-      VALUES (?, ?, ?, unixepoch())
-    `);
-        const checkStmt = this.db.prepare('SELECT 1 FROM skill_embeddings WHERE skill_id = ?');
-        const transaction = this.db.transaction(() => {
-            for (const { skillId, embedding, text } of embeddings) {
-                try {
-                    if (embedding.length !== this.config.dimensions) {
-                        result.failed++;
-                        result.errors.push({ skillId, error: `Dimension mismatch: ${embedding.length}` });
-                        continue;
-                    }
-                    const exists = checkStmt.get(skillId);
-                    insertStmt.run(skillId, Buffer.from(embedding.buffer), text);
-                    if (this.vectorDB) {
-                        try {
-                            this.vectorDB.insert(embedding, skillId, { text });
-                        }
-                        catch (err) {
-                            console.warn(`VectorDB insert failed for ${skillId}: ${err}`);
-                        }
-                    }
-                    if (exists)
-                        result.updated++;
-                    else
-                        result.inserted++;
-                }
-                catch (err) {
-                    result.failed++;
-                    result.errors.push({ skillId, error: err instanceof Error ? err.message : String(err) });
-                }
-            }
-        });
-        transaction();
-        result.durationMs = Date.now() - startTime;
-        return result;
-    }
-    removeEmbedding(skillId) {
-        let removed = false;
-        if (this.db) {
-            const stmt = this.db.prepare('DELETE FROM skill_embeddings WHERE skill_id = ?');
-            removed = stmt.run(skillId).changes > 0;
-        }
-        if (this.vectorDB && removed) {
-            try {
-                const vdbResult = this.vectorDB.remove(skillId);
-                if (vdbResult instanceof Promise) {
-                    vdbResult.catch((err) => console.warn(`VectorDB remove failed: ${err}`));
-                }
-            }
-            catch (err) {
-                console.warn(`VectorDB remove failed: ${err}`);
-            }
-        }
-        return removed;
-    }
-    saveIndex() {
-        if (!this.indexPath)
-            throw new Error('Cannot save index: indexPath not configured');
-        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
-    }
-    loadIndex() {
-        if (!this.indexPath)
-            throw new Error('Cannot load index: indexPath not configured');
-        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
-    }
-    async rebuildIndex(newConfig) {
-        if (newConfig)
-            Object.assign(this.config, newConfig);
-        if (this.vectorDB) {
-            try {
-                const clearResult = this.vectorDB.clear();
-                if (clearResult instanceof Promise)
-                    await clearResult;
-            }
-            catch (err) {
-                console.warn(`Failed to clear VectorDB: ${err}`);
-            }
-        }
-        await this.initHNSWIndex();
-        if (this.db && this.vectorDB) {
-            const allEmbeddings = this.getAllEmbeddings();
-            for (const [skillId, embedding] of allEmbeddings) {
-                try {
-                    const result = this.vectorDB.insert(embedding, skillId);
-                    if (result instanceof Promise)
-                        await result;
-                }
-                catch (err) {
-                    console.warn(`Failed to reinsert ${skillId}: ${err}`);
-                }
-            }
-        }
-    }
-    setEfSearch(efSearch) {
-        if (efSearch <= 0)
-            throw new Error('efSearch must be > 0');
-        this.config.efSearch = efSearch;
-        console.log(`[HNSWEmbeddingStore] efSearch updated to ${efSearch}`);
-    }
-    // Private methods
-    initDatabase(dbPath) {
-        this.db = createDatabaseSync(dbPath);
-        this.initEmbeddingsTable();
-    }
-    async initDatabaseAsync(dbPath) {
-        this.db = await createDatabaseAsync(dbPath);
-        this.initEmbeddingsTable();
-    }
-    initEmbeddingsTable() {
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS skill_embeddings (
-        skill_id TEXT PRIMARY KEY,
-        embedding BLOB NOT NULL,
-        text TEXT NOT NULL,
-        created_at INTEGER DEFAULT (unixepoch())
-      );
-      CREATE INDEX IF NOT EXISTS idx_skill_embeddings_id ON skill_embeddings(skill_id);
-    `);
-    }
-    async initHNSWIndex() {
-        // V3 VectorDB unavailable after claude-flow → ruflo rename (SMI-3600)
-        // @claude-flow/cli restricts subpath imports; always use brute-force search
-        this.vectorDB = null;
-    }
-    distanceToSimilarity(distance) {
-        if (this.distanceMetric === 'cosine')
-            return 1 - distance;
-        return 1 / (1 + distance);
-    }
-}
-//# sourceMappingURL=hnsw-store.js.map