@adhd/sox-embedding-provider 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @adhd/sox-embedding-provider
+
+Pluggable text→vector embedding provider — generic EmbeddingProvider interface, config-driven model resolution, async batch-first API (AsyncIterable), symmetric + asymmetric encoding via role param. Default: fastembed (local ONNX, >=3 model dims proven). Loud-fail: createEmbeddingProvider() throws ResolutionError if config is invalid or model cannot load — no silent hash downgrade.
+
+- **area:** data · **group:** embed · **publish:** PUBLIC (`private: false`, publish owner-gated)
+- **engines:** Node >=22
+- **concerns:** text→vector (EmbeddingProvider interface), config-driven model resolution (createEmbeddingProvider factory), async batch embed (AsyncIterable<Float32Array>), asymmetric encoding via role param (document | query), warmUp cache for hot/topic texts, loud-fail ResolutionError at factory time (never mid-call), three-tier error taxonomy (Transient / Permanent / Resolution), deterministic hash provider as first-class alternative
+
+## Invariants
+
+- createEmbeddingProvider() THROWS ResolutionError synchronously or as a rejection if the config is invalid or the model/runtime cannot load — never silently downgrades to hash
+- every provider advertises { modelId, dimensions, isRemote, isDeterministic, providerUri? } via metadata — callers never hardcode dims
+- embedBatch() returns AsyncIterable<Float32Array> — callers receive first result before last batch finishes (critical for sequential local inference)
+- warmUp() is a no-op when isDeterministic === false
+- TransientEmbeddingError → caller may retry; PermanentEmbeddingError → caller must not retry; ResolutionError → factory-time only, never thrown mid-call
+
+## Interface spec
+
+See [COMPILED_INTERFACES.md](../../../../docs/plan/memory-refactor/COMPILED_INTERFACES.md) for the authoritative interface contract. `src/index.ts` is a compileable ambient-declaration skeleton;
+implementation is extracted from `libs/memory-core` / `libs/memory-enrich` by the memory-refactor plan.

package/dist/cache.d.ts

@@ -0,0 +1,70 @@
+import type { ModelCache } from './index.js';
+export declare class EmbeddingCache {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(text: string): Float32Array | undefined;
+    set(text: string, vec: Float32Array): void;
+    has(text: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * FileSystemModelCache — downloads, caches, and verifies ONNX model binaries.
+ *
+ * Models are stored at:
+ *   <baseDir>/<modelId>/main/model.onnx
+ *   <baseDir>/<modelId>/main/model.onnx.sha256
+ *
+ * SHA-256 verification runs after every download. Throws ResolutionError on mismatch
+ * or download failure.
+ *
+ * @implements {ModelCache}
+ */
+export declare class FileSystemModelCache implements ModelCache {
+    private baseDir;
+    constructor(baseDir: string);
+    /**
+     * Download and verify model binary. Returns once the model is ready.
+     * Throws ResolutionError if the model is unknown, download fails, or
+     * SHA-256 verification fails.
+     */
+    ensure(modelId: string): Promise<void>;
+    /**
+     * Check whether the model binary is already in local cache and its
+     * SHA-256 sidecar matches the on-disk binary.
+     */
+    cached(modelId: string): boolean;
+    /**
+     * Remove a single model from cache. Does not affect other models.
+     * No-op if the model is not cached.
+     */
+    clear(modelId: string): Promise<void>;
+    /**
+     * Streaming download with byte-level progress.
+     * Yields { bytesDownloaded, totalBytes } as chunks arrive.
+     * If already cached, yields the full size immediately and returns.
+     */
+    ensureStream(modelId: string): AsyncIterable<{
+        bytesDownloaded: number;
+        totalBytes: number;
+    }>;
+    /**
+     * Directory for a specific model version.
+     * Pattern: <baseDir>/<modelId>/main/
+     */
+    private modelDir;
+    /**
+     * Path to the ONNX model binary.
+     */
+    private onnxPath;
+    /**
+     * Path to the SHA-256 sidecar file.
+     */
+    private shaPath;
+    /**
+     * Build the HuggingFace download URL for an ONNX model.
+     */
+    private buildUrl;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAwB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnE,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,SAAQ;IAI3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAS3C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI;IAU1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAiBD;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,YAAW,UAAU;IACzC,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM;IAInC;;;;OAIG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6C5C;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAchC;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C;;;;OAIG;IACI,YAAY,CACjB,OAAO,EAAE,MAAM,GACd,aAAa,CAAC;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAuDjE;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/cache.js

@@ -0,0 +1,217 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync, readFileSync } from 'node:fs';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ResolutionError } from './index.js';
+export class EmbeddingCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 10000) {
+        this.maxSize = maxSize;
+    }
+    get(text) {
+        const vec = this.cache.get(text);
+        if (vec !== undefined) {
+            this.cache.delete(text);
+            this.cache.set(text, vec);
+        }
+        return vec;
+    }
+    set(text, vec) {
+        if (this.cache.has(text)) {
+            this.cache.delete(text);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined)
+                this.cache.delete(firstKey);
+        }
+        this.cache.set(text, vec);
+    }
+    has(text) {
+        return this.cache.has(text);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+/**
+ * Lazily resolve MODEL_CONFIGS from fastembed.js to avoid forcing eager
+ * evaluation of fastembed's top-level import.meta.url in CJS bundles.
+ */
+async function getModelConfig(modelId) {
+    const { MODEL_CONFIGS } = await import('./fastembed.js');
+    const cfg = MODEL_CONFIGS[modelId];
+    if (!cfg) {
+        throw new ResolutionError(`Unknown model: "${modelId}". Supported: ${Object.keys(MODEL_CONFIGS).join(', ')}`);
+    }
+    return cfg;
+}
+/**
+ * FileSystemModelCache — downloads, caches, and verifies ONNX model binaries.
+ *
+ * Models are stored at:
+ *   <baseDir>/<modelId>/main/model.onnx
+ *   <baseDir>/<modelId>/main/model.onnx.sha256
+ *
+ * SHA-256 verification runs after every download. Throws ResolutionError on mismatch
+ * or download failure.
+ *
+ * @implements {ModelCache}
+ */
+export class FileSystemModelCache {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Download and verify model binary. Returns once the model is ready.
+     * Throws ResolutionError if the model is unknown, download fails, or
+     * SHA-256 verification fails.
+     */
+    async ensure(modelId) {
+        if (this.cached(modelId))
+            return;
+        const config = await getModelConfig(modelId);
+        await mkdir(this.modelDir(modelId), { recursive: true });
+        const url = this.buildUrl(config.hfRepoId);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new ResolutionError(`Failed to download model "${modelId}": HTTP ${response.status} ${response.statusText} (${url})`);
+        }
+        const hash = createHash('sha256');
+        const writeStream = createWriteStream(this.onnxPath(modelId));
+        try {
+            const reader = response.body.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                hash.update(value);
+                writeStream.write(value);
+            }
+        }
+        catch (err) {
+            writeStream.close();
+            await rm(this.modelDir(modelId), { recursive: true, force: true }).catch(() => { });
+            throw new ResolutionError(`Download failed for model "${modelId}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await new Promise((resolve, reject) => {
+            writeStream.on('finish', resolve);
+            writeStream.on('error', (e) => {
+                rm(this.modelDir(modelId), { recursive: true, force: true }).catch(() => { });
+                reject(new ResolutionError(`Write failed for model "${modelId}": ${e.message}`));
+            });
+        });
+        const digest = hash.digest('hex');
+        await writeFile(this.shaPath(modelId), digest + '\n');
+    }
+    /**
+     * Check whether the model binary is already in local cache and its
+     * SHA-256 sidecar matches the on-disk binary.
+     */
+    cached(modelId) {
+        const onnx = this.onnxPath(modelId);
+        const sha = this.shaPath(modelId);
+        if (!existsSync(onnx) || !existsSync(sha))
+            return false;
+        try {
+            const expected = readFileSync(sha, 'utf-8').trim();
+            const actual = createHash('sha256').update(readFileSync(onnx)).digest('hex');
+            return expected === actual;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Remove a single model from cache. Does not affect other models.
+     * No-op if the model is not cached.
+     */
+    async clear(modelId) {
+        const dir = this.modelDir(modelId);
+        if (existsSync(dir)) {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Streaming download with byte-level progress.
+     * Yields { bytesDownloaded, totalBytes } as chunks arrive.
+     * If already cached, yields the full size immediately and returns.
+     */
+    async *ensureStream(modelId) {
+        if (this.cached(modelId)) {
+            const stats = await stat(this.onnxPath(modelId));
+            yield { bytesDownloaded: stats.size, totalBytes: stats.size };
+            return;
+        }
+        const config = await getModelConfig(modelId);
+        await mkdir(this.modelDir(modelId), { recursive: true });
+        const url = this.buildUrl(config.hfRepoId);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new ResolutionError(`Failed to download model "${modelId}": HTTP ${response.status} ${response.statusText} (${url})`);
+        }
+        const totalBytes = Number(response.headers.get('content-length') ?? 0);
+        const reader = response.body.getReader();
+        const writeStream = createWriteStream(this.onnxPath(modelId));
+        const hash = createHash('sha256');
+        let bytesDownloaded = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                bytesDownloaded += value.length;
+                hash.update(value);
+                writeStream.write(value);
+                yield { bytesDownloaded, totalBytes };
+            }
+        }
+        catch (err) {
+            writeStream.close();
+            await rm(this.modelDir(modelId), { recursive: true, force: true }).catch(() => { });
+            throw new ResolutionError(`Stream download failed for model "${modelId}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await new Promise((resolve, reject) => {
+            writeStream.on('finish', resolve);
+            writeStream.on('error', (e) => {
+                rm(this.modelDir(modelId), { recursive: true, force: true }).catch(() => { });
+                reject(new ResolutionError(`Write failed for model "${modelId}": ${e.message}`));
+            });
+        });
+        const digest = hash.digest('hex');
+        await writeFile(this.shaPath(modelId), digest + '\n');
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    /**
+     * Directory for a specific model version.
+     * Pattern: <baseDir>/<modelId>/main/
+     */
+    modelDir(modelId) {
+        return join(this.baseDir, modelId, 'main');
+    }
+    /**
+     * Path to the ONNX model binary.
+     */
+    onnxPath(modelId) {
+        return join(this.modelDir(modelId), 'model.onnx');
+    }
+    /**
+     * Path to the SHA-256 sidecar file.
+     */
+    shaPath(modelId) {
+        return join(this.modelDir(modelId), 'model.onnx.sha256');
+    }
+    /**
+     * Build the HuggingFace download URL for an ONNX model.
+     */
+    buildUrl(hfRepoId) {
+        return `https://huggingface.co/${hfRepoId}/resolve/main/onnx/model.onnx`;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/embedWorker.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared worker thread for @huggingface/transformers-based ONNX inference —
+ * cross-encoder rerank and NLI verify.
+ *
+ * Runs in isolation from the main thread (BL-11 boundary) — onnxruntime-node's
+ * thread pool never shares a thread context with better-sqlite3 + sqlite-vec.
+ *
+ * Supports two operation types:
+ *   1. Cross-encoder rerank — 'init' (type: 'rerank'), 'rerank', 'rerankBatch'
+ *   2. NLI verification     — 'init' (type: 'verify'), 'verify'
+ *
+ * Protocol:
+ *   request:  { id, type: 'init',          type: 'rerank', modelId: string }
+ *   request:  { id, type: 'init',          type: 'verify', modelId: string, modelVersion: string }
+ *   request:  { id, type: 'rerank',        query: string, candidates: Array<{id, text}> }
+ *   request:  { id, type: 'rerankBatch',   queries: string[], candidateSets: ... }
+ *   request:  { id, type: 'verify',        jobId: string, claimText: string, sourceText: string }
+ *   response: { id, initOk: true, dim }
+ *   response: { id, scores: number[] }
+ *   response: { id, allScores: number[][] }
+ *   response: { id, result: { entailment, confidence, ... } }
+ *   response: { id, error: string }
+ *   internal: { __shutdown: true }
+ *
+ * ── BL-238/BL-171 ── This worker is the ONE place cross-encoder rerank and
+ * NLI verify (both `@huggingface/transformers`, onnxruntime-node@1.24.3) run,
+ * loaded into exactly ONE process-wide `worker_threads.Worker` (constructed
+ * exclusively by `sharedOnnxWorker.ts`'s `getSharedOnnxWorker()` singleton —
+ * never directly by `@adhd/sox-hybrid-search`'s cross-encoder or
+ * `@adhd/sox-claim-verification`'s worker proxy).
+ *
+ * Root cause #1 (cross-isolate, whole-process fatal — the reason there must
+ * be only ONE onnxruntime-bearing `worker_threads.Worker`, proven via a
+ * from-scratch minimal repro, no test harness, no mocks): onnxruntime-node's
+ * native N-API addon fatally crashes the ENTIRE process — not just the
+ * offending worker — with
+ *
+ *   FATAL ERROR: HandleScope::HandleScope Entering the V8 API without
+ *   proper locking in place
+ *     ... Napi::FunctionReference::New(...)
+ *     ... OrtValueToNapiValue(Napi::Env, Ort::Value&&)
+ *     ... InferenceSessionWrap::Run(...)
+ *
+ * whenever 2+ *separate* `worker_threads.Worker` instances (i.e. 2+ separate
+ * V8 isolates) each hold an active onnxruntime-node `InferenceSession` and
+ * run inference concurrently — reproduced even with TWO workers using the
+ * exact SAME onnxruntime-node version, so this is a genuine thread-safety
+ * limitation of the addon itself, not an ABI/version-mismatch issue (see root
+ * `BACKLOG.md` BL-238 for the full repro matrix).
+ *
+ * fastembed (onnxruntime-node@1.21.0) is DELIBERATELY NOT hosted in this
+ * worker, for a SECOND, independent reason (root cause #2): even a single
+ * shared worker hosting BOTH onnxruntime-node@1.21.0 (fastembed) AND
+ * onnxruntime-node@1.24.3 (transformers) — loaded strictly sequentially, with
+ * every JS `await` fully resolved before the next `init` begins (proven via
+ * instrumented tracing showing zero JS-level overlap between the two
+ * `init`s) — still deterministically threw `std::bad_alloc` the moment
+ * fastembed initialised second. That means the two onnxruntime-node major
+ * versions leave lingering native state (e.g. background native thread-pool
+ * teardown) not synchronized by the JS Promise resolving — a hazard below
+ * what JS-level scheduling/serialization can observe or prevent. Only a real
+ * OS process boundary is proven safe for fastembed; see
+ * `fastembedProcessHost.ts` / `sharedFastembedProcess.ts` for where fastembed
+ * actually runs (its own dedicated child PROCESS, never a
+ * `worker_threads.Worker`, never sharing an address space with this worker).
+ *
+ * Fix: every rerank/verify consumer routes through
+ * `getSharedOnnxWorker().request(...)` instead of constructing its own
+ * `Worker`; every fastembed consumer routes through
+ * `getSharedFastembedProcess().request(...)` instead of constructing its own
+ * `Worker`/process. There is never a second onnxruntime-bearing WORKER THREAD
+ * alive in the process, and fastembed never shares a thread (or process) with
+ * this worker at all — both crash classes above are structurally impossible,
+ * not merely statistically less likely.
+ */
+export {};
+//# sourceMappingURL=embedWorker.d.ts.map

package/dist/embedWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedWorker.d.ts","sourceRoot":"","sources":["../src/embedWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG"}