@skillsmith/core 0.5.8 → 0.6.1

package/dist/src/db/schema.js

@@ -22,7 +22,10 @@ import { runMigrations, runMigrationsSafe } from './migration-runner.js';
 // v11: SMI-3510 content hash verification column
 // v12: SMI-3864 risk score history for trend detection
 // v13: SMI-3896 visibility and team_id for private skills
-export const SCHEMA_VERSION = 13;
+// v14, v15: reserved (RBAC, integrations)
+// v16: SMI-4665 source column + extend trust_tier CHECK to allow 'local'
+// v17: SMI-4917 widen trust_tier CHECK to allow 'curated'
+export const SCHEMA_VERSION = 17;
 /**
  * Initialize the database with the complete schema.
  *
@@ -75,9 +78,17 @@ export function openDatabase(path) {
     return db;
 }
 /**
- * Close the database connection safely
+ * Close the database connection safely.
+ *
+ * SMI-4640: Tolerate `undefined` so a failed `beforeEach` (e.g. native-module
+ * load error in `createTestDatabase`) is reported as the original error instead
+ * of being shadowed by a `Cannot read properties of undefined (reading 'close')`
+ * cascade in `afterEach`. The underlying create-side error already carries the
+ * actionable diagnostic (see `createDatabaseSync`).
  */
 export function closeDatabase(db) {
+    if (db === undefined || db === null)
+        return;
     db.close();
 }
 /**

package/dist/src/db/schema.js.map

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

package/dist/src/embeddings/embedding-utils.d.ts

@@ -39,4 +39,27 @@ export declare function checkTransformersAvailability(): Promise<boolean>;
  * Get the error that occurred when loading the transformers module, if any.
  */
 export declare function getTransformersLoadError(): Error | null;
+/**
+ * Cosine similarity between two vectors of equal length.
+ *
+ * SMI-4577: extracted from `EmbeddingService.cosineSimilarity` so the brute-
+ * force fallback in this module can call it directly without a class
+ * instance, and to keep `index.ts` under the 500-line cap.
+ *
+ * @throws if vectors have different lengths
+ * @returns 0 when either vector has zero magnitude
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Brute-force top-K nearest-neighbour search over an embedding map. Used as
+ * the deterministic fallback when HNSW is unavailable or explicitly disabled.
+ *
+ * SMI-4577: extracted from `EmbeddingService.findSimilarBruteForce` so the
+ * pure search algorithm doesn't need a class instance. The wrapper method on
+ * `EmbeddingService` still exists for backwards compatibility.
+ */
+export declare function findSimilarBruteForceFromMap(embeddings: Map<string, Float32Array>, queryEmbedding: Float32Array, topK: number): Array<{
+    skillId: string;
+    score: number;
+}>;
 //# sourceMappingURL=embedding-utils.d.ts.map

package/dist/src/embeddings/embedding-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding-utils.d.ts","sourceRoot":"","sources":["../../../src/embeddings/embedding-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAW7D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAuBnF;AAQD;;;GAGG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CACrD,cAAc,2BAA2B,CAAC,GAAG,IAAI,CAClD,CA2BA;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,GAAG,SAAS,CAI7D;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,OAAO,CAAC,CAGtE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,KAAK,GAAG,IAAI,CAEvD"}
+{"version":3,"file":"embedding-utils.d.ts","sourceRoot":"","sources":["../../../src/embeddings/embedding-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAW7D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAuBnF;AAQD;;;GAGG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CACrD,cAAc,2BAA2B,CAAC,GAAG,IAAI,CAClD,CA2BA;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,GAAG,SAAS,CAI7D;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,OAAO,CAAC,CAGtE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,KAAK,GAAG,IAAI,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAYzE;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACrC,cAAc,EAAE,YAAY,EAC5B,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAO3C"}

package/dist/src/embeddings/embedding-utils.js

@@ -118,4 +118,43 @@ export async function checkTransformersAvailability() {
 export function getTransformersLoadError() {
     return pipelineLoadError;
 }
+/**
+ * Cosine similarity between two vectors of equal length.
+ *
+ * SMI-4577: extracted from `EmbeddingService.cosineSimilarity` so the brute-
+ * force fallback in this module can call it directly without a class
+ * instance, and to keep `index.ts` under the 500-line cap.
+ *
+ * @throws if vectors have different lengths
+ * @returns 0 when either vector has zero magnitude
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        throw new Error('Embeddings must have same dimension');
+    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));
+}
+/**
+ * Brute-force top-K nearest-neighbour search over an embedding map. Used as
+ * the deterministic fallback when HNSW is unavailable or explicitly disabled.
+ *
+ * SMI-4577: extracted from `EmbeddingService.findSimilarBruteForce` so the
+ * pure search algorithm doesn't need a class instance. The wrapper method on
+ * `EmbeddingService` still exists for backwards compatibility.
+ */
+export function findSimilarBruteForceFromMap(embeddings, queryEmbedding, topK) {
+    const results = [];
+    for (const [skillId, embedding] of embeddings) {
+        results.push({ skillId, score: cosineSimilarity(queryEmbedding, embedding) });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, topK);
+}
 //# sourceMappingURL=embedding-utils.js.map

package/dist/src/embeddings/embedding-utils.js.map

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

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