blackriver-gateway 3.8.46

package/scripts/build/build-next-isolated.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import {
+  assembleStandalone,
+  syncStandaloneNativeAssets as _syncNativeAssets,
+  syncStandaloneExtraModules as _syncExtraModules,
+} from "./assembleStandalone.mjs";
+import {
+  isBackendOnlyBuild,
+  stubDashboardPages,
+  restoreDashboardPages,
+} from "./backendOnlyPages.mjs";
+
+/**
+ * Layer 1: `app/` has been renamed to `dist/` and the App-Router collision is gone.
+ * The only transient paths remaining are `.tmp/wine32` (Wine prefix used by some
+ * older build tools) and `_tasks` (planning workspace).
+ */
+
+const projectRoot = process.cwd();
+const distDir = path.resolve(process.env.NEXT_DIST_DIR || ".build/next");
+const backupRoot = path.join(os.tmpdir(), `omniroute-build-isolated-${process.pid}-${Date.now()}`);
+
+export function getTransientBuildPaths(rootDir = projectRoot, env = process.env) {
+  const paths = [
+    {
+      label: "local Wine prefix",
+      sourcePath: path.join(rootDir, ".tmp", "wine32"),
+      backupPath: path.join(backupRoot, "wine32"),
+    },
+  ];
+
+  if (env.OMNIROUTE_BUILD_MOVE_TASKS === "1") {
+    paths.push({
+      label: "task planning workspace",
+      sourcePath: path.join(rootDir, "_tasks"),
+      backupPath: path.join(backupRoot, "_tasks"),
+    });
+  }
+
+  return paths;
+}
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function movePath(sourcePath, destinationPath, fsImpl = fs) {
+  const mkdir = typeof fsImpl.mkdir === "function" ? fsImpl.mkdir.bind(fsImpl) : fs.mkdir.bind(fs);
+  await mkdir(path.dirname(destinationPath), { recursive: true });
+
+  try {
+    await fsImpl.rename(sourcePath, destinationPath);
+  } catch (error) {
+    if (error?.code !== "EXDEV") {
+      throw error;
+    }
+
+    console.warn(
+      `[build-next-isolated] EXDEV while moving ${sourcePath} -> ${destinationPath}; falling back to copy/remove`
+    );
+    await fsImpl.cp(sourcePath, destinationPath, {
+      recursive: true,
+      preserveTimestamps: true,
+      force: false,
+      errorOnExist: true,
+    });
+    await fsImpl.rm(sourcePath, { recursive: true, force: true });
+  }
+}
+
+function runNextBuild() {
+  return new Promise((resolve) => {
+    const nextBin = path.join(projectRoot, "node_modules", "next", "dist", "bin", "next");
+    const child = spawn(process.execPath, [nextBin, "build", resolveNextBuildBundlerFlag()], {
+      cwd: projectRoot,
+      stdio: "inherit",
+      env: resolveNextBuildEnv(process.env),
+    });
+
+    const forward = (signal) => {
+      if (!child.killed) child.kill(signal);
+    };
+
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      if (signal) {
+        resolve({ code: 1, signal });
+        return;
+      }
+      resolve({ code: code ?? 1, signal: null });
+    });
+  });
+}
+
+export function resolveNextBuildBundlerFlag(baseEnv = process.env) {
+  // Turbopack is the default production bundler (Next 16 stable). Benchmarked on
+  // this codebase: 2-3x faster than the single-threaded webpack pass (17min -> 9min
+  // on a 32-core box; ~20min -> 7min on ubuntu-latest), artifact validated
+  // end-to-end (standalone smoke + e2e/package/electron CI jobs). Webpack stays as
+  // the explicit escape hatch (=0) for bundler-compat regressions.
+  return baseEnv.OMNIROUTE_USE_TURBOPACK === "0" ? "--webpack" : "--turbopack";
+}
+
+export function resolveNextBuildEnv(baseEnv = process.env) {
+  const env = {
+    ...baseEnv,
+    NEXT_PRIVATE_BUILD_WORKER: baseEnv.NEXT_PRIVATE_BUILD_WORKER || "0",
+  };
+
+  // Raise the Node heap for the spawned `next build`. The webpack production pass
+  // ("Compiling instrumentation" bundles the whole server graph) is the heaviest
+  // phase and overflows V8's default ~2 GB ceiling on memory-constrained machines,
+  // stalling/OOMing local `npm run build` (npm-global installs). #4076/#4104 fixed
+  // this only in the Docker builder stage (ENV NODE_OPTIONS); the local/native path
+  // was left unprotected. Respect an existing --max-old-space-size (Docker already
+  // sets one — don't clobber/duplicate) and let OMNIROUTE_BUILD_MEMORY_MB override.
+  if (!/--max-old-space-size/.test(env.NODE_OPTIONS || "")) {
+    // Default 8 GB (was 4 GB): the clean module graph peaks ~3.9 GB during the webpack
+    // production pass, which brushed the old 4 GB ceiling on a borderline OOM. 8 GB gives
+    // headroom without risk. NOTE: heap size does NOT fix a poisoned scope — if the build
+    // OOMs/livelocks far above this, check for worktrees/cruft leaking into the tsconfig
+    // scope (run `npm run check:build-scope`), not for "more heap". See incident 2026-06-25.
+    const heapMb = Number(baseEnv.OMNIROUTE_BUILD_MEMORY_MB) || 8192;
+    env.NODE_OPTIONS = `${env.NODE_OPTIONS || ""} --max-old-space-size=${heapMb}`.trim();
+  }
+
+  return env;
+}
+
+async function resetStandaloneOutput(rootDir = projectRoot, fsImpl = fs) {
+  // Use the module-level distDir so NEXT_DIST_DIR is respected
+  const resolvedDistDir =
+    rootDir === projectRoot
+      ? distDir
+      : path.join(rootDir, process.env.NEXT_DIST_DIR || ".build/next");
+  const standaloneRoot = path.join(resolvedDistDir, "standalone");
+  if (!(await exists(standaloneRoot))) return;
+
+  const staleStandaloneBackup = path.join(backupRoot, "standalone-stale");
+
+  await movePath(standaloneRoot, staleStandaloneBackup, fsImpl);
+  console.log("[build-next-isolated] Moved stale standalone output out of the build path");
+}
+
+export async function pruneStandaloneArtifacts(rootDir = projectRoot, fsImpl = fs) {
+  const resolvedDistDirForPrune =
+    rootDir === projectRoot
+      ? distDir
+      : path.join(rootDir, process.env.NEXT_DIST_DIR || ".build/next");
+  const standaloneRoot = path.join(resolvedDistDirForPrune, "standalone");
+  const pruneTargets = [path.join(standaloneRoot, "_tasks")];
+
+  for (const targetPath of pruneTargets) {
+    if (!(await exists(targetPath))) continue;
+    await fsImpl.rm(targetPath, { recursive: true, force: true });
+    console.log(
+      `[build-next-isolated] Pruned standalone artifact: ${path.relative(rootDir, targetPath)}`
+    );
+  }
+}
+
+export async function syncStandaloneNativeAssets(
+  rootDir = projectRoot,
+  fsImpl = fs,
+  log = console
+) {
+  return _syncNativeAssets(rootDir, fsImpl, log);
+}
+
+export async function syncStandaloneExtraModules(
+  rootDir = projectRoot,
+  fsImpl = fs,
+  log = console
+) {
+  return _syncExtraModules(rootDir, fsImpl, log);
+}
+
+export async function main() {
+  const movedPaths = [];
+  const transientBuildPaths = getTransientBuildPaths();
+
+  // Backend-only fast build: replace the dashboard leaf pages with zero-cost stubs so
+  // `next build` skips the frontend (client vendor chunks + prerender) while keeping every
+  // API route handler. Restored in `finally` and on SIGINT/SIGTERM (git-recoverable regardless).
+  let stubbedPages = [];
+  const restoreStubbedPagesOnce = () => {
+    if (stubbedPages.length > 0) {
+      restoreDashboardPages(stubbedPages);
+      stubbedPages = [];
+    }
+  };
+  const onFatalSignal = (signal) => {
+    console.warn(`[build-next-isolated] Received ${signal} — restoring stubbed pages before exit`);
+    restoreStubbedPagesOnce();
+    process.exit(1);
+  };
+
+  try {
+    for (const entry of transientBuildPaths) {
+      if (!(await exists(entry.sourcePath))) continue;
+      await movePath(entry.sourcePath, entry.backupPath);
+      movedPaths.push(entry);
+    }
+
+    if (isBackendOnlyBuild()) {
+      console.log(
+        "[build-next-isolated] OMNIROUTE_BUILD_BACKEND_ONLY set — building API only (dashboard UI stubbed)"
+      );
+      stubbedPages = stubDashboardPages(projectRoot);
+      process.once("SIGINT", onFatalSignal);
+      process.once("SIGTERM", onFatalSignal);
+    }
+
+    await resetStandaloneOutput(projectRoot);
+
+    const result = await runNextBuild();
+    const standaloneDir = path.join(distDir, "standalone");
+    if (result.code === 0 && (await exists(standaloneDir))) {
+      try {
+        await fs.cp(path.join(projectRoot, "docs"), path.join(standaloneDir, "docs"), {
+          recursive: true,
+        });
+        console.log("[build-next-isolated] Copied docs/ to standalone output");
+      } catch (docsCopyErr) {
+        console.warn("[build-next-isolated] Non-fatal error copying docs/:", docsCopyErr?.message);
+      }
+
+      try {
+        await pruneStandaloneArtifacts(projectRoot);
+      } catch (pruneErr) {
+        console.warn(
+          "[build-next-isolated] Non-fatal error pruning standalone artifacts:",
+          pruneErr
+        );
+      }
+
+      // Best-effort: build the TPROXY native addon (Linux-only, opt-in) BEFORE
+      // assembling, so its transparent.node is present for assembleStandalone's
+      // NATIVE_ASSET_ENTRIES copy. Non-Linux / no-toolchain is non-fatal — the
+      // capture mode degrades gracefully when the addon is absent.
+      try {
+        const { buildTproxyNative } = await import("./build-tproxy-native.mjs");
+        const res = buildTproxyNative(projectRoot);
+        console.log(
+          res.built
+            ? "[build-next-isolated] Built TPROXY native addon (transparent.node)"
+            : `[build-next-isolated] TPROXY native addon skipped: ${res.reason}`
+        );
+      } catch (nativeErr) {
+        console.warn(
+          "[build-next-isolated] Non-fatal error building TPROXY native addon:",
+          nativeErr?.message
+        );
+      }
+
+      try {
+        console.log(
+          "[build-next-isolated] Assembling standalone bundle (static + public + natives + extras)..."
+        );
+        assembleStandalone({
+          distDir,
+          outDir: standaloneDir,
+          projectRoot,
+          copyNatives: true,
+        });
+      } catch (assembleErr) {
+        console.warn("[build-next-isolated] Non-fatal error assembling standalone:", assembleErr);
+      }
+    }
+    process.exitCode = result.code;
+  } catch (error) {
+    console.error("[build-next-isolated] Build failed:", error);
+    process.exitCode = 1;
+  } finally {
+    // Restore the stubbed dashboard pages FIRST so the working tree is clean even if the
+    // transient-path restore below throws.
+    restoreStubbedPagesOnce();
+    process.off("SIGINT", onFatalSignal);
+    process.off("SIGTERM", onFatalSignal);
+
+    while (movedPaths.length > 0) {
+      const entry = movedPaths.pop();
+      if (!entry) continue;
+      try {
+        await movePath(entry.backupPath, entry.sourcePath);
+      } catch (restoreError) {
+        console.error(
+          `[build-next-isolated] Failed to restore ${entry.label} from ${entry.backupPath}:`,
+          restoreError
+        );
+        process.exitCode = 1;
+      }
+    }
+
+    try {
+      await fs.rm(backupRoot, { recursive: true, force: true });
+    } catch (cleanupError) {
+      console.warn("[build-next-isolated] Failed to clean temporary backup root:", cleanupError);
+    }
+  }
+}
+
+const entryScript = process.argv[1] ? pathToFileURL(process.argv[1]).href : null;
+
+if (entryScript === import.meta.url) {
+  await main();
+}

package/scripts/build/colocateOptionals.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * OmniRoute — Co-locate the LLMLingua-2 optional dependency closure into the standalone bundle.
+ *
+ * The compression "ultra" SLM tier (PR #4257) runs `@atjsh/llmlingua-2` +
+ * `@huggingface/transformers` + `@tensorflow/tfjs` + `js-tiktoken` inside a worker thread
+ * (`open-sse/services/compression/engines/llmlingua/onnxWorker.js`, shipped under `dist/`). These
+ * are `optionalDependencies`: npm installs them into the ROOT `node_modules` on
+ * `--include=optional`, but the Next.js standalone trace bundles ONLY `@huggingface/transformers`
+ * (3.5.2, pinned) into `dist/node_modules` — it does NOT trace the optional, dynamically-imported
+ * SLM packages.
+ *
+ * ## Why this matters (the instance-split bug)
+ *
+ * The worker lives under `dist/`, so its `import("@huggingface/transformers")` resolves
+ * `dist/node_modules/@huggingface/transformers` (3.5.2) and the worker sets the model `cacheDir`
+ * on THAT instance's `env`. But its `import("@atjsh/llmlingua-2")` walks past `dist/node_modules`
+ * (no `@atjsh` there) up to the ROOT `node_modules`, and llmlingua-2's own
+ * `import("@huggingface/transformers")` then resolves the ROOT transformers — a DIFFERENT instance.
+ * The `cacheDir`/`localModelPath` config the worker set never reaches the instance llmlingua-2
+ * actually uses, so the local model under `DATA_DIR/models/llmlingua` is never found and the SLM
+ * tier silently fails-open (no compression). Worse, if the root transformers is a 4.x line,
+ * llmlingua-2 throws on a tokenizer-API change (`decoder.decode` is undefined).
+ *
+ * ## The fix
+ *
+ * Co-locate the SLM optional dependency CLOSURE from the root `node_modules` into
+ * `dist/node_modules` (NO-CLOBBER, so the pinned `dist` transformers 3.5.2 / onnxruntime / sharp
+ * stay). Then the worker resolves `@atjsh/llmlingua-2` AND `@huggingface/transformers` from the
+ * SAME `dist/node_modules` — a single 3.5.2 instance — so the env config applies and the local
+ * model loads.
+ *
+ * `@huggingface/transformers` is intentionally NOT a closure seed: it is a PEER of
+ * `@atjsh/llmlingua-2` (not a regular dependency) and is already bundled in `dist/node_modules`,
+ * so the closure walk never reaches it and the no-clobber guard would skip it anyway.
+ *
+ * ## Validation (Hard Rule #18)
+ *
+ * Manual co-location of this exact closure on the production VPS produced real 54.8% compression
+ * (11520 → 5203 chars) via real ONNX inference — both the default and the `modelPath` (PR #4257)
+ * code paths. See the unit test for the closure-walk + no-clobber contract.
+ *
+ * Idempotent + fail-soft: skips when the optionals are absent (the common case — they are OPTIONAL)
+ * or already co-located; a per-package copy failure only disables the SLM tier, which is itself
+ * fail-open, so this never throws into the install.
+ */
+
+import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Entry packages of the SLM optional stack (the closure roots). `@huggingface/transformers` is
+ * deliberately absent — it is the pinned instance already present in `dist/node_modules`.
+ */
+export const SEED_PACKAGES = ["@atjsh/llmlingua-2", "@tensorflow/tfjs", "js-tiktoken"];
+
+/**
+ * Compute the transitive dependency closure of `seeds` by walking each package's `dependencies` +
+ * `optionalDependencies` from a `node_modules` directory. Packages that are not present in that
+ * tree (e.g. peers provided elsewhere, like `@huggingface/transformers` in `dist`) are skipped —
+ * the closure only contains packages that actually exist in `nodeModulesDir`.
+ *
+ * @param {string} nodeModulesDir absolute path to the source `node_modules`
+ * @param {string[]} [seeds] closure roots (defaults to {@link SEED_PACKAGES})
+ * @returns {string[]} package names in discovery order, seeds first
+ */
+export function computeDependencyClosure(nodeModulesDir, seeds = SEED_PACKAGES) {
+  const closure = [];
+  const seen = new Set();
+  const stack = [...seeds];
+
+  while (stack.length) {
+    const name = stack.shift();
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    const pkgDir = join(nodeModulesDir, name);
+    if (!existsSync(pkgDir)) continue; // absent in this tree (peer provided elsewhere) — skip
+
+    closure.push(name);
+
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+    } catch {
+      continue; // unreadable/absent manifest — copy the dir but do not recurse
+    }
+
+    const deps = { ...manifest.dependencies, ...manifest.optionalDependencies };
+    for (const dep of Object.keys(deps)) {
+      if (!seen.has(dep)) stack.push(dep);
+    }
+  }
+
+  return closure;
+}
+
+/**
+ * Co-locate the SLM optional closure from `<rootDir>/node_modules` into
+ * `<rootDir>/dist/node_modules`. No-op when the standalone `dist` bundle or the optional seeds are
+ * absent, and idempotent once co-located. Never throws.
+ *
+ * @param {{ rootDir: string, log?: (message: string) => void }} opts
+ * @returns {{ skipped: true, reason: string }
+ *   | { skipped: false, copied: number, closure: number }}
+ */
+export function colocateLlmlinguaOptionals({ rootDir, log = () => {} }) {
+  const rootNm = join(rootDir, "node_modules");
+  const distNm = join(rootDir, "dist", "node_modules");
+
+  if (!existsSync(distNm)) {
+    return { skipped: true, reason: "no standalone dist/node_modules" };
+  }
+  // Gate: only run when the optional stack was actually installed (`npm install --include=optional`).
+  if (!SEED_PACKAGES.every((seed) => existsSync(join(rootNm, seed)))) {
+    return { skipped: true, reason: "SLM optionals not installed at root" };
+  }
+  // Idempotent: the entry package is already co-located → nothing to do.
+  if (existsSync(join(distNm, "@atjsh", "llmlingua-2"))) {
+    return { skipped: true, reason: "already co-located" };
+  }
+
+  const closure = computeDependencyClosure(rootNm);
+  let copied = 0;
+
+  for (const name of closure) {
+    const dest = join(distNm, name);
+    if (existsSync(dest)) continue; // no-clobber: keep dist's pinned copy (transformers 3.5.2, …)
+    try {
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(join(rootNm, name), dest, { recursive: true });
+      copied++;
+    } catch (err) {
+      log(`  ⚠️  LLMLingua optional co-location failed for ${name}: ${err.message}`);
+    }
+  }
+
+  if (copied > 0) {
+    log(`  ✅ Co-located ${copied} LLMLingua SLM optional package(s) into dist/node_modules.\n`);
+  }
+
+  return { skipped: false, copied, closure: closure.length };
+}

package/scripts/build/native-binary-compat.mjs

@@ -0,0 +1,167 @@
+import { existsSync, openSync, readSync, closeSync } from "node:fs";
+
+export const PUBLISHED_BUILD_PLATFORM = "linux";
+export const PUBLISHED_BUILD_ARCH = "x64";
+
+const HEADER_SIZE = 4096;
+const MAX_FAT_ARCH_COUNT = 30;
+
+function mapElfMachine(machine) {
+  switch (machine) {
+    case 62:
+      return "x64";
+    case 183:
+      return "arm64";
+    default:
+      return null;
+  }
+}
+
+function mapMachCpuType(cpuType) {
+  switch (cpuType) {
+    case 0x01000007:
+      return "x64";
+    case 0x0100000c:
+      return "arm64";
+    default:
+      return null;
+  }
+}
+
+function mapPeMachine(machine) {
+  switch (machine) {
+    case 0x8664:
+      return "x64";
+    case 0xaa64:
+      return "arm64";
+    default:
+      return null;
+  }
+}
+
+function readUInt16(buffer, offset, littleEndian) {
+  return littleEndian ? buffer.readUInt16LE(offset) : buffer.readUInt16BE(offset);
+}
+
+function readUInt32(buffer, offset, littleEndian) {
+  return littleEndian ? buffer.readUInt32LE(offset) : buffer.readUInt32BE(offset);
+}
+
+const ELF_MAGIC = 0x7f454c46;
+
+function detectElfTarget(buffer) {
+  if (buffer.length < 20) return null;
+  if (buffer.readUInt32BE(0) !== ELF_MAGIC) return null;
+
+  const littleEndian = buffer[5] !== 2;
+  const arch = mapElfMachine(readUInt16(buffer, 18, littleEndian));
+  if (!arch) return null;
+
+  return { platform: "linux", architectures: [arch] };
+}
+
+const THIN_MACH_MAGIC = new Map([
+  [0xfeedface, false],
+  [0xfeedfacf, false],
+  [0xcefaedfe, true],
+  [0xcffaedfe, true],
+]);
+const FAT_MACH_MAGIC = new Map([
+  [0xcafebabe, false],
+  [0xcafebabf, false],
+  [0xbebafeca, true],
+  [0xbfbafeca, true],
+]);
+
+function detectMachTarget(buffer) {
+  if (buffer.length < 8) return null;
+
+  const magic = buffer.readUInt32BE(0);
+
+  if (THIN_MACH_MAGIC.has(magic)) {
+    const littleEndian = THIN_MACH_MAGIC.get(magic);
+    const arch = mapMachCpuType(readUInt32(buffer, 4, littleEndian));
+    if (!arch) return null;
+    return { platform: "darwin", architectures: [arch] };
+  }
+
+  if (!FAT_MACH_MAGIC.has(magic)) return null;
+
+  const littleEndian = FAT_MACH_MAGIC.get(magic);
+  const isFat64 = magic === 0xcafebabf || magic === 0xbfbafeca;
+  const archCount = readUInt32(buffer, 4, littleEndian);
+  if (archCount > MAX_FAT_ARCH_COUNT) return null;
+  const entrySize = isFat64 ? 32 : 20;
+  const architectures = new Set();
+
+  for (let index = 0; index < archCount; index += 1) {
+    const offset = 8 + index * entrySize;
+    if (offset + 4 > buffer.length) break;
+    const arch = mapMachCpuType(readUInt32(buffer, offset, littleEndian));
+    if (arch) architectures.add(arch);
+  }
+
+  if (architectures.size === 0) return null;
+  return { platform: "darwin", architectures: [...architectures] };
+}
+
+function detectPeTarget(buffer) {
+  if (buffer.length < 0x40) return null;
+  if (buffer.readUInt16LE(0) !== 0x5a4d) return null;
+
+  const peHeaderOffset = buffer.readUInt32LE(0x3c);
+  if (peHeaderOffset + 6 > buffer.length) return null;
+  if (buffer.readUInt32LE(peHeaderOffset) !== 0x00004550) return null;
+
+  const arch = mapPeMachine(buffer.readUInt16LE(peHeaderOffset + 4));
+  if (!arch) return null;
+  return { platform: "win32", architectures: [arch] };
+}
+
+export function detectNativeBinaryTarget(buffer) {
+  return detectElfTarget(buffer) ?? detectMachTarget(buffer) ?? detectPeTarget(buffer);
+}
+
+export function readNativeBinaryTarget(binaryPath) {
+  if (!existsSync(binaryPath)) return null;
+
+  let fd;
+  try {
+    fd = openSync(binaryPath, "r");
+    const buffer = Buffer.alloc(HEADER_SIZE);
+    const bytesRead = readSync(fd, buffer, 0, HEADER_SIZE, 0);
+    return detectNativeBinaryTarget(buffer.subarray(0, bytesRead));
+  } catch (err) {
+    console.warn(`  ⚠️  Could not read native binary at ${binaryPath}: ${err.message}`);
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function isNativeBinaryCompatible(
+  binaryPath,
+  { runtimePlatform = process.platform, runtimeArch = process.arch, dlopen = process.dlopen } = {}
+) {
+  const target = readNativeBinaryTarget(binaryPath);
+
+  if (target) {
+    if (
+      (target.platform !== runtimePlatform &&
+        !(target.platform === "linux" && runtimePlatform === "android")) ||
+      !target.architectures.includes(runtimeArch)
+    ) {
+      return false;
+    }
+  } else if (runtimePlatform !== PUBLISHED_BUILD_PLATFORM || runtimeArch !== PUBLISHED_BUILD_ARCH) {
+    return false;
+  }
+
+  try {
+    dlopen({ exports: {} }, binaryPath);
+    return true;
+  } catch (err) {
+    console.warn(`  ⚠️  Native binary dlopen failed: ${err.message}`);
+    return false;
+  }
+}