@adhd/sox-embedding-provider 0.1.0

package/dist/sharedOnnxWorker.js

@@ -0,0 +1,255 @@
+/**
+ * Process-wide singleton client for the ONE onnxruntime-native-bearing
+ * `worker_threads.Worker` allowed to exist in this process (BL-238/BL-171).
+ *
+ * This worker (`embedWorker.ts`) hosts the MS-MARCO cross-encoder reranker
+ * (`@adhd/sox-hybrid-search`) and the DeBERTa NLI verifier
+ * (`@adhd/sox-claim-verification`) — both driven by
+ * `@huggingface/transformers`' onnxruntime-node@1.24.3. fastembed embeddings
+ * (`fastembed.ts`, onnxruntime-node@1.21.0) are DELIBERATELY routed
+ * elsewhere — see `sharedFastembedProcess.ts` / `fastembedProcessHost.ts` —
+ * for a second, independent native hazard (see below).
+ *
+ * ── Root cause #1 (proven via a from-scratch minimal repro, no test
+ * harness, no mocks — two independent worker_threads.Worker instances, each
+ * performing real ONNX inference, concurrently) ──
+ *
+ * onnxruntime-node's native N-API addon 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. The crash fires from inside a `setImmediate`
+ * completion callback (`onnxruntime-node/dist/backend.js`), which strongly
+ * suggests the native binding keeps some global/static Napi reference that
+ * is not isolate-scoped, so a background completion callback belonging to
+ * one isolate's session fires while the wrong isolate (or no isolate/
+ * HandleScope at all) is active.
+ *
+ * This reproduces even with TWO workers using the exact SAME
+ * onnxruntime-node version (fastembed's 1.21.0, twice) — so it is NOT an
+ * ABI/version-mismatch bug between fastembed's onnxruntime-node@1.21.0 and
+ * @huggingface/transformers' onnxruntime-node@1.24.3; it is a genuine
+ * thread-safety limitation of the onnxruntime-node native addon itself when
+ * 2+ instances are concurrently active in one process, regardless of which
+ * package loaded which version.
+ *
+ * ── Root cause #2 (why fastembed is NOT also hosted in this same worker) ──
+ *
+ * A single shared worker hosting BOTH onnxruntime-node@1.21.0 (fastembed)
+ * AND onnxruntime-node@1.24.3 (transformers) was tried and instrumented:
+ * even with the two `init` calls strictly serialized in JS (proven via
+ * tracing — the second `init` provably did not begin until the first's
+ * promise had fully settled), fastembed's init still deterministically threw
+ * `std::bad_alloc` when it ran second. This means the two onnxruntime-node
+ * major versions leave native state that JS-level Promise resolution does
+ * not observe/synchronize (e.g. lingering background native thread-pool
+ * teardown) — a hazard below what JS scheduling can prevent. Only a real OS
+ * process boundary is proven safe for mixing the two versions; see
+ * `sharedFastembedProcess.ts` for that isolation.
+ *
+ * ── Fix ──
+ *
+ * Every rerank/verify ONNX consumer in this codebase — the MS-MARCO
+ * cross-encoder reranker (`@adhd/sox-hybrid-search`) and the DeBERTa NLI
+ * verifier (`@adhd/sox-claim-verification`) — is routed through exactly ONE
+ * lazily created, process-wide `worker_threads.Worker` running
+ * `embedWorker.ts`. There is never a second onnxruntime-bearing worker alive
+ * in the process, so root cause #1 is structurally impossible. fastembed
+ * never shares a thread (or process) with this worker at all, so root cause
+ * #2 is structurally impossible too.
+ *
+ * This is the ONLY place a `new Worker(embedWorker.js)` (or any other
+ * onnxruntime-bearing worker) should be constructed anywhere in the
+ * `@adhd/sox-embedding-provider` / `@adhd/sox-hybrid-search` /
+ * `@adhd/sox-claim-verification` triangle. `CrossEncoderWorker` and
+ * `WorkerProxy` delegate their wire traffic to
+ * `getSharedOnnxWorker().request(...)` instead of spawning their own
+ * `Worker`; `FastembedProvider` delegates to
+ * `getSharedFastembedProcess().request(...)` instead (a separate child
+ * PROCESS, not this worker).
+ *
+ * Trade-off (accepted, documented): `@adhd/sox-claim-verification`'s
+ * `workerCount` pool option (`ClaimVerifierConfig.workerCount`) previously
+ * gave real parallelism by spawning N separate worker threads. Since
+ * rerank+verify work in the process now funnels through this single shared
+ * worker, a `workerCount > 1` no longer buys extra parallelism (every
+ * `WorkerProxy` in the pool proxies to the same underlying worker) — but it
+ * remains safe (no crash) and does not regress correctness, only
+ * throughput under artificially-forced pool concurrency. This is the
+ * correct trade for a HIGH-severity whole-process crash.
+ */
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve `embedWorker.js` regardless of whether this module is running
+ * compiled (`dist/sharedOnnxWorker.js`, sitting next to the compiled
+ * `dist/embedWorker.js`) or transformed-in-place from source (vitest runs
+ * `.ts` files directly via its SSR transform, so `__dirname` resolves to
+ * `src/`, which never contains a compiled `.js`) — mirrors the same
+ * `dist`-fallback pattern already proven in `embedWorker.spec.ts`.
+ */
+function resolveEmbedWorkerPath() {
+    const sibling = join(__dirname, 'embedWorker.js');
+    if (existsSync(sibling))
+        return sibling;
+    const distSibling = join(__dirname, '..', 'dist', 'embedWorker.js');
+    if (existsSync(distSibling))
+        return distSibling;
+    // Last resort: return the original candidate so the resulting error names
+    // the path that was actually attempted.
+    return sibling;
+}
+export class SharedOnnxWorkerClient {
+    worker = null;
+    startingPromise = null;
+    nextId = 1;
+    pending = new Map();
+    /** True once the underlying Worker has been created. */
+    get started() {
+        return this.worker !== null;
+    }
+    /** Lazily create (exactly once) and return the single shared Worker instance. */
+    ensureWorker() {
+        if (this.worker)
+            return Promise.resolve(this.worker);
+        if (this.startingPromise)
+            return this.startingPromise;
+        this.startingPromise = new Promise((resolveStart) => {
+            const workerPath = resolveEmbedWorkerPath();
+            const w = new Worker(workerPath);
+            w.unref();
+            w.on('message', (msg) => {
+                const pending = this.pending.get(msg.id);
+                if (!pending)
+                    return;
+                this.pending.delete(msg.id);
+                if ('error' in msg && typeof msg['error'] === 'string') {
+                    pending.reject(new Error(msg['error']));
+                }
+                else {
+                    pending.resolve(msg);
+                }
+            });
+            w.on('error', (err) => {
+                for (const { reject } of this.pending.values())
+                    reject(err);
+                this.pending.clear();
+                this.worker = null;
+                this.startingPromise = null;
+            });
+            w.on('exit', (code) => {
+                if (code !== 0) {
+                    const err = new Error(`shared ONNX worker exited with code ${code}`);
+                    for (const { reject } of this.pending.values())
+                        reject(err);
+                    this.pending.clear();
+                }
+                this.worker = null;
+                this.startingPromise = null;
+            });
+            // Attaching a 'message'/'error'/'exit' listener re-refs a Worker's
+            // underlying MessagePort even if `.unref()` already ran once before
+            // any listener existed (carried over from the BL-fix already applied
+            // to the 3 previous per-consumer worker implementations this module
+            // replaces). Re-assert unref now that every listener is attached, so
+            // a real process can exit once its own work is done instead of
+            // hanging on this worker forever.
+            w.unref();
+            this.worker = w;
+            resolveStart(w);
+        });
+        return this.startingPromise;
+    }
+    /**
+     * Send a request to the shared worker and await its correlated response.
+     * Assigns a globally-unique `id` — the caller must NOT set its own `id`
+     * (any `id` field on `payload` is ignored/overwritten).
+     *
+     * Resolves with the raw response message (everything embedWorker.ts sent
+     * back except the correlation `id` is semantically meaningful to the
+     * caller — e.g. `{ initOk, dim }`, `{ embedding }`, `{ scores }`,
+     * `{ result }`). Rejects if the response carries an `error` string, if
+     * the shared worker itself errors/exits non-zero while the request is
+     * pending, or if `timeoutMs` elapses first.
+     */
+    async request(payload, timeoutMs) {
+        const worker = await this.ensureWorker();
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            let to;
+            if (timeoutMs && timeoutMs > 0) {
+                to = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`shared ONNX worker request timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                if (typeof to.unref === 'function')
+                    to.unref();
+            }
+            this.pending.set(id, {
+                resolve: (v) => {
+                    if (to)
+                        clearTimeout(to);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    if (to)
+                        clearTimeout(to);
+                    reject(e);
+                },
+            });
+            worker.postMessage({ ...payload, id });
+        });
+    }
+    /**
+     * Forcefully terminate the shared worker. Intended ONLY for full process
+     * shutdown or test teardown that genuinely owns the whole process's ONNX
+     * lifecycle — an individual consumer's dispose()/stop() must NOT call
+     * this, since other consumers (embed / rerank / verify) may still depend
+     * on the shared worker.
+     */
+    async terminate() {
+        const w = this.worker;
+        this.worker = null;
+        this.startingPromise = null;
+        for (const { reject } of this.pending.values()) {
+            reject(new Error('shared ONNX worker terminated'));
+        }
+        this.pending.clear();
+        if (w)
+            await w.terminate();
+    }
+}
+let _singleton = null;
+/**
+ * Process-wide singleton accessor — the ONLY sanctioned place a
+ * `new Worker(embedWorker.js)` is constructed anywhere in the embed/rerank/
+ * verify triangle (BL-238/BL-171). Every ONNX consumer (fastembed
+ * embeddings, cross-encoder rerank, NLI verify) must obtain its worker
+ * handle through this function instead of constructing its own `Worker`.
+ */
+export function getSharedOnnxWorker() {
+    if (!_singleton)
+        _singleton = new SharedOnnxWorkerClient();
+    return _singleton;
+}
+/**
+ * Test-only: reset the module-level singleton so a test can exercise a
+ * fresh shared-worker lifecycle (e.g. after deliberately crashing/
+ * terminating it). Does NOT terminate any existing worker itself — call
+ * `.terminate()` on the previous instance first if a clean shutdown is
+ * needed.
+ */
+export function __resetSharedOnnxWorkerForTests() {
+    _singleton = null;
+}
+//# sourceMappingURL=sharedOnnxWorker.js.map

package/dist/sharedOnnxWorker.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@adhd/sox-embedding-provider",
+  "version": "0.1.0",
+  "description": "Pluggable text→vector embedding provider — generic EmbeddingProvider interface, config-driven model resolution, async batch-first API (AsyncIterable). Default: fastembed (local ONNX, >=3 model dims proven). Loud-fail: createEmbeddingProvider() throws ResolutionError if config is invalid or model cannot load — no silent downgrade.",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "fastembed": "^2.1.0"
+  },
+  "sox": {
+    "area": "data",
+    "group": "embed",
+    "concerns": [
+      "text→vector (EmbeddingProvider interface)",
+      "config-driven model resolution (createEmbeddingProvider factory)",
+      "async batch embed (AsyncIterable<Float32Array>)",
+      "EmbedRole param (document | query) accepted on embedSingle/embedBatch for interface compatibility — currently ignored (not yet applied) by the fastembed provider",
+      "loud-fail ResolutionError at factory time (never mid-call)",
+      "three-tier error taxonomy (Transient / Permanent / Resolution)"
+    ],
+    "invariants": [
+      "createEmbeddingProvider() THROWS ResolutionError synchronously or as a rejection if the config is invalid or the model/runtime cannot load — never silently downgrades",
+      "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 — currently ALWAYS true, since every shipped provider (fastembed, remote) hard-codes isDeterministic: false, so warmUp() is a no-op on every path today",
+      "TransientEmbeddingError → caller may retry; PermanentEmbeddingError → caller must not retry; ResolutionError → factory-time only, never thrown mid-call"
+    ],
+    "entrypoints": [
+      "dist/index.js"
+    ]
+  }
+}