@reftrixmcp/ml 0.1.7 → 0.5.1

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,16 +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"],
-  })) 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> {
@@ -185,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;
@@ -210,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}`);
       }
@@ -1275,6 +1287,92 @@ export class EmbeddingService {
     this.config = { ...this.config, device: "cpu" };
   }
 
+  /**
+   * Terminate the worker thread and prepare for re-spawn on next use.
+   *
+   * Unlike dispose() which only releases the ONNX pipeline within the
+   * existing worker thread, this method terminates the worker thread
+   * process entirely. This forces the OS to reclaim ALL memory held by
+   * the ONNX Runtime C++ arena allocator, which glibc malloc fragmentation
+   * prevents dispose() from returning.
+   *
+   * After termination, the next generateEmbedding() call will automatically
+   * re-spawn a new worker thread via ensureWorkerReady().
+   *
+   * Key behaviors:
+   * - lastCrashTime is reset to 0 (planned terminate, not a crash)
+   * - workerRestartCount is preserved (not incremented)
+   * - currentProvider is preserved for re-spawn
+   * - Mutual exclusion via workerInitPromise
+   */
+  async terminateAndRespawn(): Promise<void> {
+    // T-4: Set workerInitPromise to prevent concurrent spawns during terminate
+    const terminatePromise = (async (): Promise<void> => {
+      // T-3: Save workerRestartCount before terminate (crash handler increments it)
+      const savedRestartCount = this.workerRestartCount;
+
+      // Clear idle timer
+      if (this.idleTimer !== null) {
+        clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+      }
+
+      if (this.worker) {
+        try {
+          // Send terminate message so worker can dispose pipeline
+          await this.sendWorkerMessage({
+            type: "terminate",
+            requestId: generateRequestId(),
+          });
+        } catch {
+          // May fail if worker already exited
+        }
+
+        // Force terminate the worker thread
+        try {
+          await this.worker.terminate();
+        } catch {
+          // Already terminated
+        }
+
+        this.worker = null;
+        this.workerReady = false;
+      }
+
+      // Also dispose in-process pipeline if present
+      await this.disposeInProcess();
+
+      // Reject any remaining pending requests
+      for (const [id, pending] of this.pendingRequests) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error("Service terminated for respawn"));
+        this.pendingRequests.delete(id);
+      }
+
+      // T-3: Restore workerRestartCount (planned terminate, not a crash)
+      this.workerRestartCount = savedRestartCount;
+
+      // T-3: Reset lastCrashTime (planned terminate, no cooldown needed)
+      this.lastCrashTime = 0;
+
+      this.inferencesSinceRecycle = 0;
+
+      // T-5: currentProvider is NOT reset — re-spawn will use same provider
+
+      // eslint-disable-next-line no-console
+      console.log("[ML] Worker Thread terminated for respawn (planned)");
+    })();
+
+    // T-4: Hold workerInitPromise to block concurrent generateEmbedding() calls
+    this.workerInitPromise = terminatePromise.then(() => {
+      // Clear workerInitPromise after terminate completes so next
+      // ensureWorkerReady() can spawn a fresh worker
+      this.workerInitPromise = null;
+    });
+
+    await terminatePromise;
+  }
+
   /**
    * Get the number of worker thread restarts that have occurred.
    */

package/src/embeddings/worker-thread-types.ts

@@ -144,7 +144,7 @@ export interface WorkerDisposeResponse {
 }
 
 /**
- * Successful response from terminate (sent just before process.exit).
+ * Successful response from terminate (sent before parent calls worker.terminate()).
  */
 export interface WorkerTerminateResponse {
   type: "terminate";

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}`);
     }
@@ -436,8 +347,8 @@ async function handleMessage(message: WorkerMessage): Promise<void> {
         requestId: message.requestId,
         success: true,
       });
-      // Allow the response to be flushed before exiting
-      setTimeout(() => process.exit(0), 50);
+      // Parent calls worker.terminate() to stop this thread.
+      // No process.exit() — let parent control the lifecycle.
       break;
     }
 
@@ -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({

package/src/index.ts

@@ -49,6 +49,21 @@ export { DINOv2Service, DINOV2_EMBEDDING_DIMENSION, DINOV2_INPUT_SIZE } from "./
 export type { DINOv2ServiceConfig } from "./dinov2/index.js";
 export type { DINOv2WorkerMessage, DINOv2WorkerResponse } from "./dinov2/index.js";
 
+// ONNX Runtime availability checker
+export {
+  isOnnxRuntimeAvailable,
+  OnnxRuntimeUnavailableError,
+  safeImportOnnx,
+} from "./onnx-availability.js";
+
+// ML Worker Thread resource limits (PR7e-β1)
+export {
+  loadMLWorkerResourceLimits,
+  getMLWorkerThreadOptions,
+  MLWorkerResourceLimitsSchema,
+} from "./config/worker-resource-limits.js";
+export type { MLWorkerResourceLimits } from "./config/worker-resource-limits.js";
+
 // Search utilities exports (SearchService removed in v0.1.0)
 export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./search/index.js";
 export { executeHybridSearch } from "./search/index.js";

package/src/onnx-availability.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Cached availability checker for onnxruntime-node (optionalDependency).
+ * When unavailable, ML features degrade gracefully.
+ *
+ * @module onnx-availability
+ */
+
+let _available: boolean | null = null;
+let _unavailableReason: string | null = null;
+
+/**
+ * Check if onnxruntime-node is available (async, caches result).
+ */
+export async function isOnnxRuntimeAvailable(): Promise<boolean> {
+  if (_available !== null) return _available;
+  try {
+    await import("onnxruntime-node");
+    _available = true;
+    _unavailableReason = null;
+  } catch {
+    _available = false;
+    _unavailableReason = "onnxruntime-node is not installed";
+  }
+  return _available;
+}
+
+/**
+ * Synchronous check — returns null if not yet probed.
+ */
+export function isOnnxRuntimeAvailableSync(): boolean | null {
+  return _available;
+}
+
+/**
+ * Returns the reason onnxruntime-node is unavailable, or null if available.
+ */
+export function getOnnxUnavailableReason(): string | null {
+  return _unavailableReason;
+}
+
+/**
+ * Error thrown when ML features require onnxruntime-node but it is not installed.
+ */
+export class OnnxRuntimeUnavailableError extends Error {
+  constructor(context?: string) {
+    super(
+      `ML features require onnxruntime-node which is not available. ` +
+        `Install with: pnpm add onnxruntime-node` +
+        (context ? ` (${context})` : "")
+    );
+    this.name = "OnnxRuntimeUnavailableError";
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+type OnnxRuntimeModule = typeof import("onnxruntime-node");
+
+/**
+ * Safely import onnxruntime-node with a sanitized error on failure.
+ */
+export async function safeImportOnnx(): Promise<OnnxRuntimeModule> {
+  try {
+    return await import("onnxruntime-node");
+  } catch {
+    throw new OnnxRuntimeUnavailableError();
+  }
+}
+
+/**
+ * For testing: reset cached state.
+ */
+export function _resetForTesting(): void {
+  _available = null;
+  _unavailableReason = null;
+}

package/src/onnx-provider-detect.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * ONNX Execution Provider Detection Utilities
+ *
+ * Shared logic for detecting the ONNX execution provider (CPU vs CUDA)
+ * based on environment configuration and CUDA shared library availability.
+ *
+ * Used by both the e5-base embedding worker thread and the DINOv2 worker thread
+ * to avoid code duplication. Extracted from embeddings/worker-thread.ts in v0.4.0.
+ *
+ * @module onnx-provider-detect
+ */
+
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import nodePath from "node:path";
+
+// =====================================================
+// Types
+// =====================================================
+
+export type ExecutionProvider = "cpu" | "cuda";
+
+// =====================================================
+// Provider Detection
+// =====================================================
+
+/**
+ * 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.
+ *
+ * @param logPrefix - Log prefix for warning messages (e.g. "EmbeddingWorker", "DINOv2Worker")
+ */
+export function detectExecutionProvider(logPrefix?: string): ExecutionProvider {
+  const prefix = logPrefix ?? "OnnxProvider";
+  const envProvider = process.env.ONNX_EXECUTION_PROVIDER;
+
+  if (envProvider === "cuda" || envProvider === "rocm") {
+    const cudaAvailable = verifyCudaAvailability(logPrefix);
+    if (cudaAvailable) {
+      return "cuda";
+    }
+    console.warn(
+      "[%s] ONNX_EXECUTION_PROVIDER=%s but CUDA provider not available, falling back to CPU",
+      prefix,
+      envProvider
+    );
+    return "cpu";
+  }
+
+  return "cpu";
+}
+
+// =====================================================
+// CUDA Availability Verification
+// =====================================================
+
+/**
+ * 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).
+ *
+ * @param logPrefix - Log prefix for warning messages
+ */
+export function verifyCudaAvailability(logPrefix?: string): boolean {
+  const prefix = logPrefix ?? "OnnxProvider";
+  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("[%s] CUDA provider not found in: %s", prefix, binDir);
+    return false;
+  } catch {
+    console.warn("[%s] Cannot verify CUDA provider: onnxruntime-node not found", prefix);
+    return false;
+  }
+}
+
+// =====================================================
+// LD_LIBRARY_PATH Check
+// =====================================================
+
+/**
+ * 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.
+ *
+ * @returns true if LD_LIBRARY_PATH is set at OS level, or if /proc/self/environ is unavailable
+ */
+export 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;
+  }
+}