@reftrixmcp/ml 0.3.0 → 0.5.1

package/dist/onnx-provider-detect.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reftrixmcp/ml",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "license": "AGPL-3.0-only",
   "type": "module",
   "description": "ML/Embedding services for Reftrix",
@@ -30,16 +30,18 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
-    "onnxruntime-node": "1.21.0",
     "p-limit": "^3.1.0",
     "zod": "^3.24.0"
   },
+  "optionalDependencies": {
+    "onnxruntime-node": "1.21.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.0.14",
     "typescript": "^5.9.0",
     "vitest": "^4.0.14",
-    "@reftrixmcp/config": "0.3.0"
+    "@reftrixmcp/config": "0.5.1"
   },
   "publishConfig": {
     "access": "public"

package/src/config/worker-resource-limits.ts

@@ -0,0 +1,176 @@
+// SPDX-FileCopyrightText: 2025-2026 Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * ML Worker Thread Resource Limits (PR7e-β1)
+ *
+ * ONNX Runtime が CPU fallback (onnxruntime-node) に切り替わったとき、
+ * `execArgv: []` を指定した Worker Thread は親プロセスの
+ * `--max-old-space-size` を継承しないため、デフォルトでは V8 old space
+ * が 4GB 未満の既定値に制限されてしまう。その結果、e5-base / DINOv2 の
+ * CPU 推論で OOM クラッシュが発生し、Queue-based Backfill が永久に
+ * `in_progress` のまま滞留する。
+ *
+ * When ONNX Runtime falls back to CPU (`onnxruntime-node`), a Worker Thread
+ * spawned with `execArgv: []` does NOT inherit the parent's
+ * `--max-old-space-size` flag, so V8 old-space defaults to less than 4GB.
+ * This causes OOM crashes during e5-base / DINOv2 CPU inference and leaves
+ * Queue-based Backfill jobs stuck `in_progress` indefinitely.
+ *
+ * Fix: explicitly pass `resourceLimits` to `new Worker(...)` so that the
+ * worker gets an explicit old-space / young-space / code-range ceiling.
+ *
+ * 参照 / References:
+ * - ADR-0012 §3 BLOCKER 4
+ * - Node.js docs: https://nodejs.org/api/worker_threads.html#new-workerfilename-options
+ *
+ * @module config/worker-resource-limits
+ */
+
+import { z } from "zod";
+
+/**
+ * Default old-space ceiling (MB) for ML Worker Threads.
+ *
+ * 4096 MB は e5-base (~500MB arena) + DINOv2 (~800MB arena) + transformers.js
+ * pipeline overhead を同時に CPU でロードしても OOM にならない実測値。
+ * さらに β1 では Phase 5 親プロセス RSS 上限を 4096 MB に段階緩和するため、
+ * Worker old-space をそれと同水準に揃えることで、親プロセスと子 Worker の
+ * メモリ上限を対称化する。
+ *
+ * 4096 MB is empirically the minimum old-space ceiling that keeps e5-base
+ * (~500MB arena) + DINOv2 (~800MB arena) + transformers.js pipeline overhead
+ * from OOMing on CPU. β1 also raises the Phase 5 parent-process RSS ceiling
+ * to 4096 MB, so aligning the Worker old-space with the parent RSS keeps
+ * parent/child memory ceilings symmetric.
+ */
+const DEFAULT_ML_WORKER_MAX_OLD_SPACE_MB = 4096;
+
+/**
+ * Fixed secondary limits.
+ *
+ * young-space=512MB and code-range=256MB are Node.js defaults scaled for
+ * ONNX Runtime's large tensor allocations; exposing them as env vars would
+ * create too many configuration surfaces.
+ */
+const ML_WORKER_MAX_YOUNG_GENERATION_MB = 512;
+const ML_WORKER_CODE_RANGE_MB = 256;
+
+/**
+ * 許容レンジ
+ * - 下限 512 MB: e5-base の初期化 (tokenizer + model metadata) だけでも
+ *   約 300MB 必要で、ヘッドルームを確保する最小値
+ * - 上限 8192 MB: 単一 Worker Thread で 8GB を超える old-space は現実的な
+ *   ユースケースが存在せず、over-provisioning 防御
+ *
+ * Allowed range:
+ * - Lower bound 512 MB: e5-base init (tokenizer + model metadata) alone needs
+ *   ~300MB, so this is the minimum that preserves any headroom.
+ * - Upper bound 8192 MB: no realistic use case for > 8GB old-space in a single
+ *   Worker Thread; guards against over-provisioning.
+ */
+const ML_WORKER_MAX_OLD_SPACE_MIN_MB = 512;
+const ML_WORKER_MAX_OLD_SPACE_MAX_MB = 8192;
+
+/**
+ * ML Worker resource-limits Zod schema
+ */
+export const MLWorkerResourceLimitsSchema = z.object({
+  /**
+   * Worker Thread の V8 old-space 上限（MB）
+   * V8 old-space ceiling (MB) for the Worker Thread
+   */
+  maxOldGenerationSizeMb: z
+    .number()
+    .int()
+    .min(ML_WORKER_MAX_OLD_SPACE_MIN_MB)
+    .max(ML_WORKER_MAX_OLD_SPACE_MAX_MB)
+    .default(DEFAULT_ML_WORKER_MAX_OLD_SPACE_MB),
+  /**
+   * Worker Thread の V8 young-space 上限（MB）
+   * V8 young-space ceiling (MB) for the Worker Thread
+   */
+  maxYoungGenerationSizeMb: z.number().int().positive().default(ML_WORKER_MAX_YOUNG_GENERATION_MB),
+  /**
+   * Worker Thread の code-range 上限（MB）
+   * Code-range ceiling (MB) for the Worker Thread
+   */
+  codeRangeSizeMb: z.number().int().positive().default(ML_WORKER_CODE_RANGE_MB),
+});
+
+export type MLWorkerResourceLimits = z.infer<typeof MLWorkerResourceLimitsSchema>;
+
+/**
+ * 環境変数から ML Worker Thread の resource-limits をロードする。
+ * Load ML Worker Thread resource-limits from environment variables.
+ *
+ * 環境変数 / Environment variables:
+ * - `ML_WORKER_MAX_OLD_SPACE_MB`: V8 old-space ceiling (MB, integer, 512..8192)
+ *
+ * 不正値（NaN / Infinity / 負値 / 範囲外）は warn してデフォルトにフォールバック。
+ * Invalid values (NaN / Infinity / negative / out of range) warn and fall back
+ * to defaults.
+ *
+ * 副作用 / Side effects:
+ * - なし (純粋関数) / None (pure function)
+ * - 呼び出し側でログ出力すること / Caller is responsible for logging
+ */
+export function loadMLWorkerResourceLimits(): MLWorkerResourceLimits {
+  const raw = process.env["ML_WORKER_MAX_OLD_SPACE_MB"];
+
+  // 未設定 → Zod default
+  // Unset → Zod default
+  if (raw === undefined || raw === "") {
+    return MLWorkerResourceLimitsSchema.parse({});
+  }
+
+  const parsed = Number(raw);
+
+  // NaN / Infinity 早期拒絶 (Zod でも弾けるが明示的に)
+  // Reject NaN / Infinity explicitly
+  if (!Number.isFinite(parsed)) {
+    return {
+      maxOldGenerationSizeMb: DEFAULT_ML_WORKER_MAX_OLD_SPACE_MB,
+      maxYoungGenerationSizeMb: ML_WORKER_MAX_YOUNG_GENERATION_MB,
+      codeRangeSizeMb: ML_WORKER_CODE_RANGE_MB,
+    };
+  }
+
+  const result = MLWorkerResourceLimitsSchema.safeParse({ maxOldGenerationSizeMb: parsed });
+  if (!result.success) {
+    return {
+      maxOldGenerationSizeMb: DEFAULT_ML_WORKER_MAX_OLD_SPACE_MB,
+      maxYoungGenerationSizeMb: ML_WORKER_MAX_YOUNG_GENERATION_MB,
+      codeRangeSizeMb: ML_WORKER_CODE_RANGE_MB,
+    };
+  }
+
+  return result.data;
+}
+
+/**
+ * 新しい Worker Thread を作成する際に渡す resourceLimits オプションを返す。
+ * Returns the `resourceLimits` option object to pass to `new Worker(...)`.
+ *
+ * 使用例 / Usage:
+ * ```ts
+ * import { getMLWorkerThreadOptions } from "@reftrixmcp/ml/config/worker-resource-limits";
+ * new Worker(scriptPath, { execArgv: [], ...getMLWorkerThreadOptions() });
+ * ```
+ */
+export function getMLWorkerThreadOptions(): {
+  resourceLimits: {
+    maxOldGenerationSizeMb: number;
+    maxYoungGenerationSizeMb: number;
+    codeRangeSizeMb: number;
+  };
+} {
+  const limits = loadMLWorkerResourceLimits();
+  return {
+    resourceLimits: {
+      maxOldGenerationSizeMb: limits.maxOldGenerationSizeMb,
+      maxYoungGenerationSizeMb: limits.maxYoungGenerationSizeMb,
+      codeRangeSizeMb: limits.codeRangeSizeMb,
+    },
+  };
+}

package/src/dinov2/service.ts

@@ -23,6 +23,9 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import type { DINOv2WorkerMessage, DINOv2WorkerResponse } from "./worker-thread-types.js";
+import { safeImportOnnx } from "../onnx-availability.js";
+import { detectExecutionProvider, isLdLibraryPathSetAtOsLevel } from "../onnx-provider-detect.js";
+import { getMLWorkerThreadOptions } from "../config/worker-resource-limits.js";
 
 // =====================================================
 // Constants
@@ -174,7 +177,13 @@ export class DINOv2Service {
 
       // Worker threads inherit the parent's execArgv by default.
       // Pass empty array to prevent parent flags from propagating.
-      this.worker = new Worker(scriptPath, { execArgv: [] });
+      //
+      // PR7e-β1: Add explicit resourceLimits to prevent OOM when ONNX
+      // falls back to CPU (onnxruntime-node). DINOv2 ViT-B/14 arena is
+      // ~800MB; without resourceLimits V8 old-space < 4GB triggers OOM
+      // during CPU inference. See ADR-0012 §3 BLOCKER 4.
+      const workerOptions = { execArgv: [], ...getMLWorkerThreadOptions() };
+      this.worker = new Worker(scriptPath, workerOptions);
 
       this.worker.on("message", (response: DINOv2WorkerResponse) => {
         this.handleWorkerResponse(response);
@@ -280,18 +289,67 @@ export class DINOv2Service {
   // =====================================================
 
   private async initializeInProcess(): Promise<void> {
-    const ortModule = await import("onnxruntime-node");
-    this.inProcessSession = await ortModule.InferenceSession.create(this.modelPath, {
-      executionProviders: ["cpu"],
-      enableCpuMemArena: false,
-      enableMemPattern: false,
-    });
+    const provider = detectExecutionProvider("DINOv2");
+
+    // Safety check: LD_LIBRARY_PATH must be set at OS level for CUDA
+    let effectiveProvider = provider;
+    if (effectiveProvider === "cuda" && !isLdLibraryPathSetAtOsLevel()) {
+      console.warn(
+        "[DINOv2] CUDA requested but LD_LIBRARY_PATH not set at OS level. " + "Falling back to CPU."
+      );
+      effectiveProvider = "cpu";
+    }
+
+    const sessionOptions =
+      effectiveProvider === "cuda"
+        ? {
+            executionProviders: ["CUDAExecutionProvider", "CPUExecutionProvider"],
+            enableMemPattern: false,
+          }
+        : {
+            executionProviders: ["cpu"],
+            enableCpuMemArena: false,
+            enableMemPattern: false,
+          };
+
+    const ortModule = await safeImportOnnx();
+
+    // Attempt session creation with resolved provider.
+    // If CUDA init fails, catch and retry with CPU.
+    try {
+      this.inProcessSession = await ortModule.InferenceSession.create(
+        this.modelPath,
+        sessionOptions
+      );
+    } catch (providerError) {
+      if (effectiveProvider !== "cpu") {
+        const errorMsg =
+          providerError instanceof Error ? providerError.message : String(providerError);
+        console.warn(
+          "[DINOv2] CUDA in-process session creation failed, falling back to CPU: %s",
+          errorMsg
+        );
+        this.inProcessSession = await ortModule.InferenceSession.create(this.modelPath, {
+          executionProviders: ["cpu"],
+          enableCpuMemArena: false,
+          enableMemPattern: false,
+        });
+        effectiveProvider = "cpu";
+      } else {
+        throw providerError;
+      }
+    }
+
     // eslint-disable-next-line no-console
-    console.log("[DINOv2] Session initialized in-process:", this.modelPath);
+    console.log(
+      "[DINOv2] Session initialized in-process (provider: %s):",
+      effectiveProvider,
+      this.modelPath
+    );
   }
 
   private async generateInProcess(imageBuffer: Buffer): Promise<number[]> {
-    const ortModule = await import("onnxruntime-node");
+    const ortModule = await safeImportOnnx();
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const sess = this.inProcessSession as any;
@@ -319,7 +377,18 @@ export class DINOv2Service {
     }
 
     const inputTensor = new ortModule.Tensor("float32", float32, [1, 3, height, width]);
-    const output = await sess.run({ pixel_values: inputTensor });
+
+    // OOM-FIX-1: Use try/finally to ensure ONNX tensor disposal.
+    // ONNX Tensor holds native C++ memory that V8 GC cannot reclaim.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let output: any;
+    try {
+      output = await sess.run({ pixel_values: inputTensor });
+    } finally {
+      if (typeof inputTensor.dispose === "function") {
+        inputTensor.dispose();
+      }
+    }
 
     const lastHiddenState = output.last_hidden_state;
     if (!lastHiddenState) {
@@ -334,6 +403,15 @@ export class DINOv2Service {
       clsToken[i] = data[i]!;
     }
 
+    // OOM-FIX-1: Dispose output tensors after data extraction
+    for (const key of Object.keys(output)) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const tensor = output[key] as any;
+      if (typeof tensor?.dispose === "function") {
+        tensor.dispose();
+      }
+    }
+
     // L2 normalize
     let norm = 0;
     for (let i = 0; i < clsToken.length; i++) {

package/src/dinov2/worker-thread.ts

@@ -28,16 +28,20 @@ import type {
 } from "./worker-thread-types.js";
 
 // =====================================================
-// Dynamic import of onnxruntime-node
+// Dynamic import of onnxruntime-node (optional dependency)
 // =====================================================
 
+import { safeImportOnnx } from "../onnx-availability.js";
+import { detectExecutionProvider, isLdLibraryPathSetAtOsLevel } from "../onnx-provider-detect.js";
+import type { ExecutionProvider } from "../onnx-provider-detect.js";
+
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 type OrtModule = typeof import("onnxruntime-node");
 let ort: OrtModule | null = null;
 
 async function getOrt(): Promise<OrtModule> {
   if (!ort) {
-    ort = await import("onnxruntime-node");
+    ort = await safeImportOnnx();
   }
   return ort;
 }
@@ -137,18 +141,71 @@ function l2Normalize(vec: Float32Array): Float32Array {
 // Session management
 // =====================================================
 
+/** Resolved execution provider for the current session. */
+let resolvedProvider: ExecutionProvider = "cpu";
+
 async function initializeSession(modelPath: string): Promise<void> {
   if (session) return;
 
+  const provider = detectExecutionProvider("DINOv2Worker");
+
+  // Safety check: if CUDA is requested but LD_LIBRARY_PATH was not set at
+  // the OS level (only set via loadEnvLocal at runtime), CUDA init will crash
+  // because dlopen() can't find CUDA shared libraries. Fall back to CPU.
+  let effectiveProvider = provider;
+  if (effectiveProvider === "cuda" && !isLdLibraryPathSetAtOsLevel()) {
+    console.warn(
+      "[DINOv2Worker] CUDA requested but LD_LIBRARY_PATH not set at OS level. " +
+        "dlopen() cannot find CUDA libraries. Falling back to CPU. " +
+        "To use CUDA, set LD_LIBRARY_PATH before starting the Node.js process."
+    );
+    effectiveProvider = "cpu";
+  }
+
+  const sessionOptions =
+    effectiveProvider === "cuda"
+      ? {
+          executionProviders: ["CUDAExecutionProvider", "CPUExecutionProvider"],
+          enableMemPattern: false,
+        }
+      : {
+          executionProviders: ["cpu"],
+          enableCpuMemArena: false,
+          enableMemPattern: false,
+        };
+
   const ortModule = await getOrt();
-  session = (await ortModule.InferenceSession.create(modelPath, {
-    executionProviders: ["cpu"],
-    enableCpuMemArena: false,
-    enableMemPattern: false,
-  })) as unknown as OrtSession;
+
+  // Attempt to create session with the resolved provider.
+  // If CUDA init fails (e.g. library not found), catch and retry with CPU.
+  try {
+    session = (await ortModule.InferenceSession.create(
+      modelPath,
+      sessionOptions
+    )) as unknown as OrtSession;
+    resolvedProvider = effectiveProvider;
+  } catch (providerError) {
+    if (effectiveProvider !== "cpu") {
+      // CUDA init failed — fallback to CPU
+      const errorMsg =
+        providerError instanceof Error ? providerError.message : String(providerError);
+      console.warn(
+        "[DINOv2Worker] CUDA session creation failed, falling back to CPU: %s",
+        errorMsg
+      );
+      session = (await ortModule.InferenceSession.create(modelPath, {
+        executionProviders: ["cpu"],
+        enableCpuMemArena: false,
+        enableMemPattern: false,
+      })) as unknown as OrtSession;
+      resolvedProvider = "cpu";
+    } else {
+      throw providerError;
+    }
+  }
 
   // eslint-disable-next-line no-console
-  console.log("[DINOv2Worker] Session initialized:", modelPath);
+  console.log("[DINOv2Worker] Session initialized (provider: %s):", resolvedProvider, modelPath);
 }
 
 async function disposeSession(): Promise<void> {
@@ -187,8 +244,18 @@ async function runInference(
   // Create input tensor [1, 3, height, width]
   const inputTensor = new ortModule.Tensor("float32", inputData, [1, 3, height, width]);
 
-  // Run inference
-  const output = await session.run({ pixel_values: inputTensor });
+  // Run inference — use try/finally to ensure tensor disposal (OOM-FIX-1)
+  // ONNX Tensor holds native C++ memory that V8 GC cannot reclaim.
+  // Without explicit dispose(), ~1.4MB/inference leaks as native memory.
+  let output: Record<string, { data: Float32Array; dims: readonly number[] }>;
+  try {
+    output = await session.run({ pixel_values: inputTensor });
+  } finally {
+    // Dispose input tensor immediately after inference completes
+    if (typeof (inputTensor as unknown as { dispose?: () => void }).dispose === "function") {
+      (inputTensor as unknown as { dispose: () => void }).dispose();
+    }
+  }
 
   // Extract CLS token from last_hidden_state [1, 257, 768]
   const lastHiddenState = output.last_hidden_state;
@@ -212,6 +279,14 @@ async function runInference(
     clsToken[i] = data[i]!;
   }
 
+  // Dispose output tensors after data extraction (OOM-FIX-1)
+  for (const key of Object.keys(output)) {
+    const tensor = output[key] as unknown as { dispose?: () => void };
+    if (typeof tensor?.dispose === "function") {
+      tensor.dispose();
+    }
+  }
+
   // L2 normalize with NaN/Infinity defense
   const normalized = l2Normalize(clsToken);
 

package/src/embeddings/service.ts

@@ -21,6 +21,8 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import type { EmbeddingTextType, EmbeddingServiceConfig, CacheStats } from "./types.js";
 import type { WorkerMessage, WorkerResponse } from "./worker-thread-types.js";
+import { OnnxRuntimeUnavailableError } from "../onnx-availability.js";
+import { getMLWorkerThreadOptions } from "../config/worker-resource-limits.js";
 
 /**
  * Disposable pipeline interface (used only in in-process fallback mode).
@@ -306,7 +308,13 @@ export class EmbeddingService {
       // worker_threads Workers, so we must explicitly pass an empty array
       // to prevent the parent's flags (set by WorkerSupervisor fork())
       // from propagating.
-      this.worker = new Worker(scriptPath, { execArgv: [] });
+      //
+      // PR7e-β1: Add explicit resourceLimits to prevent OOM when ONNX
+      // falls back to CPU (onnxruntime-node). Without resourceLimits,
+      // V8 old-space defaults to < 4GB and e5-base CPU inference OOMs.
+      // See ADR-0012 §3 BLOCKER 4 and config/worker-resource-limits.ts.
+      const workerOptions = { execArgv: [], ...getMLWorkerThreadOptions() };
+      this.worker = new Worker(scriptPath, workerOptions);
 
       // Handle worker messages
       this.worker.on("message", (response: WorkerResponse) => {
@@ -502,6 +510,10 @@ export class EmbeddingService {
         }
       } catch (error) {
         this.initPromise = null;
+        const code = (error as { code?: string }).code;
+        if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+          throw new OnnxRuntimeUnavailableError("text embedding");
+        }
         const message = error instanceof Error ? error.message : "Unknown error";
         throw new Error(`Failed to load embedding model: ${message}`);
       }

package/src/embeddings/worker-thread.ts

@@ -20,10 +20,14 @@
  */
 
 import { parentPort } from "node:worker_threads";
-import { createRequire } from "node:module";
-import fs from "node:fs";
-import nodePath from "node:path";
 import type { WorkerMessage, WorkerResponse, WorkerErrorResponse } from "./worker-thread-types.js";
+import { OnnxRuntimeUnavailableError } from "../onnx-availability.js";
+import {
+  detectExecutionProvider,
+  verifyCudaAvailability,
+  isLdLibraryPathSetAtOsLevel,
+} from "../onnx-provider-detect.js";
+import type { ExecutionProvider } from "../onnx-provider-detect.js";
 
 // =====================================================
 // Pipeline types (mirrors service.ts DisposablePipeline)
@@ -38,83 +42,6 @@ interface DisposablePipeline {
   dispose?: () => Promise<unknown[]>;
 }
 
-// =====================================================
-// GPU execution provider detection
-// =====================================================
-
-type ExecutionProvider = "cpu" | "cuda";
-
-/**
- * Detect the ONNX execution provider based on environment configuration.
- *
- * Checks ONNX_EXECUTION_PROVIDER env var and verifies that the CUDA
- * provider shared library is available on disk. Falls back to CPU
- * gracefully if the provider is not installed.
- */
-function detectExecutionProvider(): ExecutionProvider {
-  const envProvider = process.env.ONNX_EXECUTION_PROVIDER;
-
-  if (envProvider === "cuda" || envProvider === "rocm") {
-    const cudaAvailable = verifyCudaAvailability();
-    if (cudaAvailable) {
-      return "cuda";
-    }
-    console.warn(
-      "[EmbeddingWorker] ONNX_EXECUTION_PROVIDER=%s but CUDA provider not available, falling back to CPU",
-      envProvider
-    );
-    return "cpu";
-  }
-
-  return "cpu";
-}
-
-/**
- * Verify that CUDA provider (libonnxruntime_providers_cuda.so) is available.
- *
- * onnxruntime-node can download the CUDA provider shared library via
- * `ONNXRUNTIME_NODE_INSTALL_CUDA=v12 node .../install.js`. This function
- * checks for its presence on disk rather than trying to resolve a
- * non-existent npm package (onnxruntime-gpu is Python-only).
- */
-function verifyCudaAvailability(): boolean {
-  try {
-    const esmRequire = createRequire(import.meta.url);
-    const ortNodePath = esmRequire.resolve("onnxruntime-node");
-    // require.resolve returns e.g. .../onnxruntime-node/dist/index.js
-    // Walk up to package root by finding the directory containing package.json
-    let packageDir = nodePath.dirname(ortNodePath);
-    for (let i = 0; i < 5; i++) {
-      if (fs.existsSync(nodePath.join(packageDir, "package.json"))) break;
-      packageDir = nodePath.dirname(packageDir);
-    }
-
-    // Search across napi versions (v3, v6, etc.) for CUDA provider
-    const binDir = nodePath.join(packageDir, "bin");
-    if (fs.existsSync(binDir)) {
-      const napiDirs = fs.readdirSync(binDir).filter((d) => d.startsWith("napi-v"));
-      for (const napiDir of napiDirs) {
-        const cudaProviderPath = nodePath.join(
-          binDir,
-          napiDir,
-          "linux",
-          "x64",
-          "libonnxruntime_providers_cuda.so"
-        );
-        if (fs.existsSync(cudaProviderPath)) {
-          return true;
-        }
-      }
-    }
-
-    console.warn("[EmbeddingWorker] CUDA provider not found in: %s", binDir);
-    return false;
-  } catch {
-    console.warn("[EmbeddingWorker] Cannot verify CUDA provider: onnxruntime-node not found");
-    return false;
-  }
-}
-
 // =====================================================
 // Worker state
 // =====================================================
@@ -146,26 +73,6 @@ function normalizeVector(vector: number[]): number[] {
   return vector.map((val) => val / norm);
 }
 
-/**
- * Verify that LD_LIBRARY_PATH is set at the OS level (not just process.env).
- *
- * dlopen() reads LD_LIBRARY_PATH from the kernel environment (/proc/self/environ),
- * NOT from process.env modifications made at runtime. If LD_LIBRARY_PATH was set
- * after process startup (e.g. by loadEnvLocal()), dlopen() cannot find CUDA
- * libraries and ONNX Runtime CUDA provider initialization will segfault or throw.
- *
- * Returns true only if LD_LIBRARY_PATH was present in the original process environment.
- */
-function isLdLibraryPathSetAtOsLevel(): boolean {
-  try {
-    const procEnv = fs.readFileSync("/proc/self/environ", "utf-8");
-    return procEnv.includes("LD_LIBRARY_PATH");
-  } catch {
-    // /proc/self/environ not available (non-Linux) — assume set
-    return true;
-  }
-}
-
 async function initializePipeline(): Promise<void> {
   if (pipeline) return;
   if (initPromise) return initPromise;
@@ -175,7 +82,7 @@ async function initializePipeline(): Promise<void> {
       // Only auto-detect from env on first init. If provider was explicitly
       // set by a switch-provider message, respect that setting.
       if (!providerExplicitlySet) {
-        resolvedProvider = detectExecutionProvider();
+        resolvedProvider = detectExecutionProvider("EmbeddingWorker");
       }
 
       // Safety check: if CUDA is requested but LD_LIBRARY_PATH was not set at
@@ -236,6 +143,10 @@ async function initializePipeline(): Promise<void> {
       console.log("[EmbeddingWorker] ONNX pipeline ready (provider: %s)", resolvedProvider);
     } catch (error) {
       initPromise = null;
+      const code = (error as { code?: string }).code;
+      if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+        throw new OnnxRuntimeUnavailableError("text embedding");
+      }
       const message = error instanceof Error ? error.message : "Unknown error";
       throw new Error(`Failed to load embedding model in worker thread: ${message}`);
     }
@@ -446,7 +357,7 @@ async function handleMessage(message: WorkerMessage): Promise<void> {
 
       // If switching to CUDA, verify availability first
       if (targetProvider === "cuda") {
-        const canUseCuda = verifyCudaAvailability();
+        const canUseCuda = verifyCudaAvailability("EmbeddingWorker");
         if (!canUseCuda) {
           // Cannot switch to CUDA — respond with current (cpu) provider
           sendResponse({