@skillsmith/core 0.5.8 → 0.6.0

package/dist/src/embeddings/hnsw-search.d.ts

@@ -0,0 +1,133 @@
+/**
+ * SMI-4577: HNSW search backend for `EmbeddingService.findSimilar`.
+ *
+ * Lazily loads `hnswlib-node` (declared as `optionalDependencies` on
+ * @skillsmith/core), builds or loads an on-disk index at
+ * `~/.skillsmith/cache/hnsw-{modelName}.{bin,meta.json,labels.json}`,
+ * and exposes incremental `addPoint`/`markDelete` semantics with a debounced
+ * atomic-rename persist.
+ *
+ * Failure modes:
+ *  - `MODULE_NOT_FOUND` on import → permanently disable; brute-force fallback
+ *    in `EmbeddingService.findSimilar` covers the case.
+ *  - `readIndex` failure on a corrupt cache → delete + rebuild on next call
+ *    (treat as transient).
+ *  - Concurrent writers → atomic-rename (`writeIndex` to `.tmp`,
+ *    `fs.renameSync` to final). Loser-of-race acceptable; readers re-read
+ *    via the atomic pointer.
+ *
+ * @see ADR-009 (2026-05 amendment): brute-force fallback retained for
+ * environments where the optional dep failed to install.
+ */
+import type { HierarchicalNSW } from './hnsw-store.types.js';
+/**
+ * Persisted metadata describing the on-disk HNSW index. Used to invalidate the
+ * cached graph when the embedding count, model, or vector dimension drift.
+ */
+export interface HnswMeta {
+    /** Schema version. Bump on incompatible meta changes. */
+    version: 1;
+    /** Model identifier (e.g. `Xenova/all-MiniLM-L6-v2`). */
+    modelName: string;
+    /** Vector dimensionality. */
+    dim: number;
+    /** Number of points the cache was built from. */
+    count: number;
+    /** ISO timestamp the cache was last persisted. */
+    builtAt: string;
+}
+/**
+ * Wrapper exposing the live HNSW index plus the bookkeeping needed by
+ * `EmbeddingService` to rewire incremental upserts/removes.
+ */
+export interface HnswHandle {
+    /** The live HNSW index. */
+    index: HierarchicalNSW;
+    /** label → skillId mapping (HNSW returns numeric labels). */
+    labelToId: Map<number, string>;
+    /** skillId → label mapping (for incremental updates / deletes). */
+    idToLabel: Map<string, number>;
+    /** Next label to assign for new points. */
+    nextLabel: number;
+    /** Filesystem paths the index will read/write. Exposed for diagnostics/tests. */
+    paths: HnswCachePaths;
+    /** Schedule a debounced persist (5s). Safe to call repeatedly. */
+    schedulePersist: () => void;
+    /** Persist immediately (used at shutdown / for tests). */
+    persistNow: () => void;
+}
+export interface HnswCachePaths {
+    bin: string;
+    meta: string;
+    labels: string;
+    binTmp: string;
+    metaTmp: string;
+    labelsTmp: string;
+}
+/**
+ * Status reported back to `EmbeddingService` so it can distinguish
+ * "the optional dep is missing" (permanent) from "we hit a transient
+ * write error" (try again next time).
+ */
+export type HnswStatus = {
+    kind: 'ok';
+    handle: HnswHandle;
+} | {
+    kind: 'permanently-unavailable';
+    reason: string;
+} | {
+    kind: 'temporarily-unavailable';
+    reason: string;
+};
+/**
+ * Build (or load from cache) an HNSW index for the supplied embedding map.
+ *
+ * `embeddings` is the canonical source of truth (from `EmbeddingService`'s
+ * SQLite cache). On a cold start with a populated cache file matching
+ * meta.json, we `readIndex` and skip the rebuild. Otherwise we initialise
+ * a fresh index and add every point — same I/O cost as a brute-force seed
+ * but the resulting graph survives subsequent `findSimilar` calls.
+ */
+export declare function loadOrBuildHnsw(args: {
+    embeddings: Map<string, Float32Array>;
+    modelName: string;
+    dim: number;
+    /** Capacity hint. Defaults to ~2x current size, clamped to 1024 minimum. */
+    maxElements?: number;
+    /** Override hyperparams. Defaults match `DEFAULT_HNSW_CONFIG` in hnsw-store.types.ts. */
+    m?: number;
+    efConstruction?: number;
+    efSearch?: number;
+}): Promise<HnswStatus>;
+/**
+ * Top-K nearest-neighbour search via the supplied handle.
+ *
+ * @param handle - HNSW handle returned by `loadOrBuildHnsw`
+ * @param query - Query vector (must match `handle.dim`)
+ * @param topK - Maximum neighbours to return
+ * @returns Result rows in HNSW score order; `score` is `1 - cosineDistance`.
+ */
+export declare function findSimilarHnsw(handle: HnswHandle, query: Float32Array, topK: number): Array<{
+    skillId: string;
+    score: number;
+}>;
+/**
+ * Add or replace a point. Used by `EmbeddingService.storeEmbedding` to keep
+ * the in-memory graph aligned with the SQLite cache. Marks the handle dirty;
+ * persist happens via the debounced 5s timer (or `persistNow`).
+ */
+export declare function upsertPoint(handle: HnswHandle, skillId: string, vector: Float32Array): void;
+/**
+ * Mark a point deleted. The point stays in the graph for traversal correctness
+ * but `findSimilarHnsw` filters it out via the labelToId lookup.
+ */
+export declare function removePoint(handle: HnswHandle, skillId: string): boolean;
+/**
+ * Test-only helper — clears the cached `hnswlib-node` constructor reference so
+ * tests can simulate "module reinstalled" scenarios. Not part of the public
+ * API; do not use in production code.
+ *
+ * @internal
+ */
+export declare function __resetCachedHnswCtorForTests(): void;
+//# sourceMappingURL=hnsw-search.d.ts.map

package/dist/src/embeddings/hnsw-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-search.d.ts","sourceRoot":"","sources":["../../../src/embeddings/hnsw-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAA;AAExF;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,OAAO,EAAE,CAAC,CAAA;IACV,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,KAAK,EAAE,eAAe,CAAA;IACtB,6DAA6D;IAC7D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,mEAAmE;IACnE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,KAAK,EAAE,cAAc,CAAA;IACrB,kEAAkE;IAClE,eAAe,EAAE,MAAM,IAAI,CAAA;IAC3B,0DAA0D;IAC1D,UAAU,EAAE,MAAM,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AA8FvD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACrC,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yFAAyF;IACzF,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6GtB;AAgGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAc3C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAgB3F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/src/embeddings/hnsw-search.js

@@ -0,0 +1,387 @@
+/**
+ * SMI-4577: HNSW search backend for `EmbeddingService.findSimilar`.
+ *
+ * Lazily loads `hnswlib-node` (declared as `optionalDependencies` on
+ * @skillsmith/core), builds or loads an on-disk index at
+ * `~/.skillsmith/cache/hnsw-{modelName}.{bin,meta.json,labels.json}`,
+ * and exposes incremental `addPoint`/`markDelete` semantics with a debounced
+ * atomic-rename persist.
+ *
+ * Failure modes:
+ *  - `MODULE_NOT_FOUND` on import → permanently disable; brute-force fallback
+ *    in `EmbeddingService.findSimilar` covers the case.
+ *  - `readIndex` failure on a corrupt cache → delete + rebuild on next call
+ *    (treat as transient).
+ *  - Concurrent writers → atomic-rename (`writeIndex` to `.tmp`,
+ *    `fs.renameSync` to final). Loser-of-race acceptable; readers re-read
+ *    via the atomic pointer.
+ *
+ * @see ADR-009 (2026-05 amendment): brute-force fallback retained for
+ * environments where the optional dep failed to install.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { getCacheDir } from '../config/index.js';
+/**
+ * One-shot module loader. Cached across calls; on `MODULE_NOT_FOUND` the
+ * caller receives a sentinel and is expected to permanently disable HNSW.
+ */
+let cachedCtor = null;
+/**
+ * Dynamically load `hnswlib-node`. Returns the constructor or `null` when the
+ * optional dependency is not installed (Vercel build, restricted hosts).
+ *
+ * Uses a literal dynamic `import()` (not the `Function('return import(...)')()`
+ * pattern that lives in `hnsw-store.helpers.ts`); vitest's vm-mode ESM rejects
+ * the latter with "A dynamic import callback was not specified." A native
+ * dynamic import is safe here because `hnswlib-node` is a CJS module that's
+ * not type-imported anywhere — only TS will error on resolution failure, but
+ * we catch that in the `catch` block below.
+ */
+async function loadHnswCtor() {
+    if (cachedCtor === 'unavailable')
+        return null;
+    if (cachedCtor !== null)
+        return cachedCtor;
+    try {
+        // hnswlib-node is CJS; ESM dynamic import lifts its `module.exports` onto
+        // `.default`. Some bundlers / older Node versions also surface named
+        // exports at the top level — check both shapes so we work in every
+        // environment.
+        //
+        // Note: a previous codebase pattern used `Function('return import(...)')()`
+        // here. Vitest's vm-mode ESM rejects that with "A dynamic import callback
+        // was not specified" so we use a literal dynamic `import()`. The string
+        // literal is intentional to keep TypeScript from re-routing the specifier
+        // (`hnswlib-node` is in `optionalDependencies`, not a hard dep).
+        const mod = (await import('hnswlib-node'));
+        const ctor = mod.HierarchicalNSW ?? mod.default?.HierarchicalNSW;
+        if (!ctor) {
+            cachedCtor = 'unavailable';
+            return null;
+        }
+        cachedCtor = ctor;
+        return cachedCtor;
+    }
+    catch {
+        cachedCtor = 'unavailable';
+        return null;
+    }
+}
+function cachePaths(modelName) {
+    // Sanitize model name (slashes become double-underscore so we don't
+    // accidentally create nested directories under cache/).
+    const safeName = modelName.replace(/[/\\]/g, '__');
+    const dir = getCacheDir();
+    const base = join(dir, `hnsw-${safeName}`);
+    return {
+        bin: `${base}.bin`,
+        meta: `${base}.meta.json`,
+        labels: `${base}.labels.json`,
+        binTmp: `${base}.bin.tmp`,
+        metaTmp: `${base}.meta.json.tmp`,
+        labelsTmp: `${base}.labels.json.tmp`,
+    };
+}
+function readMeta(metaPath) {
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(metaPath, 'utf-8'));
+        if (parsed.version !== 1)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function readLabels(labelsPath) {
+    if (!existsSync(labelsPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(labelsPath, 'utf-8'));
+        if (!Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAtomic(tmp, final, contents) {
+    mkdirSync(dirname(tmp), { recursive: true });
+    writeFileSync(tmp, contents, typeof contents === 'string' ? { encoding: 'utf-8' } : undefined);
+    renameSync(tmp, final);
+}
+/**
+ * Build (or load from cache) an HNSW index for the supplied embedding map.
+ *
+ * `embeddings` is the canonical source of truth (from `EmbeddingService`'s
+ * SQLite cache). On a cold start with a populated cache file matching
+ * meta.json, we `readIndex` and skip the rebuild. Otherwise we initialise
+ * a fresh index and add every point — same I/O cost as a brute-force seed
+ * but the resulting graph survives subsequent `findSimilar` calls.
+ */
+export async function loadOrBuildHnsw(args) {
+    const Ctor = await loadHnswCtor();
+    if (!Ctor) {
+        return {
+            kind: 'permanently-unavailable',
+            reason: 'hnswlib-node not installed (optionalDependencies)',
+        };
+    }
+    const paths = cachePaths(args.modelName);
+    const meta = readMeta(paths.meta);
+    const labels = readLabels(paths.labels);
+    const count = args.embeddings.size;
+    // R2 mitigation: defaults tuned to clear the recall@10 ≥ 0.95 gate.
+    // m=32/efConstruction=400/efSearch=200 is the `large` preset from
+    // hnsw-store.types.ts and matches what the original SMI-1519 design
+    // documented for 100k-scale skill registries. At 14k synthetic vectors
+    // we still see >100x speedup vs brute-force p99.
+    const m = args.m ?? 32;
+    const efConstruction = args.efConstruction ?? 400;
+    const efSearch = args.efSearch ?? 200;
+    const capacity = Math.max(args.maxElements ?? Math.max(count * 2, 1024), 1024);
+    const reusable = meta !== null &&
+        labels !== null &&
+        meta.modelName === args.modelName &&
+        meta.dim === args.dim &&
+        meta.count === count &&
+        existsSync(paths.bin);
+    let index;
+    let labelToId;
+    let idToLabel;
+    let nextLabel;
+    if (reusable) {
+        try {
+            index = new Ctor('cosine', args.dim);
+            // Use sync read; the async `readIndex` returns a Promise we'd have to
+            // await, defeating the synchronous boot path. Sync is fine here — the
+            // file is < a few MB at expected scale.
+            index.readIndexSync(paths.bin, true);
+            index.setEf(efSearch);
+            labelToId = new Map(labels);
+            idToLabel = new Map(labels.map(([label, id]) => [id, label]));
+            nextLabel = labels.reduce((max, [label]) => Math.max(max, label), -1) + 1;
+        }
+        catch (err) {
+            // Corrupt cache — wipe and recurse for a fresh build. The retry will
+            // hit `reusable === false` because we just removed the artefacts.
+            try {
+                if (existsSync(paths.bin))
+                    unlinkSync(paths.bin);
+                if (existsSync(paths.meta))
+                    unlinkSync(paths.meta);
+                if (existsSync(paths.labels))
+                    unlinkSync(paths.labels);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            try {
+                return await loadOrBuildHnsw(args);
+            }
+            catch (retryErr) {
+                return {
+                    kind: 'temporarily-unavailable',
+                    reason: `cache rebuild failed after corrupt-load: ${String(retryErr)} (initial: ${String(err)})`,
+                };
+            }
+        }
+    }
+    else {
+        index = new Ctor('cosine', args.dim);
+        index.initIndex(capacity, m, efConstruction);
+        index.setEf(efSearch);
+        labelToId = new Map();
+        idToLabel = new Map();
+        let nextLabelLocal = 0;
+        for (const [skillId, vec] of args.embeddings) {
+            // hnswlib-node@3 expects a plain Array<number> for addPoint, not a
+            // typed array — passing Float32Array surfaces as
+            // "Invalid the first argument type, must be an Array."
+            index.addPoint(Array.from(vec), nextLabelLocal);
+            labelToId.set(nextLabelLocal, skillId);
+            idToLabel.set(skillId, nextLabelLocal);
+            nextLabelLocal++;
+        }
+        nextLabel = nextLabelLocal;
+    }
+    const handle = createHandle({
+        index,
+        labelToId,
+        idToLabel,
+        nextLabel,
+        dim: args.dim,
+        modelName: args.modelName,
+        paths,
+    });
+    // Immediate persist after a fresh build. Reusable path skips this — the
+    // on-disk artefacts already match.
+    if (!reusable) {
+        try {
+            handle.persistNow();
+        }
+        catch (err) {
+            return {
+                kind: 'temporarily-unavailable',
+                reason: `persist after build failed: ${String(err)}`,
+            };
+        }
+    }
+    return { kind: 'ok', handle };
+}
+/**
+ * Wrap the raw HNSW index with the bookkeeping needed for incremental upserts
+ * + debounced persist. Caller owns the handle's lifecycle (no auto-cleanup).
+ */
+function createHandle(args) {
+    let dirty = false;
+    let timer = null;
+    // Mutable closure state — we update via the handle methods below, but the
+    // returned object exposes the current values via getters.
+    const state = {
+        nextLabel: args.nextLabel,
+    };
+    const persistNow = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (!dirty && existsSync(args.paths.bin) && existsSync(args.paths.meta)) {
+            // Nothing to write and the cache is already consistent on disk.
+            return;
+        }
+        // `writeIndex` is async (returns a Promise) — we want sync semantics so
+        // the persist runs to completion inside the debounce callback / on close.
+        args.index.writeIndexSync(args.paths.binTmp);
+        renameSync(args.paths.binTmp, args.paths.bin);
+        const labelsArr = Array.from(args.labelToId.entries());
+        writeAtomic(args.paths.labelsTmp, args.paths.labels, JSON.stringify(labelsArr));
+        const meta = {
+            version: 1,
+            modelName: args.modelName,
+            dim: args.dim,
+            count: args.idToLabel.size,
+            builtAt: new Date().toISOString(),
+        };
+        writeAtomic(args.paths.metaTmp, args.paths.meta, JSON.stringify(meta, null, 2));
+        dirty = false;
+    };
+    const schedulePersist = () => {
+        dirty = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            try {
+                persistNow();
+            }
+            catch (err) {
+                // Persist failures are non-fatal — the in-memory index stays valid;
+                // a future rebuild will recover from the cached embeddings map.
+                // Log the cache path so a user can spot a read-only cache dir.
+                console.warn(`[hnsw-search] debounced persist failed (path=${args.paths.bin}):`, err instanceof Error ? err.message : err);
+            }
+        }, 5000);
+        // Don't keep the event loop alive just for this timer.
+        if (timer && typeof timer.unref === 'function')
+            timer.unref();
+    };
+    return {
+        get index() {
+            return args.index;
+        },
+        get labelToId() {
+            return args.labelToId;
+        },
+        get idToLabel() {
+            return args.idToLabel;
+        },
+        get nextLabel() {
+            return state.nextLabel;
+        },
+        set nextLabel(v) {
+            state.nextLabel = v;
+        },
+        get paths() {
+            return args.paths;
+        },
+        schedulePersist,
+        persistNow,
+    };
+}
+/**
+ * Top-K nearest-neighbour search via the supplied handle.
+ *
+ * @param handle - HNSW handle returned by `loadOrBuildHnsw`
+ * @param query - Query vector (must match `handle.dim`)
+ * @param topK - Maximum neighbours to return
+ * @returns Result rows in HNSW score order; `score` is `1 - cosineDistance`.
+ */
+export function findSimilarHnsw(handle, query, topK) {
+    const liveCount = handle.idToLabel.size;
+    if (liveCount === 0)
+        return [];
+    const k = Math.min(topK, liveCount);
+    // searchKnn also requires plain Array — Float32Array triggers
+    // "Invalid the first argument type, must be an Array."
+    const result = handle.index.searchKnn(Array.from(query), k);
+    const out = [];
+    for (let i = 0; i < result.neighbors.length; i++) {
+        const skillId = handle.labelToId.get(result.neighbors[i]);
+        if (!skillId)
+            continue; // marked-deleted points may still surface; skip
+        out.push({ skillId, score: 1 - result.distances[i] });
+    }
+    return out;
+}
+/**
+ * Add or replace a point. Used by `EmbeddingService.storeEmbedding` to keep
+ * the in-memory graph aligned with the SQLite cache. Marks the handle dirty;
+ * persist happens via the debounced 5s timer (or `persistNow`).
+ */
+export function upsertPoint(handle, skillId, vector) {
+    const existing = handle.idToLabel.get(skillId);
+    if (existing !== undefined) {
+        // hnswlib supports `addPoint(..., replaceDeleted=true)` for true
+        // replacement; for non-deleted points we mark + reinsert under a new
+        // label to preserve correctness across efConstruction tuning.
+        handle.index.markDelete(existing);
+        handle.labelToId.delete(existing);
+    }
+    const label = handle.nextLabel;
+    // Plain Array required (see addPoint comment above).
+    handle.index.addPoint(Array.from(vector), label);
+    handle.idToLabel.set(skillId, label);
+    handle.labelToId.set(label, skillId);
+    handle.nextLabel = label + 1;
+    handle.schedulePersist();
+}
+/**
+ * Mark a point deleted. The point stays in the graph for traversal correctness
+ * but `findSimilarHnsw` filters it out via the labelToId lookup.
+ */
+export function removePoint(handle, skillId) {
+    const label = handle.idToLabel.get(skillId);
+    if (label === undefined)
+        return false;
+    handle.index.markDelete(label);
+    handle.idToLabel.delete(skillId);
+    handle.labelToId.delete(label);
+    handle.schedulePersist();
+    return true;
+}
+/**
+ * Test-only helper — clears the cached `hnswlib-node` constructor reference so
+ * tests can simulate "module reinstalled" scenarios. Not part of the public
+ * API; do not use in production code.
+ *
+ * @internal
+ */
+export function __resetCachedHnswCtorForTests() {
+    cachedCtor = null;
+}
+//# sourceMappingURL=hnsw-search.js.map

package/dist/src/embeddings/hnsw-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-search.js","sourceRoot":"","sources":["../../../src/embeddings/hnsw-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAC/F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA4DhD;;;GAGG;AACH,IAAI,UAAU,GAAsD,IAAI,CAAA;AAExE;;;;;;;;;;GAUG;AACH,KAAK,UAAU,YAAY;IACzB,IAAI,UAAU,KAAK,aAAa;QAAE,OAAO,IAAI,CAAA;IAC7C,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAA;IAC1C,IAAI,CAAC;QACH,0EAA0E;QAC1E,qEAAqE;QACrE,mEAAmE;QACnE,eAAe;QACf,EAAE;QACF,4EAA4E;QAC5E,0EAA0E;QAC1E,wEAAwE;QACxE,0EAA0E;QAC1E,iEAAiE;QACjE,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,CAGxC,CAAA;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,OAAO,EAAE,eAAe,CAAA;QAChE,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,UAAU,GAAG,aAAa,CAAA;YAC1B,OAAO,IAAI,CAAA;QACb,CAAC;QACD,UAAU,GAAG,IAAI,CAAA;QACjB,OAAO,UAAU,CAAA;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,UAAU,GAAG,aAAa,CAAA;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,SAAiB;IACnC,oEAAoE;IACpE,wDAAwD;IACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;IAClD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAA;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,QAAQ,EAAE,CAAC,CAAA;IAC1C,OAAO;QACL,GAAG,EAAE,GAAG,IAAI,MAAM;QAClB,IAAI,EAAE,GAAG,IAAI,YAAY;QACzB,MAAM,EAAE,GAAG,IAAI,cAAc;QAC7B,MAAM,EAAE,GAAG,IAAI,UAAU;QACzB,OAAO,EAAE,GAAG,IAAI,gBAAgB;QAChC,SAAS,EAAE,GAAG,IAAI,kBAAkB;KACrC,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,QAAgB;IAChC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAa,CAAA;QACtE,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACrC,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,UAAkB;IACpC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAA;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAA4B,CAAA;QACvF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAA;QACvC,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAW,EAAE,KAAa,EAAE,QAAyB;IACxE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5C,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC9F,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAUrC;IACC,MAAM,IAAI,GAAG,MAAM,YAAY,EAAE,CAAA;IACjC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,IAAI,EAAE,yBAAyB;YAC/B,MAAM,EAAE,mDAAmD;SAC5D,CAAA;IACH,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAA;IAClC,oEAAoE;IACpE,kEAAkE;IAClE,oEAAoE;IACpE,uEAAuE;IACvE,iDAAiD;IACjD,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAA;IACtB,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,GAAG,CAAA;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAA;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;IAE9E,MAAM,QAAQ,GACZ,IAAI,KAAK,IAAI;QACb,MAAM,KAAK,IAAI;QACf,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS;QACjC,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG;QACrB,IAAI,CAAC,KAAK,KAAK,KAAK;QACpB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEvB,IAAI,KAAsB,CAAA;IAC1B,IAAI,SAA8B,CAAA;IAClC,IAAI,SAA8B,CAAA;IAClC,IAAI,SAAiB,CAAA;IAErB,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YACpC,sEAAsE;YACtE,sEAAsE;YACtE,wCAAwC;YACxC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YACpC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;YACrB,SAAS,GAAG,IAAI,GAAG,CAAC,MAAO,CAAC,CAAA;YAC5B,SAAS,GAAG,IAAI,GAAG,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;YAC9D,SAAS,GAAG,MAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAC5E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,kEAAkE;YAClE,IAAI,CAAC;gBACH,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;oBAAE,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;gBAChD,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAClD,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;oBAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YACxD,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,eAAe,CAAC,IAAI,CAAC,CAAA;YACpC,CAAC;YAAC,OAAO,QAAQ,EAAE,CAAC;gBAClB,OAAO;oBACL,IAAI,EAAE,yBAAyB;oBAC/B,MAAM,EAAE,4CAA4C,MAAM,CAAC,QAAQ,CAAC,cAAc,MAAM,CAAC,GAAG,CAAC,GAAG;iBACjG,CAAA;YACH,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACpC,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,cAAc,CAAC,CAAA;QAC5C,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACrB,SAAS,GAAG,IAAI,GAAG,EAAE,CAAA;QACrB,SAAS,GAAG,IAAI,GAAG,EAAE,CAAA;QACrB,IAAI,cAAc,GAAG,CAAC,CAAA;QACtB,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7C,mEAAmE;YACnE,iDAAiD;YACjD,uDAAuD;YACvD,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAA;YAC/C,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;YACtC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;YACtC,cAAc,EAAE,CAAA;QAClB,CAAC;QACD,SAAS,GAAG,cAAc,CAAA;IAC5B,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,KAAK;QACL,SAAS;QACT,SAAS;QACT,SAAS;QACT,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK;KACN,CAAC,CAAA;IAEF,wEAAwE;IACxE,mCAAmC;IACnC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC;YACH,MAAM,CAAC,UAAU,EAAE,CAAA;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,IAAI,EAAE,yBAAyB;gBAC/B,MAAM,EAAE,+BAA+B,MAAM,CAAC,GAAG,CAAC,EAAE;aACrD,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AAC/B,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAQrB;IACC,IAAI,KAAK,GAAG,KAAK,CAAA;IACjB,IAAI,KAAK,GAAyC,IAAI,CAAA;IACtD,0EAA0E;IAC1E,0DAA0D;IAC1D,MAAM,KAAK,GAAG;QACZ,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAA;IAED,MAAM,UAAU,GAAG,GAAS,EAAE;QAC5B,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,KAAK,GAAG,IAAI,CAAA;QACd,CAAC;QACD,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,gEAAgE;YAChE,OAAM;QACR,CAAC;QACD,wEAAwE;QACxE,0EAA0E;QAC1E,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAC5C,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAE7C,MAAM,SAAS,GAA4B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAA;QAC/E,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAA;QAE/E,MAAM,IAAI,GAAa;YACrB,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;YAC1B,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAClC,CAAA;QACD,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QAC/E,KAAK,GAAG,KAAK,CAAA;IACf,CAAC,CAAA;IAED,MAAM,eAAe,GAAG,GAAS,EAAE;QACjC,KAAK,GAAG,IAAI,CAAA;QACZ,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAA;QAC9B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,GAAG,IAAI,CAAA;YACZ,IAAI,CAAC;gBACH,UAAU,EAAE,CAAA;YACd,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,oEAAoE;gBACpE,gEAAgE;gBAChE,+DAA+D;gBAC/D,OAAO,CAAC,IAAI,CACV,gDAAgD,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,EAClE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAA;YACH,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAA;QACR,uDAAuD;QACvD,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,KAAK,CAAC,KAAK,EAAE,CAAA;IAC/D,CAAC,CAAA;IAED,OAAO;QACL,IAAI,KAAK;YACP,OAAO,IAAI,CAAC,KAAK,CAAA;QACnB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,IAAI,CAAC,SAAS,CAAA;QACvB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,IAAI,CAAC,SAAS,CAAA;QACvB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,KAAK,CAAC,SAAS,CAAA;QACxB,CAAC;QACD,IAAI,SAAS,CAAC,CAAS;YACrB,KAAK,CAAC,SAAS,GAAG,CAAC,CAAA;QACrB,CAAC;QACD,IAAI,KAAK;YACP,OAAO,IAAI,CAAC,KAAK,CAAA;QACnB,CAAC;QACD,eAAe;QACf,UAAU;KACX,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAkB,EAClB,KAAmB,EACnB,IAAY;IAEZ,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAA;IACvC,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IACnC,8DAA8D;IAC9D,uDAAuD;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3D,MAAM,GAAG,GAA8C,EAAE,CAAA;IACzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;QACzD,IAAI,CAAC,OAAO;YAAE,SAAQ,CAAC,gDAAgD;QACvE,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACvD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,OAAe,EAAE,MAAoB;IACnF,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC9C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,iEAAiE;QACjE,qEAAqE;QACrE,8DAA8D;QAC9D,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;QACjC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACnC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAA;IAC9B,qDAAqD;IACrD,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAA;IAChD,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACpC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACpC,MAAM,CAAC,SAAS,GAAG,KAAK,GAAG,CAAC,CAAA;IAC5B,MAAM,CAAC,eAAe,EAAE,CAAA;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,OAAe;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC3C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACrC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IAC9B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAChC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9B,MAAM,CAAC,eAAe,EAAE,CAAA;IACxB,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B;IAC3C,UAAU,GAAG,IAAI,CAAA;AACnB,CAAC"}

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

@@ -1,10 +1,16 @@
 /**
  * SMI-1519: HNSW Embedding Store
+ * SMI-4577: Production HNSW path now lives in `embeddings/hnsw-search.ts` and is
+ *           wired into `EmbeddingService.findSimilar`. This class retains its
+ *           historical API for callers that want a self-contained store without
+ *           the full `EmbeddingService` surface, but no longer references the
+ *           V3 VectorDB (decommissioned after the claude-flow → ruflo rename).
  *
- * High-performance vector storage using HNSW index for fast ANN search.
- * Uses brute-force search (V3 VectorDB unavailable after claude-flow rename).
+ * High-performance vector storage with SQLite-backed metadata. `findSimilar`
+ * uses brute-force search; consumers wanting the HNSW backend should use
+ * `EmbeddingService` instead, which lazy-loads `hnswlib-node` from the
+ * shared search module.
  *
- * Enable via: SKILLSMITH_USE_HNSW=true
  * @see ADR-009: Embedding Service Fallback Strategy
  */
 import type { SimilarityResult } from './index.js';

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

@@ -1 +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"}
+{"version":3,"file":"hnsw-store.d.ts","sourceRoot":"","sources":["../../../src/embeddings/hnsw-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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;IAQjB,SAAS,IAAI,IAAI;IAOX,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;IAS3B,OAAO,CAAC,oBAAoB;CAI7B"}

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

@@ -1,10 +1,16 @@
 /**
  * SMI-1519: HNSW Embedding Store
+ * SMI-4577: Production HNSW path now lives in `embeddings/hnsw-search.ts` and is
+ *           wired into `EmbeddingService.findSimilar`. This class retains its
+ *           historical API for callers that want a self-contained store without
+ *           the full `EmbeddingService` surface, but no longer references the
+ *           V3 VectorDB (decommissioned after the claude-flow → ruflo rename).
  *
- * High-performance vector storage using HNSW index for fast ANN search.
- * Uses brute-force search (V3 VectorDB unavailable after claude-flow rename).
+ * High-performance vector storage with SQLite-backed metadata. `findSimilar`
+ * uses brute-force search; consumers wanting the HNSW backend should use
+ * `EmbeddingService` instead, which lazy-loads `hnswlib-node` from the
+ * shared search module.
  *
- * Enable via: SKILLSMITH_USE_HNSW=true
  * @see ADR-009: Embedding Service Fallback Strategy
  */
 import { createDatabaseSync, createDatabaseAsync } from '../db/createDatabase.js';
@@ -277,12 +283,13 @@ export class HNSWEmbeddingStore {
     saveIndex() {
         if (!this.indexPath)
             throw new Error('Cannot save index: indexPath not configured');
-        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
+        // SMI-4577: persistence now handled by EmbeddingService HNSW backend; this store is a no-op shim.
+        console.log('[HNSWEmbeddingStore] saveIndex() is a no-op; use EmbeddingService for HNSW persistence');
     }
     loadIndex() {
         if (!this.indexPath)
             throw new Error('Cannot load index: indexPath not configured');
-        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
+        console.log('[HNSWEmbeddingStore] loadIndex() is a no-op; use EmbeddingService for HNSW persistence');
     }
     async rebuildIndex(newConfig) {
         if (newConfig)
@@ -339,8 +346,11 @@ export class HNSWEmbeddingStore {
     `);
     }
     async initHNSWIndex() {
-        // V3 VectorDB unavailable after claude-flow → ruflo rename (SMI-3600)
-        // @claude-flow/cli restricts subpath imports; always use brute-force search
+        // SMI-4577: V3 VectorDB was decommissioned with the claude-flow → ruflo rename
+        // (SMI-3600). The replacement HNSW backend lives in `embeddings/hnsw-search.ts`
+        // and is exposed through `EmbeddingService.findSimilar`. This store retains
+        // its public API but always uses the brute-force code path; callers wanting
+        // HNSW should switch to `EmbeddingService` directly.
         this.vectorDB = null;
     }
     distanceToSimilarity(distance) {