@adhd/sox-embedding-provider 0.1.0

package/dist/remote.js

@@ -0,0 +1,91 @@
+import { PermanentEmbeddingError, TransientEmbeddingError } from './index.js';
+/**
+ * Remote provider adapter — typed reference implementation.
+ *
+ * Implements EmbeddingProvider against the same async+batch-first contract.
+ * NOT wired to a live/paid endpoint — proves context-agnosticism without spend.
+ */
+export class RemoteProvider {
+    metadata;
+    endpoint;
+    apiKey;
+    constructor(modelId, dimensions, endpoint, apiKey) {
+        this.metadata = {
+            modelId,
+            dimensions,
+            maxTokens: 8192,
+            isRemote: true,
+            isDeterministic: false,
+            providerUri: endpoint,
+        };
+        this.endpoint = endpoint;
+        this.apiKey = apiKey;
+    }
+    async embedSingle(text, role) {
+        void role;
+        this.validateEndpoint();
+        try {
+            const vec = await this.simulatedRemoteEmbed(text);
+            return vec;
+        }
+        catch (err) {
+            if (err instanceof TransientEmbeddingError || err instanceof PermanentEmbeddingError) {
+                throw err;
+            }
+            throw new TransientEmbeddingError(`Remote embed failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async *embedBatch(texts, opts) {
+        void opts;
+        this.validateEndpoint();
+        const batchSize = opts?.batchSize ?? 256;
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const chunk = texts.slice(i, i + batchSize);
+            for (const text of chunk) {
+                try {
+                    yield await this.simulatedRemoteEmbed(text);
+                }
+                catch (err) {
+                    if (err instanceof TransientEmbeddingError || err instanceof PermanentEmbeddingError) {
+                        throw err;
+                    }
+                    throw new TransientEmbeddingError(`Remote batch embed failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    health() {
+        return {
+            configured: `remote:${this.metadata.modelId}`,
+            active: this.metadata.modelId,
+            state: 'real',
+            dimensions: this.metadata.dimensions,
+            last_error: null,
+        };
+    }
+    async warmUp(_texts) {
+        // No-op: isDeterministic is false, cache would be unreliable.
+    }
+    validateEndpoint() {
+        if (!this.endpoint.startsWith('https://') && !this.endpoint.startsWith('http://')) {
+            throw new PermanentEmbeddingError(`Invalid remote endpoint: ${this.endpoint} (must start with http:// or https://)`);
+        }
+        if (!this.apiKey) {
+            throw new PermanentEmbeddingError(`Remote provider requires an API key (endpoint: ${this.endpoint})`);
+        }
+    }
+    async simulatedRemoteEmbed(text) {
+        if (!this.apiKey || this.apiKey.length < 8) {
+            throw new PermanentEmbeddingError('Invalid API key: too short');
+        }
+        if (text.length === 0) {
+            throw new PermanentEmbeddingError('Cannot embed empty text');
+        }
+        if (text.length > 8192) {
+            throw new PermanentEmbeddingError('Text exceeds maximum token length');
+        }
+        // Simulate: return a zero vector (reference impl, not wired to real endpoint)
+        return new Float32Array(this.metadata.dimensions);
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/remote.js.map

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

package/dist/sharedFastembedProcess.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Process-wide singleton client for the ONE fastembed-hosting child
+ * **process** allowed to exist in this process (BL-238/BL-171).
+ *
+ * See `fastembedProcessHost.ts` for the full root-cause writeup: fastembed's
+ * onnxruntime-node@1.21.0 cannot safely share a `worker_threads.Worker` (or
+ * any thread) with `@huggingface/transformers`' onnxruntime-node@1.24.3 —
+ * proven not just for concurrent execution (whole-process HandleScope fatal)
+ * but even for strictly JS-serialized sequential loading in the same thread
+ * (deterministic `std::bad_alloc`, confirmed via instrumented tracing showing
+ * zero JS-level overlap). Only a real OS process boundary is proven safe.
+ *
+ * This mirrors `sharedOnnxWorker.ts`'s client shape (lazy singleton,
+ * request/response correlation by `id`, `unref()`'d so it never keeps a real
+ * process alive) but forks a child **process** instead of constructing a
+ * `worker_threads.Worker`.
+ */
+export declare class SharedFastembedProcessClient {
+    private child;
+    private startingPromise;
+    private nextId;
+    private pending;
+    /** True once the underlying child process has been forked. */
+    get started(): boolean;
+    /** Lazily fork (exactly once) and return the single shared child process. */
+    private ensureProcess;
+    /**
+     * Send a request to the shared fastembed process 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).
+     */
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /**
+     * Forcefully terminate the shared fastembed process. Intended ONLY for
+     * full process shutdown or test teardown that genuinely owns the whole
+     * process's fastembed lifecycle.
+     */
+    terminate(): Promise<void>;
+}
+/**
+ * Process-wide singleton accessor — the ONLY sanctioned place a fastembed
+ * child process is forked anywhere in `@adhd/sox-embedding-provider`
+ * (BL-238/BL-171). Every `FastembedProvider` obtains its handle through this
+ * function instead of constructing its own `worker_threads.Worker` or
+ * `child_process`.
+ */
+export declare function getSharedFastembedProcess(): SharedFastembedProcessClient;
+/**
+ * Test-only: reset the module-level singleton so a test can exercise a
+ * fresh shared-process lifecycle (e.g. after deliberately crashing/
+ * terminating it). Does NOT terminate any existing process itself — call
+ * `.terminate()` on the previous instance first if a clean shutdown is
+ * needed.
+ */
+export declare function __resetSharedFastembedProcessForTests(): void;
+//# sourceMappingURL=sharedFastembedProcess.d.ts.map

package/dist/sharedFastembedProcess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedFastembedProcess.d.ts","sourceRoot":"","sources":["../src/sharedFastembedProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAqCH,qBAAa,4BAA4B;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,eAAe,CAAsC;IAC7D,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAmC;IAElD,8DAA8D;IAC9D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,6EAA6E;IAC7E,OAAO,CAAC,aAAa;IAuDrB;;;;OAIG;IACG,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IA6Bb;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAYjC;AAID;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,4BAA4B,CAGxE;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}

package/dist/sharedFastembedProcess.js

@@ -0,0 +1,180 @@
+/**
+ * Process-wide singleton client for the ONE fastembed-hosting child
+ * **process** allowed to exist in this process (BL-238/BL-171).
+ *
+ * See `fastembedProcessHost.ts` for the full root-cause writeup: fastembed's
+ * onnxruntime-node@1.21.0 cannot safely share a `worker_threads.Worker` (or
+ * any thread) with `@huggingface/transformers`' onnxruntime-node@1.24.3 —
+ * proven not just for concurrent execution (whole-process HandleScope fatal)
+ * but even for strictly JS-serialized sequential loading in the same thread
+ * (deterministic `std::bad_alloc`, confirmed via instrumented tracing showing
+ * zero JS-level overlap). Only a real OS process boundary is proven safe.
+ *
+ * This mirrors `sharedOnnxWorker.ts`'s client shape (lazy singleton,
+ * request/response correlation by `id`, `unref()`'d so it never keeps a real
+ * process alive) but forks a child **process** instead of constructing a
+ * `worker_threads.Worker`.
+ */
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve `fastembedProcessHost.js` regardless of whether this module is
+ * running compiled (`dist/sharedFastembedProcess.js`, sitting next to the
+ * compiled `dist/fastembedProcessHost.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
+ * `sharedOnnxWorker.ts`.
+ */
+function resolveFastembedHostPath() {
+    const sibling = join(__dirname, 'fastembedProcessHost.js');
+    if (existsSync(sibling))
+        return sibling;
+    const distSibling = join(__dirname, '..', 'dist', 'fastembedProcessHost.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 SharedFastembedProcessClient {
+    child = null;
+    startingPromise = null;
+    nextId = 1;
+    pending = new Map();
+    /** True once the underlying child process has been forked. */
+    get started() {
+        return this.child !== null;
+    }
+    /** Lazily fork (exactly once) and return the single shared child process. */
+    ensureProcess() {
+        if (this.child)
+            return Promise.resolve(this.child);
+        if (this.startingPromise)
+            return this.startingPromise;
+        this.startingPromise = new Promise((resolveStart) => {
+            const hostPath = resolveFastembedHostPath();
+            const c = fork(hostPath, [], {
+                stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+                // Real inference is CPU-bound in native code; no need to keep the
+                // parent process alive on this child's account.
+                detached: false,
+            });
+            c.unref();
+            c.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);
+                }
+            });
+            c.on('error', (err) => {
+                for (const { reject } of this.pending.values())
+                    reject(err);
+                this.pending.clear();
+                this.child = null;
+                this.startingPromise = null;
+            });
+            c.on('exit', (code) => {
+                if (code !== 0 && code !== null) {
+                    const err = new Error(`shared fastembed process exited with code ${code}`);
+                    for (const { reject } of this.pending.values())
+                        reject(err);
+                    this.pending.clear();
+                }
+                this.child = null;
+                this.startingPromise = null;
+            });
+            // Same re-unref pattern as `sharedOnnxWorker.ts` — attaching listeners
+            // can re-ref the underlying handle; re-assert `unref()` once every
+            // listener is attached so a real process can exit when its own work is
+            // done instead of hanging on this child forever.
+            c.unref();
+            this.child = c;
+            resolveStart(c);
+        });
+        return this.startingPromise;
+    }
+    /**
+     * Send a request to the shared fastembed process 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).
+     */
+    async request(payload, timeoutMs) {
+        const child = await this.ensureProcess();
+        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 fastembed process 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);
+                },
+            });
+            child.send({ ...payload, id });
+        });
+    }
+    /**
+     * Forcefully terminate the shared fastembed process. Intended ONLY for
+     * full process shutdown or test teardown that genuinely owns the whole
+     * process's fastembed lifecycle.
+     */
+    async terminate() {
+        const c = this.child;
+        this.child = null;
+        this.startingPromise = null;
+        for (const { reject } of this.pending.values()) {
+            reject(new Error('shared fastembed process terminated'));
+        }
+        this.pending.clear();
+        if (c) {
+            c.kill();
+        }
+    }
+}
+let _singleton = null;
+/**
+ * Process-wide singleton accessor — the ONLY sanctioned place a fastembed
+ * child process is forked anywhere in `@adhd/sox-embedding-provider`
+ * (BL-238/BL-171). Every `FastembedProvider` obtains its handle through this
+ * function instead of constructing its own `worker_threads.Worker` or
+ * `child_process`.
+ */
+export function getSharedFastembedProcess() {
+    if (!_singleton)
+        _singleton = new SharedFastembedProcessClient();
+    return _singleton;
+}
+/**
+ * Test-only: reset the module-level singleton so a test can exercise a
+ * fresh shared-process lifecycle (e.g. after deliberately crashing/
+ * terminating it). Does NOT terminate any existing process itself — call
+ * `.terminate()` on the previous instance first if a clean shutdown is
+ * needed.
+ */
+export function __resetSharedFastembedProcessForTests() {
+    _singleton = null;
+}
+//# sourceMappingURL=sharedFastembedProcess.js.map

package/dist/sharedFastembedProcess.js.map

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

package/dist/sharedOnnxWorker.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+export declare class SharedOnnxWorkerClient {
+    private worker;
+    private startingPromise;
+    private nextId;
+    private pending;
+    /** True once the underlying Worker has been created. */
+    get started(): boolean;
+    /** Lazily create (exactly once) and return the single shared Worker instance. */
+    private ensureWorker;
+    /**
+     * 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.
+     */
+    request<T = Record<string, unknown>>(payload: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /**
+     * 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.
+     */
+    terminate(): Promise<void>;
+}
+/**
+ * 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 declare function getSharedOnnxWorker(): SharedOnnxWorkerClient;
+/**
+ * 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 declare function __resetSharedOnnxWorkerForTests(): void;
+//# sourceMappingURL=sharedOnnxWorker.d.ts.map

package/dist/sharedOnnxWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedOnnxWorker.d.ts","sourceRoot":"","sources":["../src/sharedOnnxWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AA2CH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAmC;IAElD,wDAAwD;IACxD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,iFAAiF;IACjF,OAAO,CAAC,YAAY;IAqDpB;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IA6Bb;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAUjC;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,sBAAsB,CAG5D;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}