@reftrixmcp/ml 0.3.0 → 0.6.0

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,9 @@ 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";
+import { detectExecutionProvider, isLdLibraryPathSetAtOsLevel } from "../onnx-provider-detect.js";
 
 /**
  * Disposable pipeline interface (used only in in-process fallback mode).
@@ -306,7 +309,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) => {
@@ -445,10 +454,59 @@ export class EmbeddingService {
    * If the configured device is 'cuda' but initialization fails (e.g. because
    * LD_LIBRARY_PATH was not set at the OS level), automatically falls back to CPU.
    */
+  /**
+   * Resolve the safe execution device for the in-process pipeline.
+   *
+   * PR-1 GPU-COORD H regression fix (FIND-IMPL-PR1-H-NEW-01): the Phase 5 fork
+   * child's VRAM probe wires `ONNX_EXECUTION_PROVIDER=cuda` when free VRAM is
+   * available, but that does NOT guarantee the CUDA EP shared library
+   * (`libonnxruntime_providers_cuda.so`) is installed on the host. Previously
+   * the in-process path trusted `this.config.device` (set straight from the env
+   * var in the constructor) and passed `device:"cuda"` to transformers, which
+   * raw-throws on the native dlopen failure when the EP `.so` is absent.
+   *
+   * This gate mirrors the DINOv2 in-process path (`dinov2/worker-thread.ts`
+   * `initializeSession`): it resolves via `detectExecutionProvider` (which calls
+   * `verifyCudaAvailability` for an EP `.so` filesystem check) and also requires
+   * `LD_LIBRARY_PATH` at the OS level. If either fails, it returns "cpu" so the
+   * pipeline is never asked to create a CUDA session it cannot back. When the
+   * configured device is not "cuda", the configured device is returned as-is.
+   */
+  private resolveInProcessDevice(): "cpu" | "cuda" {
+    if (this.config.device !== "cuda") {
+      return this.config.device === undefined ? "cpu" : (this.config.device as "cpu" | "cuda");
+    }
+
+    // CUDA requested — gate on EP `.so` availability and OS-level LD_LIBRARY_PATH.
+    const resolved = detectExecutionProvider("EmbeddingService");
+    if (resolved === "cuda" && !isLdLibraryPathSetAtOsLevel()) {
+      console.warn(
+        "[ML] CUDA requested but LD_LIBRARY_PATH not set at OS level. " +
+          "dlopen() cannot find CUDA libraries. Falling back to CPU."
+      );
+      return "cpu";
+    }
+    if (resolved !== "cuda") {
+      console.warn(
+        "[ML] CUDA requested but CUDA EP not available (libonnxruntime_providers_cuda.so absent). " +
+          "Falling back to CPU."
+      );
+    }
+    return resolved;
+  }
+
   private async initializeInProcess(): Promise<void> {
     if (this.pipeline) return;
     if (this.initPromise) return this.initPromise;
 
+    // Resolve the safe device BEFORE init so we never pass an unbacked CUDA
+    // device to the pipeline (FIND-IMPL-PR1-H-NEW-01 — gate parity with DINOv2).
+    const effectiveDevice = this.resolveInProcessDevice();
+    if (effectiveDevice !== this.config.device) {
+      this.config = { ...this.config, device: effectiveDevice };
+      this.currentProvider = effectiveDevice;
+    }
+
     this.initPromise = (async (): Promise<void> => {
       try {
         if (process.env.NODE_ENV === "development") {
@@ -502,6 +560,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-device.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Worker-thread ONNX device gate helpers
+ *
+ * Pure, side-effect-free helpers that decide the effective ONNX execution
+ * device for the e5-base embedding worker thread. Extracted from
+ * `worker-thread.ts` so the gate logic is directly unit-testable — the worker
+ * module itself only runs as a Worker Thread (it requires `parentPort` at
+ * import time), so its gate could otherwise not be exercised in-place.
+ *
+ * The contract mirrors the in-process gate
+ * (`service.ts` `resolveInProcessDevice`, FIND-IMPL-PR1-H-NEW-01): the effective
+ * device must HONOR the already-resolved provider (the result of
+ * `detectExecutionProvider()` + the OS-level `LD_LIBRARY_PATH` check) and must
+ * NOT fall back to a raw `config.device` value (which is set straight from the
+ * `ONNX_EXECUTION_PROVIDER` env var). Letting `config.device="cuda"` override a
+ * gate decision of `"cpu"` passes an unbacked CUDA device to transformers, which
+ * raw-throws on the native `dlopen()` failure when the EP `.so` is absent
+ * (root-cause decision `019ec56b`).
+ *
+ * @module embeddings/worker-thread-device
+ */
+
+import type { ExecutionProvider } from "../onnx-provider-detect.js";
+
+/**
+ * Resolve the effective ONNX device for the worker-thread pipeline.
+ *
+ * `resolvedProvider` is already the result of the init gate
+ * (`detectExecutionProvider()` — a CUDA EP `.so` filesystem check — plus the
+ * OS-level `LD_LIBRARY_PATH` check in `initializePipeline`). This helper simply
+ * honors that decision. It deliberately does NOT consult `config.device`: doing
+ * so was the line-97 bug that let a `"cuda"` env override a `"cpu"` gate result.
+ *
+ * Parity: `service.ts` `resolveInProcessDevice()` likewise returns the gate
+ * result (`resolved`), never a raw configured device when CUDA is unbacked.
+ *
+ * @param resolvedProvider - The provider already resolved by the init gate.
+ * @returns The effective device to pass to the transformers pipeline.
+ */
+export function resolveWorkerEffectiveDevice(
+  resolvedProvider: ExecutionProvider
+): ExecutionProvider {
+  return resolvedProvider;
+}
+
+/**
+ * Decide whether a `switch-provider` request to CUDA may proceed.
+ *
+ * Mirrors the init-time AND gate (`initializePipeline`, line ~88): CUDA may be
+ * used only if BOTH the CUDA EP shared library is present
+ * (`verifyCudaAvailability`) AND `LD_LIBRARY_PATH` was set at the OS level
+ * (`isLdLibraryPathSetAtOsLevel`). Pre-fix, `switch-provider` gated on
+ * `verifyCudaAvailability` alone — so a host with the EP `.so` but an unset
+ * `LD_LIBRARY_PATH` would let `resolvedProvider="cuda"` through, producing an
+ * unbacked CUDA device and a `dlopen()` raw throw (UB-6 init parity).
+ *
+ * The two checks are passed in as functions so this helper stays pure and
+ * deterministically testable (the production caller passes the real
+ * `verifyCudaAvailability` / `isLdLibraryPathSetAtOsLevel`).
+ *
+ * @param verifyCuda - CUDA EP `.so` filesystem availability check.
+ * @param isLdSet - OS-level `LD_LIBRARY_PATH` presence check.
+ * @returns true only if both checks pass (CUDA switch permitted).
+ */
+export function canSwitchToCuda(verifyCuda: () => boolean, isLdSet: () => boolean): boolean {
+  return verifyCuda() && isLdSet();
+}

package/src/embeddings/worker-thread.ts

@@ -20,10 +20,15 @@
  */
 
 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";
+import { resolveWorkerEffectiveDevice, canSwitchToCuda } from "./worker-thread-device.js";
 
 // =====================================================
 // Pipeline types (mirrors service.ts DisposablePipeline)
@@ -38,83 +43,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 +74,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 +83,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
@@ -190,7 +98,13 @@ async function initializePipeline(): Promise<void> {
         resolvedProvider = "cpu";
       }
 
-      const effectiveDevice = resolvedProvider === "cuda" ? "cuda" : config.device;
+      // Honor the gate decision. resolvedProvider is already the result of
+      // detectExecutionProvider() (CUDA EP .so check) + the LD_LIBRARY_PATH OS-level
+      // check above (line 88-95). config.device (set straight from the env var) must
+      // NOT override the gate — otherwise a "cuda" env on a host without the EP .so
+      // passes device:"cuda" to transformers, which raw-throws on dlopen. Parity with
+      // the in-process resolveInProcessDevice() gate (service.ts:472, FIND-IMPL-PR1-H-NEW-01).
+      const effectiveDevice: ExecutionProvider = resolveWorkerEffectiveDevice(resolvedProvider);
 
       // eslint-disable-next-line no-console
       console.log("[EmbeddingWorker] Initializing ONNX pipeline", {
@@ -236,6 +150,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}`);
     }
@@ -444,9 +362,17 @@ async function handleMessage(message: WorkerMessage): Promise<void> {
     case "switch-provider": {
       const targetProvider = message.provider;
 
-      // If switching to CUDA, verify availability first
+      // If switching to CUDA, verify availability first. Mirror the init-time
+      // AND gate (line ~88): CUDA may proceed only if BOTH the EP .so is present
+      // AND LD_LIBRARY_PATH was set at the OS level. Gating on
+      // verifyCudaAvailability ALONE (the pre-fix gap, UB-6) would let a host
+      // with the EP .so but unset LD_LIBRARY_PATH pass device:"cuda" through →
+      // dlopen raw throw. canSwitchToCuda ANDs both checks (init parity).
       if (targetProvider === "cuda") {
-        const canUseCuda = verifyCudaAvailability();
+        const canUseCuda = canSwitchToCuda(
+          () => verifyCudaAvailability("EmbeddingWorker"),
+          isLdLibraryPathSetAtOsLevel
+        );
         if (!canUseCuda) {
           // Cannot switch to CUDA — respond with current (cpu) provider
           sendResponse({

package/src/index.ts

@@ -49,6 +49,33 @@ 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";
+
+// ONNX execution provider detection (CUDA EP `.so` availability gate)
+// Exported so the Phase 5 fork-child VRAM probe can gate CUDA selection on the
+// CUDA EP shared-library availability (FIND-IMPL-PR1-H-NEW-01), not just on
+// free VRAM. `verifyCudaAvailability` is a pure filesystem check (no GPU/native
+// init), safe to call from the fork-child leaf path.
+export {
+  detectExecutionProvider,
+  verifyCudaAvailability,
+  isLdLibraryPathSetAtOsLevel,
+} from "./onnx-provider-detect.js";
+export type { ExecutionProvider } from "./onnx-provider-detect.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;
+}