js: point GenAI at ORT via ORT_LIB_PATH; drop the unversioned dylib alias

onnxruntime-genai's InitApi() (built with dlopen on macOS-non-framework and
Linux, per its CMakeLists) honors the ORT_LIB_PATH env var: it dlopens that exact
file before its hardcoded unversioned libonnxruntime.{dylib,so} fallback. Set it
in the JS addon loader to the ORT we ship, so the package no longer needs the
unversioned alias purely for GenAI:

- detail/native.ts: applyOrtLibPath() sets ORT_LIB_PATH (only if unset) to the
  resolved ORT in the prebuilds dir, or the configured libraryPath, before the
  addon -- and thus GenAI's lazy InitApi -- loads. No-op on Windows (ORT is linked
  directly, no dlopen). ortCandidateBasenames now prefers the versioned soname.
- install-native.cjs: rename the extracted unversioned ORT to the versioned soname
  (libonnxruntime.1.dylib / .so.1) that libfoundry_local records, instead of
  symlinking and keeping both -- one file, no symlink.
- copy-native.mjs: dev staging copies the versioned soname only, matching ship.

macOS CI (js_test_osx_arm64) runs npm ci (install-native postinstall) + vitest
with FOUNDRY_TEST_DATA_DIR set, so the real-model path that loads GenAI exercises
this end to end. The C++ build keeps its own ORT symlink for the C++ test harness,
which does not set ORT_LIB_PATH.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bmehta001

sdk_v2/js/script/copy-native.mjs

@@ -58,20 +58,17 @@ const wanted = (() => {
     ];
   }
   if (process.platform === "darwin") {
-    // The ORT dylib is referenced under two fixed names: foundry_local loads it by
-    // its soversion install_name (libonnxruntime.1.dylib), while GenAI's static
-    // initializer dlopen()s the unversioned libonnxruntime.dylib. Both must sit
-    // beside the addon. Shipped packages symlink one name to the other to avoid
-    // duplicating the ~24MB binary; this dev-only staging just copies both, since
-    // the duplicate never leaves the machine.
+    // Copy only the versioned ORT soname (libonnxruntime.1.dylib) — the name
+    // libfoundry_local records. GenAI is pointed at it via ORT_LIB_PATH (set by the
+    // addon loader in detail/native.ts), so the unversioned alias isn't needed. The
+    // C++ build stages the versioned name as a symlink; copyFileSync dereferences it.
     return [
       "libfoundry_local.dylib",
-      "libonnxruntime.dylib",
       "libonnxruntime.1.dylib",
       "libonnxruntime-genai.dylib",
     ];
   }
-  return ["libfoundry_local.so", "libonnxruntime.so", "libonnxruntime.so.1", "libonnxruntime-genai.so"];
+  return ["libfoundry_local.so", "libonnxruntime.so.1", "libonnxruntime-genai.so"];
 })();
 
 let copied = 0;

sdk_v2/js/script/install-native.cjs

@@ -225,38 +225,32 @@ async function installPackage(artifact, tempDir, binDir) {
     );
 }
 
-// Mirror the platform-specific post-build steps that sdk_v2/cpp/CMakeLists.txt
-// runs after building libfoundry_local. The Foundry ORT nupkg ships only the
-// unversioned `libonnxruntime.{so,dylib}`, but libfoundry_local records a
-// versioned SONAME/install_name dependency (libonnxruntime.so.1 /
-// libonnxruntime.1.dylib), so we add that soname symlink next to the shipped
-// file. GenAI continues to dlopen the unversioned name, which stays as-is.
-function applyOrtPlatformAliases(binDir, ortVersion) {
+// The Foundry ORT nupkg extracts the unversioned `libonnxruntime.{so,dylib}`, but
+// libfoundry_local records a versioned SONAME/install_name dependency
+// (libonnxruntime.so.1 / libonnxruntime.1.dylib). Rename the extracted file to that
+// versioned soname so foundry_local resolves it via rpath. GenAI is pointed at the
+// same file by the ORT_LIB_PATH env var the addon loader sets (onnxruntime-genai
+// honors it before its unversioned-name fallback), so no unversioned alias is
+// shipped. Windows uses onnxruntime.dll, which has no soname.
+function normalizeOrtLibName(binDir, ortVersion) {
+    let unversioned;
+    let versioned;
     if (os.platform() === 'linux') {
-        const unv = path.join(binDir, 'libonnxruntime.so');
-        const soname = path.join(binDir, 'libonnxruntime.so.1');
-        if (fs.existsSync(unv) && !fs.existsSync(soname)) {
-            try {
-                fs.symlinkSync('libonnxruntime.so', soname);
-                console.log(`  Created symlink libonnxruntime.so.1 -> libonnxruntime.so`);
-            } catch (err) {
-                fs.copyFileSync(unv, soname);
-                console.log(`  Copied libonnxruntime.so -> libonnxruntime.so.1 (symlink failed: ${err.message})`);
-            }
-        }
+        unversioned = path.join(binDir, 'libonnxruntime.so');
+        versioned = path.join(binDir, 'libonnxruntime.so.1');
     } else if (os.platform() === 'darwin') {
         const major = ortVersion.split('.')[0];
-        const unv = path.join(binDir, 'libonnxruntime.dylib');
-        const soname = path.join(binDir, `libonnxruntime.${major}.dylib`);
-        if (fs.existsSync(unv) && !fs.existsSync(soname)) {
-            try {
-                fs.symlinkSync('libonnxruntime.dylib', soname);
-                console.log(`  Created symlink libonnxruntime.${major}.dylib -> libonnxruntime.dylib`);
-            } catch (err) {
-                fs.copyFileSync(unv, soname);
-                console.log(`  Copied libonnxruntime.dylib -> libonnxruntime.${major}.dylib (symlink failed: ${err.message})`);
-            }
-        }
+        unversioned = path.join(binDir, 'libonnxruntime.dylib');
+        versioned = path.join(binDir, `libonnxruntime.${major}.dylib`);
+    } else {
+        return;
+    }
+    if (fs.existsSync(versioned)) {
+        return;
+    }
+    if (fs.existsSync(unversioned)) {
+        fs.renameSync(unversioned, versioned);
+        console.log(`  Renamed ${path.basename(unversioned)} -> ${path.basename(versioned)}`);
     }
 }
 
@@ -269,7 +263,7 @@ function applyOrtPlatformAliases(binDir, ortVersion) {
         for (const artifact of ARTIFACTS) {
             await installPackage(artifact, tempDir, BIN_DIR);
         }
-        applyOrtPlatformAliases(BIN_DIR, ortVersion);
+        normalizeOrtLibName(BIN_DIR, ortVersion);
         console.log('[foundry-local] Native runtime install complete.');
     } catch (err) {
         console.error('[foundry-local] Installation failed:', err instanceof Error ? err.message : err);

sdk_v2/js/src/detail/native.ts

@@ -258,6 +258,8 @@ function loadAddon(): NativeAddon {
       `Native addon not found at ${addonPath}.\nBuild it locally with:\n  npm run copy-native:dev && npm run build:native\n(requires the C++ SDK to be built first via\n \`python sdk_v2/cpp/build.py --configure --build --config RelWithDebInfo\`).\nAlternatively, pass \`libraryPath\` in the FoundryLocalConfig (or call \`configureNativeLoader\`) to point at a directory containing the native library.`,
     );
   }
+  // Point GenAI at the ORT bundled next to the addon before the addon loads.
+  applyOrtLibPath(prebuildDir);
   const require = createRequire(import.meta.url);
   return require(addonPath) as NativeAddon;
 }
@@ -284,20 +286,44 @@ function nativeLibBasename(): string {
 
 /**
  * Candidate basenames for an ORT-family library on the current platform. The loader tries them in order and
- * uses the first that exists on disk. The Foundry nupkg ships the unversioned `libonnxruntime.{so,dylib}`;
- * we add the versioned soname (`libonnxruntime.so.1` / `libonnxruntime.1.dylib`) beside it, which is the name
- * libfoundry_local actually records, so both are listed as fallbacks. GenAI has no versioned variant.
+ * uses the first that exists on disk. We ship the versioned soname (`libonnxruntime.so.1` /
+ * `libonnxruntime.1.dylib`) — the name libfoundry_local records — and point GenAI at it via ORT_LIB_PATH
+ * (see applyOrtLibPath). The unversioned name is kept only as a tolerant fallback for layouts that still
+ * stage it (e.g. the raw C++ build output). GenAI has no versioned variant of its own.
  */
 function ortCandidateBasenames(name: "onnxruntime" | "onnxruntime-genai"): string[] {
   if (process.platform === "win32") return [`${name}.dll`];
   if (process.platform === "darwin") {
-    if (name === "onnxruntime") return ["libonnxruntime.dylib", "libonnxruntime.1.dylib"];
+    if (name === "onnxruntime") return ["libonnxruntime.1.dylib", "libonnxruntime.dylib"];
     return [`lib${name}.dylib`];
   }
-  if (name === "onnxruntime") return ["libonnxruntime.so", "libonnxruntime.so.1"];
+  if (name === "onnxruntime") return ["libonnxruntime.so.1", "libonnxruntime.so"];
   return [`lib${name}.so`];
 }
 
+/**
+ * Point onnxruntime-genai at the exact ORT we ship, via the `ORT_LIB_PATH` env var.
+ *
+ * On macOS/Linux the GenAI library (built with dlopen support) resolves ORT in its `InitApi()` by first
+ * dlopen-ing `$ORT_LIB_PATH`, then falling back to the unversioned `libonnxruntime.{dylib,so}` leafname. We
+ * ship only the versioned soname (the name libfoundry_local records), so setting `ORT_LIB_PATH` to it is what
+ * lets the package omit the unversioned alias entirely. Windows links ORT directly (no dlopen), so this is a
+ * no-op there.
+ *
+ * Must run before the addon loads (GenAI's `InitApi` is lazy, fired by the first model load). Never clobbers a
+ * caller-provided `ORT_LIB_PATH`.
+ */
+function applyOrtLibPath(directory: string): void {
+  if (process.platform === "win32" || process.env.ORT_LIB_PATH) return;
+  for (const basename of ortCandidateBasenames("onnxruntime")) {
+    const fullPath = resolve(directory, basename);
+    if (existsSync(fullPath)) {
+      process.env.ORT_LIB_PATH = fullPath;
+      return;
+    }
+  }
+}
+
 /**
  * Pre-load ORT and ORT-GenAI from `directory` by absolute path so that when foundry_local is loaded, the OS
  * loader resolves its NEEDED entries against the already-resident modules instead of doing a filesystem search
@@ -377,6 +403,9 @@ export function configureNativeLoader(opts: { libraryPath?: string }): void {
   // (.github/instructions/ort-loading-contract.instructions.md) — every binding must do this.
   preloadOrtIfPresent(libraryPath);
 
+  // Point GenAI at the ORT in this directory (takes precedence over the default prebuilds lookup).
+  applyOrtLibPath(libraryPath);
+
   try {
     getPreloadAddon().preloadLibrary(fullPath);
   } catch (err) {