@reftrixmcp/ml 0.1.7 → 0.5.1

package/dist/onnx-availability.js

@@ -0,0 +1,69 @@
+// 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 = null;
+let _unavailableReason = null;
+/**
+ * Check if onnxruntime-node is available (async, caches result).
+ */
+export async function isOnnxRuntimeAvailable() {
+    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() {
+    return _available;
+}
+/**
+ * Returns the reason onnxruntime-node is unavailable, or null if available.
+ */
+export function getOnnxUnavailableReason() {
+    return _unavailableReason;
+}
+/**
+ * Error thrown when ML features require onnxruntime-node but it is not installed.
+ */
+export class OnnxRuntimeUnavailableError extends Error {
+    constructor(context) {
+        super(`ML features require onnxruntime-node which is not available. ` +
+            `Install with: pnpm add onnxruntime-node` +
+            (context ? ` (${context})` : ""));
+        this.name = "OnnxRuntimeUnavailableError";
+    }
+}
+/**
+ * Safely import onnxruntime-node with a sanitized error on failure.
+ */
+export async function safeImportOnnx() {
+    try {
+        return await import("onnxruntime-node");
+    }
+    catch {
+        throw new OnnxRuntimeUnavailableError();
+    }
+}
+/**
+ * For testing: reset cached state.
+ */
+export function _resetForTesting() {
+    _available = null;
+    _unavailableReason = null;
+}
+//# sourceMappingURL=onnx-availability.js.map

package/dist/onnx-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-availability.js","sourceRoot":"","sources":["../src/onnx-availability.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,yCAAyC;AAEzC;;;;;GAKG;AAEH,IAAI,UAAU,GAAmB,IAAI,CAAC;AACtC,IAAI,kBAAkB,GAAkB,IAAI,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACjC,UAAU,GAAG,IAAI,CAAC;QAClB,kBAAkB,GAAG,IAAI,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,UAAU,GAAG,KAAK,CAAC;QACnB,kBAAkB,GAAG,mCAAmC,CAAC;IAC3D,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,OAAgB;QAC1B,KAAK,CACH,+DAA+D;YAC7D,yCAAyC;YACzC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CACnC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAKD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,2BAA2B,EAAE,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,UAAU,GAAG,IAAI,CAAC;IAClB,kBAAkB,GAAG,IAAI,CAAC;AAC5B,CAAC"}

package/dist/onnx-provider-detect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+export 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.
+ *
+ * @param logPrefix - Log prefix for warning messages (e.g. "EmbeddingWorker", "DINOv2Worker")
+ */
+export declare function detectExecutionProvider(logPrefix?: string): ExecutionProvider;
+/**
+ * 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 declare function verifyCudaAvailability(logPrefix?: string): boolean;
+/**
+ * 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 declare function isLdLibraryPathSetAtOsLevel(): boolean;
+//# sourceMappingURL=onnx-provider-detect.d.ts.map

package/dist/onnx-provider-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-provider-detect.d.ts","sourceRoot":"","sources":["../src/onnx-provider-detect.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAUH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,CAAC;AAM/C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAkB7E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAqClE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAQrD"}

package/dist/onnx-provider-detect.js

@@ -0,0 +1,111 @@
+// 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";
+// =====================================================
+// 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) {
+    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) {
+    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() {
+    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;
+    }
+}
+//# sourceMappingURL=onnx-provider-detect.js.map

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.1.7",
+  "version": "0.5.1",
   "license": "AGPL-3.0-only",
   "type": "module",
   "description": "ML/Embedding services for Reftrix",
@@ -30,16 +30,21 @@
   },
   "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.1.7"
+    "@reftrixmcp/config": "0.5.1"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "repository": {
     "type": "git",

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,16 +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"],
-    });
+    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;
@@ -317,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) {
@@ -332,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++) {
@@ -469,6 +549,23 @@ export class DINOv2Service {
     this._isInitialized = false;
   }
 
+  /**
+   * Recycle the ONNX session to free accumulated native memory.
+   *
+   * Performs dispose() followed by initialize() to reset the ONNX Runtime
+   * internal memory allocations. The modelPath is reused from the original
+   * configuration (DINO-3: no re-read of process.env["DINOV2_MODEL_PATH"]).
+   *
+   * If re-initialization fails, the service is left in a disposed state.
+   * Callers should handle this gracefully (Graceful Degradation).
+   *
+   * @throws {Error} If re-initialization fails after disposal
+   */
+  async recycle(): Promise<void> {
+    await this.dispose();
+    await this.initialize();
+  }
+
   /**
    * Terminate the worker thread completely and clean up.
    * After this, the service cannot be used until a new instance is created.