@skillsmith/core 0.5.7 → 0.6.0

package/dist/tests/embeddings/hnsw-bench-gate.test.js

@@ -0,0 +1,117 @@
+/**
+ * SMI-4577: HNSW vs. brute-force CI gate.
+ *
+ * vitest's `bench()` blocks (in `hnsw-vs-brute-force.bench.ts`) report
+ * timings but do NOT fail CI on regression. This test mirrors that bench
+ * structure inside a `test()` so we get a hard gate:
+ *
+ *  - p99 HNSW × 5 < p99 brute-force
+ *  - recall@10 ≥ 0.95
+ *  - rss delta < 100MB after build
+ *
+ * Without this companion file the bench is decorative — see plan §"Bench gate".
+ */
+import { test, expect, beforeAll, afterAll } from 'vitest';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { EmbeddingService } from '../../src/embeddings/index.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_PATH = resolve(__dirname, 'fixtures', '14k-bench.db');
+process.env.SKILLSMITH_USE_MOCK_EMBEDDINGS = 'true';
+let service;
+const queryVectors = [];
+async function ensureFixture() {
+    if (existsSync(FIXTURE_PATH))
+        return;
+    const seedScript = resolve(__dirname, 'seed-bench.ts');
+    const result = spawnSync('npx', ['tsx', seedScript], {
+        stdio: 'inherit',
+        cwd: resolve(__dirname, '..', '..'),
+    });
+    if (result.status !== 0) {
+        throw new Error(`seed-bench failed with exit code ${result.status}`);
+    }
+}
+beforeAll(async () => {
+    await ensureFixture();
+    service = await EmbeddingService.create({ dbPath: FIXTURE_PATH, useFallback: true });
+    const all = service.getAllEmbeddings();
+    const embeddings = Array.from(all.values());
+    for (let i = 0; i < 50; i++) {
+        queryVectors.push(embeddings[(i * 271) % embeddings.length]);
+    }
+    // Warm up so the gate measures steady-state, not first-call build cost.
+    await service.findSimilar(queryVectors[0], 10);
+}, 60_000);
+afterAll(() => {
+    service?.close();
+});
+// SMI-4690: gate this on Docker. The 5x p99 ratio at sub-ms absolute brute-force
+// times is too tight for noisy macOS host pre-push (Spotlight, JIT, kernel_task).
+// CI (Docker) provides the regression coverage; running on host is duplicative.
+// See docs/internal/research/smi-4681-host-fallback-cascade.md §1.2.
+const IN_DOCKER = process.env.IS_DOCKER === 'true';
+test.skipIf(!IN_DOCKER)('HNSW must be ≥ 5x faster (p99) than brute-force AND recall@10 ≥ 0.95', async () => {
+    const ITERATIONS = 100;
+    const TOP_K = 10;
+    // brute-force p99
+    const bruteTimes = [];
+    for (let i = 0; i < ITERATIONS; i++) {
+        const start = process.hrtime.bigint();
+        service.findSimilarBruteForce(queryVectors[i % queryVectors.length], TOP_K);
+        bruteTimes.push(Number(process.hrtime.bigint() - start) / 1_000_000);
+    }
+    // HNSW p99 (with rss delta)
+    const rssBefore = process.memoryUsage().rss;
+    const hnswTimes = [];
+    for (let i = 0; i < ITERATIONS; i++) {
+        const start = process.hrtime.bigint();
+        await service.findSimilar(queryVectors[i % queryVectors.length], TOP_K);
+        hnswTimes.push(Number(process.hrtime.bigint() - start) / 1_000_000);
+    }
+    const rssAfter = process.memoryUsage().rss;
+    bruteTimes.sort((a, b) => a - b);
+    hnswTimes.sort((a, b) => a - b);
+    const p99 = (arr) => arr[Math.floor(arr.length * 0.99)] ?? arr.at(-1);
+    const p99Brute = p99(bruteTimes);
+    const p99Hnsw = p99(hnswTimes);
+    // recall@10 — score-tolerant. Mock embeddings produce many ties in the
+    // top-10 cosine band (variants of the same template share most of their
+    // text), so strict id matching undercounts. Treat an HNSW result as a
+    // "hit" when its score is within 1e-6 of *any* score in the brute-force
+    // top-10, which captures the semantic-equivalence intent of the gate.
+    let recallSum = 0;
+    let recallCount = 0;
+    const SCORE_TIE_EPSILON = 1e-6;
+    for (let i = 0; i < Math.min(50, queryVectors.length); i++) {
+        const brute = service.findSimilarBruteForce(queryVectors[i], TOP_K);
+        const hnsw = await service.findSimilar(queryVectors[i], TOP_K);
+        const bruteIds = new Set(brute.map((r) => r.skillId));
+        const bruteScores = brute.map((r) => r.score);
+        let hits = 0;
+        for (const r of hnsw) {
+            if (bruteIds.has(r.skillId)) {
+                hits++;
+            }
+            else if (bruteScores.some((s) => Math.abs(s - r.score) < SCORE_TIE_EPSILON)) {
+                hits++;
+            }
+        }
+        recallSum += hits / TOP_K;
+        recallCount++;
+    }
+    const meanRecall = recallSum / Math.max(recallCount, 1);
+    const rssDeltaMb = (rssAfter - rssBefore) / 1024 / 1024;
+    console.log(`[hnsw-bench-gate] p99 brute=${p99Brute.toFixed(3)}ms, ` +
+        `p99 hnsw=${p99Hnsw.toFixed(3)}ms, ` +
+        `speedup=${(p99Brute / Math.max(p99Hnsw, 0.001)).toFixed(2)}x, ` +
+        `recall@10=${meanRecall.toFixed(3)}, ` +
+        `rss delta=${rssDeltaMb.toFixed(1)}MB`);
+    expect(p99Hnsw * 5).toBeLessThan(p99Brute);
+    expect(meanRecall).toBeGreaterThanOrEqual(0.95);
+    // rss can be negative under GC; clamp to assert "no runaway growth".
+    expect(rssDeltaMb).toBeLessThan(100);
+}, 120_000);
+//# sourceMappingURL=hnsw-bench-gate.test.js.map

package/dist/tests/embeddings/hnsw-bench-gate.test.js.map

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

package/dist/tests/embeddings/hnsw-integration.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SMI-4577: HNSW + EmbeddingService integration test.
+ *
+ * Asserts:
+ *  - `findSimilar` returns the same top-1 as the brute-force fallback
+ *  - recall@10 ≥ 0.95 across 50 query iterations
+ *  - the on-disk cache (`~/.skillsmith/cache/hnsw-{model}.bin`) is created
+ *    after first call
+ *  - deleting the cache forces a rebuild on the next call (no crash)
+ *
+ * Uses a temp `HOME` to keep the cache out of the user's real `~/.skillsmith/`.
+ */
+export {};
+//# sourceMappingURL=hnsw-integration.test.d.ts.map

package/dist/tests/embeddings/hnsw-integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-integration.test.d.ts","sourceRoot":"","sources":["../../../tests/embeddings/hnsw-integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/tests/embeddings/hnsw-integration.test.js

@@ -0,0 +1,160 @@
+/**
+ * SMI-4577: HNSW + EmbeddingService integration test.
+ *
+ * Asserts:
+ *  - `findSimilar` returns the same top-1 as the brute-force fallback
+ *  - recall@10 ≥ 0.95 across 50 query iterations
+ *  - the on-disk cache (`~/.skillsmith/cache/hnsw-{model}.bin`) is created
+ *    after first call
+ *  - deleting the cache forces a rebuild on the next call (no crash)
+ *
+ * Uses a temp `HOME` to keep the cache out of the user's real `~/.skillsmith/`.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, rmSync, unlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { EmbeddingService } from '../../src/embeddings/index.js';
+const MODEL_NAME_SAFE = 'Xenova__all-MiniLM-L6-v2';
+// SMI-4691: hnswlib-node is an optionalDependency. When the native binding is
+// unavailable (e.g. macOS host without the postinstall step), EmbeddingService
+// silently falls through to brute-force and never persists a cache file. The
+// cache-write assertion is only meaningful when HNSW is actually loaded.
+const HNSW_AVAILABLE = (() => {
+    try {
+        createRequire(import.meta.url)('hnswlib-node');
+        return true;
+    }
+    catch {
+        return false;
+    }
+})();
+describe('HNSW + EmbeddingService integration (SMI-4577)', () => {
+    let tmpHome;
+    let originalHome;
+    let originalCacheOverride;
+    let service;
+    let dbPath;
+    beforeEach(async () => {
+        tmpHome = join(tmpdir(), `skillsmith-hnsw-int-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(tmpHome, { recursive: true });
+        originalHome = process.env.HOME;
+        process.env.HOME = tmpHome;
+        // SMI-4691: HOME stub is ignored by os.homedir() on macOS (getpwuid path).
+        // Pin getCacheDir() to the temp tree explicitly via the override env.
+        originalCacheOverride = process.env.SKILLSMITH_CACHE_DIR_OVERRIDE;
+        process.env.SKILLSMITH_CACHE_DIR_OVERRIDE = join(tmpHome, '.skillsmith', 'cache');
+        process.env.SKILLSMITH_USE_MOCK_EMBEDDINGS = 'true';
+        delete process.env.SKILLSMITH_USE_HNSW;
+        dbPath = join(tmpHome, 'skills.db');
+        service = await EmbeddingService.create({ dbPath, useFallback: true });
+        // Seed 100 deterministic embeddings.
+        const skills = Array.from({ length: 100 }, (_, i) => ({
+            id: `skill-${i}`,
+            text: `Skill ${i} category ${i % 7} description ${i % 13}`,
+        }));
+        const batch = await service.embedBatch(skills);
+        for (const { skillId, embedding, text } of batch) {
+            service.storeEmbedding(skillId, embedding, text);
+        }
+    });
+    afterEach(() => {
+        service?.close();
+        if (originalHome !== undefined) {
+            process.env.HOME = originalHome;
+        }
+        else {
+            delete process.env.HOME;
+        }
+        if (originalCacheOverride !== undefined) {
+            process.env.SKILLSMITH_CACHE_DIR_OVERRIDE = originalCacheOverride;
+        }
+        else {
+            delete process.env.SKILLSMITH_CACHE_DIR_OVERRIDE;
+        }
+        if (existsSync(tmpHome)) {
+            try {
+                rmSync(tmpHome, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+    });
+    it('findSimilar produces deterministic top-1 matching brute-force', async () => {
+        const all = service.getAllEmbeddings();
+        const someVector = Array.from(all.values())[0];
+        const hnsw = await service.findSimilar(someVector, 10);
+        const brute = service.findSimilarBruteForce(someVector, 10);
+        expect(hnsw.length).toBe(brute.length);
+        expect(hnsw[0]?.skillId).toBe(brute[0]?.skillId);
+    });
+    it('recall@10 ≥ 0.95 across 50 query iterations (score-tolerant)', async () => {
+        // Mock embeddings produce many tied cosine scores in the top-10 band
+        // (variants of the same template share most of their text). Treat
+        // HNSW hits within `1e-6` of any brute-force top-10 score as
+        // semantically equivalent to capture the intent of the gate.
+        const all = service.getAllEmbeddings();
+        const vectors = Array.from(all.values());
+        let sum = 0;
+        let count = 0;
+        const SCORE_TIE_EPSILON = 1e-6;
+        for (let i = 0; i < 50; i++) {
+            const q = vectors[(i * 31) % vectors.length];
+            const brute = service.findSimilarBruteForce(q, 10);
+            const hnsw = await service.findSimilar(q, 10);
+            const bruteIds = new Set(brute.map((r) => r.skillId));
+            const bruteScores = brute.map((r) => r.score);
+            let hits = 0;
+            for (const r of hnsw) {
+                if (bruteIds.has(r.skillId)) {
+                    hits++;
+                }
+                else if (bruteScores.some((s) => Math.abs(s - r.score) < SCORE_TIE_EPSILON)) {
+                    hits++;
+                }
+            }
+            sum += hits / 10;
+            count++;
+        }
+        expect(sum / count).toBeGreaterThanOrEqual(0.95);
+    });
+    it.skipIf(!HNSW_AVAILABLE)('writes ~/.skillsmith/cache/hnsw-{model}.bin after first call', async () => {
+        const all = service.getAllEmbeddings();
+        const someVector = Array.from(all.values())[0];
+        await service.findSimilar(someVector, 10);
+        // Force the debounced persist.
+        service.close();
+        const cacheBin = join(tmpHome, '.skillsmith', 'cache', `hnsw-${MODEL_NAME_SAFE}.bin`);
+        expect(existsSync(cacheBin)).toBe(true);
+    });
+    it('rebuilds index when cache is deleted (no crash)', async () => {
+        const all = service.getAllEmbeddings();
+        const someVector = Array.from(all.values())[0];
+        await service.findSimilar(someVector, 10);
+        service.close();
+        const cacheBin = join(tmpHome, '.skillsmith', 'cache', `hnsw-${MODEL_NAME_SAFE}.bin`);
+        if (existsSync(cacheBin)) {
+            unlinkSync(cacheBin);
+        }
+        // New service should rebuild from SQLite without erroring.
+        const service2 = await EmbeddingService.create({ dbPath, useFallback: true });
+        const result = await service2.findSimilar(someVector, 10);
+        expect(result.length).toBeGreaterThan(0);
+        service2.close();
+    });
+    it('honours SKILLSMITH_USE_HNSW=false (brute-force only path)', async () => {
+        process.env.SKILLSMITH_USE_HNSW = 'false';
+        try {
+            const all = service.getAllEmbeddings();
+            const someVector = Array.from(all.values())[0];
+            const result = await service.findSimilar(someVector, 5);
+            expect(result.length).toBe(5);
+        }
+        finally {
+            delete process.env.SKILLSMITH_USE_HNSW;
+        }
+    });
+});
+//# sourceMappingURL=hnsw-integration.test.js.map

package/dist/tests/embeddings/hnsw-integration.test.js.map

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

package/dist/tests/embeddings/hnsw-vs-brute-force.bench.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SMI-4577: HNSW vs. brute-force microbench.
+ *
+ * Reports `bench()` timings for both backends. **Does NOT fail CI on
+ * regression** — vitest's bench mode is reporting-only. The hard CI gate
+ * lives in `hnsw-bench-gate.test.ts` which mirrors the same workload inside
+ * a `test()` and asserts the 5x p99 + recall@10 + rss-delta thresholds.
+ *
+ * Memory tracked via `process.memoryUsage().rss` (NOT `heapUsed` — hnswlib's
+ * graph lives in C++ memory and would undercount).
+ *
+ * Run: `docker exec skillsmith-dev-1 npm run bench:hnsw --workspace=@skillsmith/core`
+ */
+export {};
+//# sourceMappingURL=hnsw-vs-brute-force.bench.d.ts.map

package/dist/tests/embeddings/hnsw-vs-brute-force.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-vs-brute-force.bench.d.ts","sourceRoot":"","sources":["../../../tests/embeddings/hnsw-vs-brute-force.bench.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/tests/embeddings/hnsw-vs-brute-force.bench.js

@@ -0,0 +1,64 @@
+/**
+ * SMI-4577: HNSW vs. brute-force microbench.
+ *
+ * Reports `bench()` timings for both backends. **Does NOT fail CI on
+ * regression** — vitest's bench mode is reporting-only. The hard CI gate
+ * lives in `hnsw-bench-gate.test.ts` which mirrors the same workload inside
+ * a `test()` and asserts the 5x p99 + recall@10 + rss-delta thresholds.
+ *
+ * Memory tracked via `process.memoryUsage().rss` (NOT `heapUsed` — hnswlib's
+ * graph lives in C++ memory and would undercount).
+ *
+ * Run: `docker exec skillsmith-dev-1 npm run bench:hnsw --workspace=@skillsmith/core`
+ */
+import { describe, bench, beforeAll, afterAll } from 'vitest';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { EmbeddingService } from '../../src/embeddings/index.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_PATH = resolve(__dirname, 'fixtures', '14k-bench.db');
+// Forced to mock embeddings throughout — the bench exercises the search
+// backend, not the model.
+process.env.SKILLSMITH_USE_MOCK_EMBEDDINGS = 'true';
+let service;
+const queryVectors = [];
+async function ensureFixture() {
+    if (existsSync(FIXTURE_PATH))
+        return;
+    const seedScript = resolve(__dirname, 'seed-bench.ts');
+    const result = spawnSync('npx', ['tsx', seedScript], {
+        stdio: 'inherit',
+        cwd: resolve(__dirname, '..', '..'),
+    });
+    if (result.status !== 0) {
+        throw new Error(`seed-bench failed with exit code ${result.status}`);
+    }
+}
+beforeAll(async () => {
+    await ensureFixture();
+    service = await EmbeddingService.create({ dbPath: FIXTURE_PATH, useFallback: true });
+    // 50 random queries — enough samples for stable p99 without dominating
+    // bench warmup. Pulled from the same vector space so neighbourhoods exist.
+    const allEmbeddings = service.getAllEmbeddings();
+    const embeddings = Array.from(allEmbeddings.values());
+    for (let i = 0; i < 50; i++) {
+        queryVectors.push(embeddings[(i * 271) % embeddings.length]);
+    }
+    // Warm up the HNSW index so the bench measures steady-state search, not
+    // first-call build cost.
+    await service.findSimilar(queryVectors[0], 10);
+});
+afterAll(() => {
+    service?.close();
+});
+describe('findSimilar @ 14k vectors', () => {
+    bench('brute-force findSimilar topK=10', () => {
+        service.findSimilarBruteForce(queryVectors[Math.floor(Math.random() * queryVectors.length)], 10);
+    }, { iterations: 100, warmupIterations: 10 });
+    bench('hnsw findSimilar topK=10', async () => {
+        await service.findSimilar(queryVectors[Math.floor(Math.random() * queryVectors.length)], 10);
+    }, { iterations: 100, warmupIterations: 10 });
+});
+//# sourceMappingURL=hnsw-vs-brute-force.bench.js.map

package/dist/tests/embeddings/hnsw-vs-brute-force.bench.js.map

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

package/dist/tests/embeddings/seed-bench.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SMI-4577: Seed a synthetic 14k-skill embedding fixture for the HNSW bench.
+ *
+ * Generates deterministic mock embeddings via `EmbeddingService` (with
+ * `SKILLSMITH_USE_MOCK_EMBEDDINGS=true` for speed) and writes them to a
+ * SQLite cache that the bench reads back without network/model load.
+ *
+ * Run via: `npm run bench:hnsw:seed --workspace=@skillsmith/core`
+ *
+ * The fixture is gitignored (see top-level `.gitignore`) so each environment
+ * regenerates it on first bench run. CI invokes this as a `pretest` hook so
+ * the bench can boot from a clean checkout.
+ */
+export {};
+//# sourceMappingURL=seed-bench.d.ts.map

package/dist/tests/embeddings/seed-bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-bench.d.ts","sourceRoot":"","sources":["../../../tests/embeddings/seed-bench.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/tests/embeddings/seed-bench.js

@@ -0,0 +1,61 @@
+/**
+ * SMI-4577: Seed a synthetic 14k-skill embedding fixture for the HNSW bench.
+ *
+ * Generates deterministic mock embeddings via `EmbeddingService` (with
+ * `SKILLSMITH_USE_MOCK_EMBEDDINGS=true` for speed) and writes them to a
+ * SQLite cache that the bench reads back without network/model load.
+ *
+ * Run via: `npm run bench:hnsw:seed --workspace=@skillsmith/core`
+ *
+ * The fixture is gitignored (see top-level `.gitignore`) so each environment
+ * regenerates it on first bench run. CI invokes this as a `pretest` hook so
+ * the bench can boot from a clean checkout.
+ */
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EmbeddingService } from '../../src/embeddings/index.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_PATH = resolve(__dirname, 'fixtures', '14k-bench.db');
+const TARGET_COUNT = 14_000;
+async function main() {
+    // Force mock-embedding mode so the seed runs in <1s instead of pulling
+    // the all-MiniLM-L6-v2 model. The bench reads vectors back as raw
+    // Float32Array — semantic correctness is checked separately in the
+    // integration test.
+    process.env.SKILLSMITH_USE_MOCK_EMBEDDINGS = 'true';
+    mkdirSync(dirname(FIXTURE_PATH), { recursive: true });
+    if (existsSync(FIXTURE_PATH)) {
+        rmSync(FIXTURE_PATH);
+    }
+    const service = await EmbeddingService.create({ dbPath: FIXTURE_PATH, useFallback: true });
+    // Generate 14k synthetic skills. We oversample 100 base templates with
+    // numeric suffixes so vectors form natural clusters (a few "neighbours"
+    // per query) rather than uniform random — gives the bench a realistic
+    // recall workload.
+    const templates = Array.from({ length: 100 }, (_, i) => ({
+        id: `template-${i}`,
+        text: `Skill template ${i}: testing automation framework category ${i % 12} ${i % 7}`,
+    }));
+    const skills = [];
+    for (let i = 0; i < TARGET_COUNT; i++) {
+        const t = templates[i % templates.length];
+        skills.push({
+            id: `${t.id}-variant-${Math.floor(i / templates.length)}`,
+            text: `${t.text} variant ${i}`,
+        });
+    }
+    const start = Date.now();
+    const batch = await service.embedBatch(skills.map(({ id, text }) => ({ id, text })));
+    for (const { skillId, embedding, text } of batch) {
+        service.storeEmbedding(skillId, embedding, text);
+    }
+    const elapsedMs = Date.now() - start;
+    service.close();
+    console.log(`[seed-bench] wrote ${batch.length} embeddings to ${FIXTURE_PATH} in ${elapsedMs}ms`);
+}
+main().catch((err) => {
+    console.error('[seed-bench] failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=seed-bench.js.map

package/dist/tests/embeddings/seed-bench.js.map

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

package/dist/tests/helpers/database.d.ts

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Test database helpers — prevents "no such table" for migrated tables
  * @see SMI-2749
+ * @see SMI-4756 — async variant added to support WASM fallback in post-merge-verify
  *
  * Use createTestDatabase() instead of createDatabase(':memory:') whenever tests
  * need tables that only exist in migration files (e.g. skill_versions).
@@ -15,6 +16,11 @@
  * createTestDatabase() iterates MIGRATIONS directly (no version gate) so every
  * migration's SQL runs unconditionally. New migrations added to MIGRATIONS are
  * automatically included — no change required here.
+ *
+ * SMI-4756: createTestDatabase is now async. It uses createDatabaseAsync() so the
+ * sql.js WASM driver is used automatically when better-sqlite3 native bindings are
+ * unavailable (e.g. in post-merge-verify CI where the native module is not rebuilt
+ * for the container platform). Callers must await the result and use async beforeEach.
  */
 import type { Database } from '../../src/db/database-interface.js';
 export { closeDatabase } from '../../src/db/schema.js';
@@ -26,7 +32,10 @@ export type { Database } from '../../src/db/database-interface.js';
  * sync_config, sync_history). Forward-compatible: new migrations added to
  * MIGRATIONS are included automatically.
  *
- * @returns Database with full schema + all migrations applied
+ * SMI-4756: Returns a Promise so the sql.js WASM driver is used automatically
+ * when better-sqlite3 native bindings are unavailable. Callers must await.
+ *
+ * @returns Promise resolving to a Database with full schema + all migrations applied
  */
-export declare function createTestDatabase(): Database;
+export declare function createTestDatabase(): Promise<Database>;
 //# sourceMappingURL=database.d.ts.map

package/dist/tests/helpers/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../tests/helpers/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAGlE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,YAAY,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAElE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAsB7C"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../tests/helpers/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAGlE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,YAAY,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAElE;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,CA4B5D"}

package/dist/tests/helpers/database.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Test database helpers — prevents "no such table" for migrated tables
  * @see SMI-2749
+ * @see SMI-4756 — async variant added to support WASM fallback in post-merge-verify
  *
  * Use createTestDatabase() instead of createDatabase(':memory:') whenever tests
  * need tables that only exist in migration files (e.g. skill_versions).
@@ -15,8 +16,13 @@
  * createTestDatabase() iterates MIGRATIONS directly (no version gate) so every
  * migration's SQL runs unconditionally. New migrations added to MIGRATIONS are
  * automatically included — no change required here.
+ *
+ * SMI-4756: createTestDatabase is now async. It uses createDatabaseAsync() so the
+ * sql.js WASM driver is used automatically when better-sqlite3 native bindings are
+ * unavailable (e.g. in post-merge-verify CI where the native module is not rebuilt
+ * for the container platform). Callers must await the result and use async beforeEach.
  */
-import { createDatabase, MIGRATIONS } from '../../src/db/schema.js';
+import { createDatabaseAsync, initializeSchema, MIGRATIONS } from '../../src/db/schema.js';
 // Re-exported for test convenience — tests only need to import from this module
 export { closeDatabase } from '../../src/db/schema.js';
 /**
@@ -26,12 +32,16 @@ export { closeDatabase } from '../../src/db/schema.js';
  * sync_config, sync_history). Forward-compatible: new migrations added to
  * MIGRATIONS are included automatically.
  *
- * @returns Database with full schema + all migrations applied
+ * SMI-4756: Returns a Promise so the sql.js WASM driver is used automatically
+ * when better-sqlite3 native bindings are unavailable. Callers must await.
+ *
+ * @returns Promise resolving to a Database with full schema + all migrations applied
  */
-export function createTestDatabase() {
-    // createDatabase() calls initializeSchema() — runs SCHEMA_SQL (handling FTS5 triggers
-    // and multi-statement SQL correctly) and stamps SCHEMA_VERSION in schema_version.
-    const db = createDatabase();
+export async function createTestDatabase() {
+    // createDatabaseAsync() + initializeSchema() — async path uses WASM fallback
+    // when better-sqlite3 native module is unavailable (cross-platform / CI).
+    const db = await createDatabaseAsync();
+    initializeSchema(db);
     // Run all migrations unconditionally (no version gate) so tables that only exist in
     // migration SQL (not SCHEMA_SQL) are created. db.exec() handles multi-statement SQL
     // natively — no semicolon split needed.
@@ -40,7 +50,13 @@ export function createTestDatabase() {
     // already included in the canonical SCHEMA_SQL. Those errors are expected and safe.
     for (const migration of MIGRATIONS) {
         try {
-            db.exec(migration.sql);
+            // SMI-4665: migrations may carry an `apply` function instead of `sql`.
+            if (migration.apply) {
+                migration.apply(db);
+            }
+            else if (migration.sql !== undefined) {
+                db.exec(migration.sql);
+            }
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);

package/dist/tests/helpers/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../tests/helpers/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGnE,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAGtD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,sFAAsF;IACtF,kFAAkF;IAClF,MAAM,EAAE,GAAG,cAAc,EAAE,CAAA;IAE3B,oFAAoF;IACpF,oFAAoF;IACpF,wCAAwC;IACxC,EAAE;IACF,iFAAiF;IACjF,oFAAoF;IACpF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAClE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBAAE,MAAM,KAAK,CAAA;QACpD,CAAC;QACD,EAAE,CAAC,OAAO,CAAC,4DAA4D,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACjG,CAAC;IAED,OAAO,EAAE,CAAA;AACX,CAAC"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../tests/helpers/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAG1F,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAGtD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,GAAG,MAAM,mBAAmB,EAAE,CAAA;IACtC,gBAAgB,CAAC,EAAE,CAAC,CAAA;IAEpB,oFAAoF;IACpF,oFAAoF;IACpF,wCAAwC;IACxC,EAAE;IACF,iFAAiF;IACjF,oFAAoF;IACpF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,uEAAuE;YACvE,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;gBACpB,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;YACrB,CAAC;iBAAM,IAAI,SAAS,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBACvC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;YACxB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAClE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBAAE,MAAM,KAAK,CAAA;QACpD,CAAC;QACD,EAAE,CAAC,OAAO,CAAC,4DAA4D,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACjG,CAAC;IAED,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/tests/install/fan-out.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fan-out.test.d.ts.map

package/dist/tests/install/fan-out.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.test.d.ts","sourceRoot":"","sources":["../../../tests/install/fan-out.test.ts"],"names":[],"mappings":""}