@skillsmith/core 0.5.4 → 0.5.6

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

@@ -0,0 +1,72 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,83 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,147 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,352 @@
+/**
+ * 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