sweet-search 2.5.2 → 2.5.4

package/core/infrastructure/language-patterns/registry-core.js

@@ -221,6 +221,7 @@ export const CORE_LANGUAGES = {
       enum: /^(?:pub\s+)?enum\s+(\w+)/,
       trait: /^(?:pub\s+)?trait\s+(\w+)/,
       impl: /^impl(?:<[^>]+>)?\s+(?:\w+\s+for\s+)?(\w+)/,
+      macro: /^macro_rules!\s+(\w+)/,
     },
     graph: {
       entities: {
@@ -232,6 +233,7 @@ export const CORE_LANGUAGES = {
         type: /^(?:pub\s+)?type\s+(\w+)/,
         const: /^(?:pub\s+)?const\s+(\w+)\s*:/,
         static: /^(?:pub\s+)?static\s+(\w+)\s*:/,
+        macro: /^macro_rules!\s+(\w+)/,
       },
       relationships: {
         use: /^use\s+([\w:]+)(?:::\{([^}]+)\})?/,
@@ -252,13 +254,21 @@ export const CORE_LANGUAGES = {
     },
     chunker: {
       function: /^(?:[\w*\s]+)\s+(\w+)\s*\([^)]*\)\s*\{/,
-      struct: /^(?:typedef\s+)?struct\s+(\w+)/,
+      // Skip attribute-like prefixes between `struct` and the type name:
+      //   - function-like attrs: __attribute__((...)), __declspec(...), _Alignas(N), __forceinline(...), __inline__(...)
+      //     Paren matcher allows up to 3 nesting levels — __attribute__ standardly takes
+      //     a doubly-parenthesized arg, optionally containing call-form attrs like aligned(8).
+      //   - C++11 attribute syntax: [[ ... ]]
+      //   - ALL_CAPS user macros (≥3 chars): PACKED_API, HWY_DLLEXPORT, EIGEN_API, etc.
+      // Without this, `struct __attribute__((packed)) Foo` captured `__attribute__` as the name.
+      // Backtracking handles ALL_CAPS-named forward decls (`struct WHEEL;`).
+      struct: /^(?:typedef\s+)?struct(?:\s+(?:__attribute__|__declspec|_Alignas|__forceinline|__inline__)\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)|\s+\[\[[^\]]*\]\]|\s+[A-Z][A-Z0-9_]{2,})*\s+(\w+)/,
       enum: /^(?:typedef\s+)?enum\s+(\w+)/,
     },
     graph: {
       entities: {
         function: /^(?:static\s+)?(?:inline\s+)?(?:[\w*]+\s+)+(\w+)\s*\([^)]*\)\s*\{/,
-        struct: /^(?:typedef\s+)?struct\s+(\w+)/,
+        struct: /^(?:typedef\s+)?struct(?:\s+(?:__attribute__|__declspec|_Alignas|__forceinline|__inline__)\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)|\s+\[\[[^\]]*\]\]|\s+[A-Z][A-Z0-9_]{2,})*\s+(\w+)/,
         enum: /^(?:typedef\s+)?enum\s+(\w+)/,
         typedef: /^typedef\s+.+\s+(\w+)\s*;/,
         macro: /^#define\s+(\w+)/,
@@ -279,14 +289,26 @@ export const CORE_LANGUAGES = {
       block: ["/*", "*/"],
     },
     chunker: {
-      class: /^(?:class|struct)\s+(\w+)(?:\s*:\s*(?:public|protected|private)\s+(\w+))?/,
+      // Skip attribute-like prefixes between `class`/`struct` and the type name.
+      // Closed list of standard attributes:
+      //   - function-like: alignas(N), __attribute__((...)), __declspec(...),
+      //     __forceinline(...). Paren matcher allows up to 3 nesting levels —
+      //     __attribute__ standardly takes a doubly-parenthesized arg, optionally
+      //     containing call-form attrs like aligned(8).
+      //   - C++11 attribute syntax: [[ ... ]]
+      //   - ALL_CAPS user macros (≥3 chars): HWY_DLLEXPORT, EIGEN_API, FMT_API, etc.
+      //     Common in dllexport/visibility shims across header-only C++ libraries.
+      // Without this, `struct alignas(16) uint128_t` captured `alignas` as the
+      // struct name (CPP-005 failure root cause). Backtracking preserves capture of
+      // ALL_CAPS forward decls like `class WHEEL;`.
+      class: /^(?:class|struct)(?:\s+(?:alignas|__attribute__|__declspec|__forceinline)\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)|\s+\[\[[^\]]*\]\]|\s+[A-Z][A-Z0-9_]{2,})*\s+(\w+)(?:\s*:\s*(?:public|protected|private)\s+(\w+))?/,
       function: /^(?:[\w:*&<>\s]+)\s+(\w+)\s*\([^)]*\)\s*(?:const)?\s*(?:override)?\s*\{/,
       namespace: /^namespace\s+(\w+)/,
       template: /^template\s*(<[^>]+>)/,
     },
     graph: {
       entities: {
-        class: /^(?:class|struct)\s+(\w+)/,
+        class: /^(?:class|struct)(?:\s+(?:alignas|__attribute__|__declspec|__forceinline)\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)|\s+\[\[[^\]]*\]\]|\s+[A-Z][A-Z0-9_]{2,})*\s+(\w+)/,
         namespace: /^namespace\s+(\w+)/,
         function: /^(?:[\w:*&<>\s]+)\s+(\w+)\s*\([^)]*\)\s*(?:const)?\s*(?:override)?\s*\{/,
         typedef: /^(?:typedef|using)\s+.+\s+(\w+)/,
@@ -310,22 +332,33 @@ export const CORE_LANGUAGES = {
       block: ["/*", "*/"],
     },
     chunker: {
-      class: /(?:public|private|internal|protected)?\s*(?:static|sealed|abstract)?\s*(?:partial\s+)?class\s+(\w+)/,
-      interface: /(?:public|internal)?\s*interface\s+(\w+)/,
-      method: /(?:public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*\(/,
-      property: /(?:public|private|protected|internal)\s+(?:[\w<>\[\]?]+)\s+(\w+)\s*\{/,
-      enum: /(?:public|internal)?\s*enum\s+(\w+)/,
-      struct: /(?:public|internal)?\s*(?:readonly\s+)?struct\s+(\w+)/,
+      class: /^\s*(?:public|private|internal|protected)?\s*(?:static|sealed|abstract)?\s*(?:partial\s+)?class\s+(\w+)/,
+      interface: /^\s*(?:public|internal)?\s*interface\s+(\w+)/,
+      // Two alternation branches:
+      //   (a) visibility-prefixed: loose return type — covers `public Task<int> Foo(...)`
+      //       and `internal override void Bar(...)`.
+      //   (b) visibility-less: STRICT return type (C# primitives + Task/ValueTask/
+      //       IEnumerable/IAsyncEnumerable + capitalized identifiers) — covers
+      //       default-private `void Foo<T>(...)` / `async Task Bar<T>(...)` patterns
+      //       shipped widely in real codebases (e.g. Garnet's AsyncProcessor.cs
+      //       partial-class shard). Strict return-type list prevents false positives
+      //       like `return Foo()` and `if (cond)` (those starting tokens not in list).
+      // Also adds `(?:<...>)?` between method name and `(` so generic-method declarations
+      // `void Foo<T>(...)` get matched (previously rejected the `<T>` between name and `(`).
+      method: /^\s*(?:(?:public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:override\s+)?(?:virtual\s+)?(?:[\w<>\[\]?]+)|(?:(?:static|async|override|virtual|sealed|new)\s+)*(?:void|bool|byte|sbyte|short|ushort|int|uint|long|ulong|float|double|decimal|char|string|object|Task(?:<[^>]+>)?|ValueTask(?:<[^>]+>)?|IEnumerable(?:<[^>]+>)?|IAsyncEnumerable(?:<[^>]+>)?|[A-Z][\w<>?\[\],]*))\s+(\w+)(?:<[\w\s,?<>]+>)?\s*\(/,
+      property: /^\s*(?:public|private|protected|internal)\s+(?:[\w<>\[\]?]+)\s+(\w+)\s*\{/,
+      enum: /^\s*(?:public|internal)?\s*enum\s+(\w+)/,
+      struct: /^\s*(?:public|internal)?\s*(?:readonly\s+)?struct\s+(\w+)/,
     },
     graph: {
       entities: {
-        class: /(?:public|private|internal|protected)?\s*(?:static|sealed|abstract)?\s*(?:partial\s+)?class\s+(\w+)(?:\s*:\s*([\w,\s<>]+))?/,
-        interface: /(?:public|internal)?\s*interface\s+(\w+)(?:\s*:\s*([\w,\s<>]+))?/,
-        enum: /(?:public|internal)?\s*enum\s+(\w+)/,
-        struct: /(?:public|internal)?\s*(?:readonly\s+)?struct\s+(\w+)/,
-        method: /(?:public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:override\s+)?(?:virtual\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*\(([^)]*)\)/,
-        property: /(?:public|private|protected|internal)\s+(?:static\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*\{/,
-        field: /(?:public|private|protected|internal)\s+(?:static\s+)?(?:readonly\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*[;=]/,
+        class: /^\s*(?:public|private|internal|protected)?\s*(?:static|sealed|abstract)?\s*(?:partial\s+)?class\s+(\w+)(?:\s*:\s*([\w,\s<>]+))?/,
+        interface: /^\s*(?:public|internal)?\s*interface\s+(\w+)(?:\s*:\s*([\w,\s<>]+))?/,
+        enum: /^\s*(?:public|internal)?\s*enum\s+(\w+)/,
+        struct: /^\s*(?:public|internal)?\s*(?:readonly\s+)?struct\s+(\w+)/,
+        method: /^\s*(?:public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:override\s+)?(?:virtual\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*\(([^)]*)\)/,
+        property: /^\s*(?:public|private|protected|internal)\s+(?:static\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*\{/,
+        field: /^\s*(?:public|private|protected|internal)\s+(?:static\s+)?(?:readonly\s+)?(?:[\w<>\[\]?]+)\s+(\w+)\s*[;=]/,
       },
       relationships: {
         using: /^using\s+([\w.]+)\s*;/,
@@ -338,4 +371,10 @@ export const CORE_LANGUAGES = {
   },
 };
 
+// .tsx files share TypeScript chunker/graph regex; only the
+// tree-sitter WASM grammar differs (see GRAMMAR_MAP in tree-sitter-provider.js).
+// Aliasing the same object means chunker patterns, graph patterns, and
+// skipCallObjects stay byte-identical to typescript without duplication.
+CORE_LANGUAGES.tsx = CORE_LANGUAGES.typescript;
+
 export default CORE_LANGUAGES;

package/core/infrastructure/language-patterns/registry-object-oriented.js

@@ -72,14 +72,21 @@ export const OBJECT_ORIENTED_LANGUAGES = {
       block: ["=begin", "=end"],
     },
     chunker: {
-      class: /^class\s+(\w+)(?:\s*<\s*(\w+))?/,
-      module: /^module\s+(\w+)/,
+      // Allow leading whitespace so indented `class Foo` declarations
+      // nested inside a module (the dominant Ruby idiom) actually match.
+      // The previous `^class` anchor missed every class inside a module
+      // wrapper (e.g. `class IndifferentHash < Hash` inside `module Sinatra`).
+      // Superclass can be any expression (`Rack::Request`, `Struct.new(:app)`)
+      // — `_matchBoundary` only consumes the first capture, so allowing any
+      // tail after the class name keeps the inheritance form parsable.
+      class: /^\s*class\s+(\w+)/,
+      module: /^\s*module\s+(\w+)/,
       method: /^\s*def\s+(\w+[?!=]?)/,
     },
     graph: {
       entities: {
-        class: /^class\s+(\w+)(?:\s*<\s*(\w+))?/,
-        module: /^module\s+(\w+)/,
+        class: /^\s*class\s+(\w+)/,
+        module: /^\s*module\s+(\w+)/,
         method: /^\s*def\s+(\w+[?!=]?)\s*(?:\(([^)]*)\))?/,
       },
       relationships: {
@@ -87,7 +94,7 @@ export const OBJECT_ORIENTED_LANGUAGES = {
         include: /^\s*include\s+(\w+)/,
         extend: /^\s*extend\s+(\w+)/,
         prepend: /^\s*prepend\s+(\w+)/,
-        inherit: /^class\s+\w+\s*<\s*(\w+)/,
+        inherit: /^\s*class\s+\w+\s*<\s*([\w:]+)/,
         methodCall: /(\w+)\s*\.\s*(\w+)\s*[(!]/,
       },
       skipCallObjects: ["puts", "print", "p", "raise", "require", "attr_accessor", "attr_reader", "attr_writer"],

package/core/infrastructure/language-patterns.js

@@ -37,6 +37,74 @@ export function getLanguageByExtension(ext) {
   return { id, ...lang };
 }
 
+/**
+ * Tokens that can appear in C++ source but NOT in valid C source outside
+ * of string literals or comments. Used by resolveLanguage() to disambiguate
+ * `.h` files between C and C++.
+ *
+ *   template<       — C has no templates (C99+ has `_Generic`, syntactically distinct).
+ *   namespace IDENT — C has no namespaces (token reserved in C++).
+ *   class IDENT[:{] — `class IDENT { ... }` and `class IDENT : base` are C++ syntax;
+ *                     `int class;` (using `class` as a C field name) does NOT match.
+ *   decltype(       — C++11 type-deduction; not in any C standard.
+ *   {private|public|protected}: — access specifiers, C++ only at file scope. They
+ *                     could appear as goto labels in C, but doing so is exceptionally
+ *                     rare and the cost of a false positive is "parse a C header with
+ *                     tree-sitter-cpp" which is mostly a superset of tree-sitter-c.
+ *   IDENT::IDENT    — scope-resolution operator, C++ only.
+ *
+ * Strings/comments containing these tokens can produce false positives. The cost is
+ * one mis-routed header parsed by tree-sitter-cpp, which still produces reasonable
+ * results since tree-sitter-cpp is a near-superset of tree-sitter-c. This is the
+ * same disambiguation strategy used by GitHub Linguist for `.h`.
+ */
+const HEADER_CPP_DISAMBIGUATOR = /\btemplate\s*<|\bnamespace\s+[A-Za-z_]|\bclass\s+[A-Za-z_]\w*\s*[:{]|\bdecltype\s*\(|\b(?:private|public|protected)\s*:|[A-Za-z_]\w*\s*::\s*[A-Za-z_]/;
+
+// Number of leading characters scanned for C++ disambiguator tokens. Real-world
+// C++ headers have at least one telltale token within the first ~1KB (include
+// guards + namespace/template/class). 2KB gives generous margin without making
+// the scan a hot-path cost.
+const HEADER_DISAMBIGUATOR_SCAN_BYTES = 2048;
+
+/**
+ * Resolve the language for a file, using file content to disambiguate
+ * ambiguous extensions (today: `.h` for C vs C++).
+ *
+ * The default `.h → c` mapping in EXTENSION_MAP is incorrect for header-
+ * only C++ libraries (highway, Eigen, fmt, abseil-cpp, range-v3, …)
+ * where the implementation lives in `.h` files. When `.h` is parsed by
+ * tree-sitter-c, C++ keywords (alignas, namespace, template, decltype)
+ * are misidentified, producing phantom symbols and oversized macro-cluster
+ * chunks that pollute retrieval.
+ *
+ * Strategy: per-file content scan. If a `.h` file contains any token that
+ * cannot appear in valid C outside strings/comments (template<, namespace,
+ * class IDENT[:{], decltype(, access specifiers, IDENT::IDENT), route to
+ * cpp; otherwise keep the default routing. No project-level state, no
+ * cross-file leakage; per-file decision is locally explainable.
+ *
+ * @param {string} filePath - File path
+ * @param {string} [content] - File content (optional; required for `.h` disambiguation)
+ * @returns {{ id: string, ...config } | null}
+ */
+export function resolveLanguage(filePath, content) {
+  const langInfo = getLanguageByPath(filePath);
+  if (!langInfo) return null;
+  if (langInfo.id !== 'c') return langInfo;
+  // Only attempt content disambiguation for `.h` (the ambiguous extension).
+  // `.c` files are unambiguous C; we won't override them based on content.
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext !== '.h') return langInfo;
+  if (typeof content !== 'string' || content.length === 0) return langInfo;
+  const probe = content.length > HEADER_DISAMBIGUATOR_SCAN_BYTES
+    ? content.slice(0, HEADER_DISAMBIGUATOR_SCAN_BYTES)
+    : content;
+  if (HEADER_CPP_DISAMBIGUATOR.test(probe)) {
+    return getLanguageByExtension('.cpp');
+  }
+  return langInfo;
+}
+
 /**
  * Get language config by file path (handles both extension and filename).
  * @param {string} filePath - File path
@@ -132,6 +200,7 @@ export default {
   LANGUAGES,
   getLanguageByExtension,
   getLanguageByPath,
+  resolveLanguage,
   getChunkerPatterns,
   getGraphPatterns,
   getLanguageMeta,

package/core/infrastructure/model-registry.js

@@ -86,6 +86,10 @@ export const MODEL_REGISTRY = {
     hfId: 'nomic-ai/CodeRankEmbed',
     profile: 'full',
     description: 'Local embedding model (FP32 safetensors, 768d) for native inference',
+    // Loaded only by the candle/native inference path, which is armed
+    // exclusively for accelerated indexing (Metal / CoreML cascade / CUDA).
+    // CPU-only hosts index with ORT INT8 and never load this — init skips it.
+    nativeAccelerated: true,
     files: [
       { path: 'model.safetensors', sizeBytes: 546938168, sha256: '827529bcd58aef0d9082e66eeff7e7d53a02f62bd005f841a26b3d3e2fb17ebe' },
       { path: 'config.json', sizeBytes: 1525, sha256: null },
@@ -96,6 +100,8 @@ export const MODEL_REGISTRY = {
     hfId: 'lightonai/LateOn-Code',
     profile: 'full',
     description: 'Late interaction model (FP32 safetensors, backbone 768d) for native inference',
+    // Native-accelerated only — see coderankembed-fp32 above.
+    nativeAccelerated: true,
     files: [
       { path: 'model.safetensors', sizeBytes: 596076280, sha256: '45c40bb4ba6b45f0c66b2deb3d27dd06efc3af23c78c8093b8cad2af61c683b2' },
       { path: '1_Dense/model.safetensors', sizeBytes: 393304, sha256: '22ea6a53cad3ed034934b5db7a214a0bcc28ff4cc440babea44029989e4bbcca' },
@@ -107,6 +113,8 @@ export const MODEL_REGISTRY = {
     hfId: 'lightonai/LateOn-Code-edge',
     profile: 'full',
     description: 'Late interaction edge model (FP32 safetensors, backbone 256d, 2-stage projection) for native inference',
+    // Native-accelerated only — see coderankembed-fp32 above.
+    nativeAccelerated: true,
     files: [
       { path: 'model.safetensors', sizeBytes: 67195976, sha256: '7ffc36b8ff71367249cd5220dbdd4bdbe177bc0e305b2e978a8b598bd8296f04' },
       { path: '1_Dense/model.safetensors', sizeBytes: 524376, sha256: '9efb17fcb2106cd8fcb01d57a9cd9c997a487ad20630ec8e44ce3f9d89efe0a7' },
@@ -160,6 +168,18 @@ export function getModelEntry(key) {
   return MODEL_REGISTRY[key] || null;
 }
 
+/**
+ * Whether a model is a native-accelerated FP32 artifact (safetensors loaded
+ * by the candle/native inference path). These are only used for accelerated
+ * indexing on Metal / CoreML cascade / CUDA hosts; a CPU-only host indexes
+ * with ORT INT8 and never loads them, so init skips them by default (~1.2 GB
+ * of downloads avoided). Marked with `nativeAccelerated: true` in the
+ * registry entry. Returns false for unknown keys.
+ */
+export function isNativeAcceleratedModel(key) {
+  return Boolean(MODEL_REGISTRY[key]?.nativeAccelerated);
+}
+
 /**
  * Truthy env-flag parser. Matches the conventions used across the codebase:
  *   "1" / "true" / "on" / "yes" (case-insensitive) → true

package/core/infrastructure/native-inference.js

@@ -48,8 +48,7 @@
 
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { createRequire } from 'module';
-import { resolveNativeAddon } from './native-resolver.js';
+import { loadNativeAddon } from './native-resolver.js';
 import { createTokenizer } from './native-tokenizer.js';
 import { getModelCacheDir, fetchModel } from './model-fetcher.js';
 import { getModelEntry } from './model-registry.js';
@@ -57,8 +56,6 @@ import { getCoremlCascadeResolvedDirs } from './coreml-cascade.js';
 import { detectHardwareCapability } from './hardware-capability.js';
 import { LATE_INTERACTION_CONFIG } from './config/ranking.js';
 
-const require = createRequire(import.meta.url);
-
 // ─── State ───
 
 let _addon = null;
@@ -173,14 +170,12 @@ function resolveCoremlCascadeForAddon() {
 
 function loadAddon() {
   if (_addon) return _addon;
-  const addonPath = resolveNativeAddon();
-  if (!addonPath) return null;
-  try {
-    _addon = require(addonPath);
-    return _addon;
-  } catch {
-    return null;
-  }
+  // CUDA-preferred with CPU fallback (see loadNativeAddon): a CUDA addon that
+  // can't load on a no-GPU box falls back to the plain CPU addon, so native
+  // inference degrades to the CPU (ORT-INT8) path instead of failing.
+  const res = loadNativeAddon();
+  _addon = res ? res.mod : null;
+  return _addon;
 }
 
 // ─── Detection ───

package/core/infrastructure/native-resolver.js

@@ -80,61 +80,76 @@ function defaultPackageDirResolver(packageName) {
 }
 
 /**
- * Resolve the path to the native MaxSim .node addon, or null.
+ * All native .node addon candidate paths that EXIST on disk, in preference
+ * order: local dev build → local package template (CUDA, then CPU) →
+ * installed npm package (CUDA, then CPU).
  *
- * On Linux, the `-cuda` variant of the platform package is preferred when
- * installed — it contains a binary built with the `cuda` Cargo feature
- * that will dispatch embedding + LI work to candle-cuda when libcuda.so
- * is present at runtime. Absence of the `-cuda` package or libcuda.so
- * cleanly falls back to the standard CPU variant.
+ * On Linux the `-cuda` variant is PREFERRED but a CUDA-built addon hard-links
+ * libcuda/libcudart/libcublas, so `require()`-ing it on a host without those
+ * libraries (any CPU-only box) THROWS. Returning an ordered candidate list —
+ * rather than a single path — lets the loader (`loadNativeAddon`) try CUDA
+ * first and transparently FALL BACK to the plain CPU addon (→ ORT-INT8 path)
+ * when CUDA can't load. This is what keeps GPU acceleration for CUDA hosts
+ * while a no-GPU `npm i` (which still auto-installs the optional -cuda package,
+ * matching os/cpu/libc) does not break indexing.
  */
-export function resolveNativeAddon(options = {}) {
+export function resolveNativeAddonCandidates(options = {}) {
   const info = getPlatformInfo();
-  if (!info) return null;
+  if (!info) return [];
   const { platform, arch, libc, cudaPackageName } = info;
   // napi-rs --platform output includes the libc suffix on Linux
-  // (e.g. `sweet-search-native.linux-x64-gnu.node`). macOS has no
-  // libc suffix so `${libc}` is '' there, yielding `.darwin-arm64.node`.
-  // Historic bug: this constructed `${platform}-${arch}` only, which
-  // worked on darwin but silently missed the Linux build output.
+  // (e.g. `sweet-search-native.linux-x64-gnu.node`). macOS has no libc suffix.
   const binaryName = `sweet-search-native.${platform}-${arch}${libc}.node`;
   const exists = options.existsSync ?? existsSync;
   const rootDir = options.rootDir ?? root;
   const resolvePackageDir = options.resolvePackageDir ?? defaultPackageDirResolver;
 
-  // 1. Local dev: crates/sweet-search-native/ directory (or legacy native-maxsim/)
-  const localDev = join(rootDir, 'crates', 'sweet-search-native', binaryName);
-  if (exists(localDev)) return localDev;
-  const legacyDev = join(rootDir, 'native-maxsim', binaryName);
-  if (exists(legacyDev)) return legacyDev;
+  const out = [];
+  const add = (p) => { if (p && exists(p) && !out.includes(p)) out.push(p); };
 
-  // 2. Local package template: packages/native-*-cuda/ preferred, then packages/native-*/
+  // 1. Local dev build (crates/sweet-search-native/ or legacy native-maxsim/).
+  add(join(rootDir, 'crates', 'sweet-search-native', binaryName));
+  add(join(rootDir, 'native-maxsim', binaryName));
+  // 2. Local package template — CUDA preferred, then CPU.
+  if (cudaPackageName) add(join(rootDir, 'packages', `native-${platform}-${arch}${libc}-cuda`, 'sweet-search-native.node'));
+  add(join(rootDir, 'packages', `native-${platform}-${arch}${libc}`, 'sweet-search-native.node'));
+  // 3. Installed npm package — CUDA preferred, then CPU.
   if (cudaPackageName) {
-    const cudaLocalPkg = join(rootDir, 'packages', `native-${platform}-${arch}${libc}-cuda`, 'sweet-search-native.node');
-    if (exists(cudaLocalPkg)) return cudaLocalPkg;
+    try { add(join(resolvePackageDir(cudaPackageName), 'sweet-search-native.node')); }
+    catch { /* -cuda package not installed */ }
   }
-  const pkgDir = `native-${platform}-${arch}${libc}`;
-  const localPkg = join(rootDir, 'packages', pkgDir, 'sweet-search-native.node');
-  if (exists(localPkg)) return localPkg;
+  try { add(join(resolvePackageDir(getPlatformPackageName()), 'sweet-search-native.node')); }
+  catch { /* package not installed */ }
 
-  // 3. Installed npm package — CUDA variant preferred on Linux.
-  if (cudaPackageName) {
+  return out;
+}
+
+/**
+ * Resolve the single highest-preference native .node addon path, or null.
+ * Back-compat shim over `resolveNativeAddonCandidates` (returns the first,
+ * i.e. CUDA-preferred). Callers that need the CUDA→CPU load fallback should
+ * use `loadNativeAddon` instead of require()-ing this path directly.
+ */
+export function resolveNativeAddon(options = {}) {
+  return resolveNativeAddonCandidates(options)[0] ?? null;
+}
+
+/**
+ * require() the first native-addon candidate that loads successfully and
+ * satisfies `validate(mod)` (default: any). Candidates are tried CUDA-first,
+ * CPU-second, so a host whose CUDA addon throws on load (libcuda absent)
+ * transparently falls back to the CPU addon. Returns `{ mod, path }` or null.
+ */
+export function loadNativeAddon({ validate, requireFn, ...options } = {}) {
+  const load = requireFn ?? require; // requireFn is a test seam
+  for (const candidatePath of resolveNativeAddonCandidates(options)) {
     try {
-      const cudaNpmPkgDir = resolvePackageDir(cudaPackageName);
-      const cudaNpmAddon = join(cudaNpmPkgDir, 'sweet-search-native.node');
-      if (exists(cudaNpmAddon)) return cudaNpmAddon;
+      const mod = load(candidatePath);
+      if (!validate || validate(mod)) return { mod, path: candidatePath };
     } catch {
-      // -cuda package not installed — fall through to standard variant.
+      // Candidate failed to load (e.g. CUDA addon without libcuda) — try next.
     }
   }
-  try {
-    const npmPkgDir = resolvePackageDir(getPlatformPackageName());
-    const npmAddon = join(npmPkgDir, 'sweet-search-native.node');
-    if (exists(npmAddon)) return npmAddon;
-  } catch {
-    // Package not installed
-  }
-
   return null;
 }