sweet-search 0.0.1 → 2.3.0

package/core/infrastructure/coreml-cascade.json

@@ -0,0 +1,46 @@
+{
+  "$comment": "CoreML variant cascade shape set — SINGLE SOURCE OF TRUTH. Consumed by (1) core/infrastructure/coreml-cascade.js for state inspection, cache resolution, and HF fetch, (2) scripts/spike-coreml/trace_cascade.py for local builds, and (3) the Rust filename parser in crates/sweet-search-native/src/inference/{embedding_model,li_model}.rs (parse_embed_variant_filename, parse_li_variant_filename) via the filePattern convention. Changing shapes here requires re-running scripts/build-coreml-cascade.js to regenerate the .mlpackage artifacts AND re-uploading tarballs to `hfRepo` with fresh checksums. The publish-coreml-cascade helper in the build script automates the tarball+upload+checksum backfill loop.",
+  "version": 2,
+  "description": "Cascade of fixed-shape NomicBERT embedding and ModernBERT LI mlpackages covering the stair-step output of the JS bucketer in core/embedding/embedding-local-model.js + core/indexing/indexer-pool.js. Distributed as per-variant .tar.gz archives from `hfRepo` so `sweet-search init` can fetch them alongside the other models without requiring Python/coremltools on the end-user machine.",
+  "hfRepo": "mrsladoje/sweet-search-coreml-cascade",
+  "embed": {
+    "modelKey": "nomic-bert",
+    "filePattern": "nomic_bert_b{batch}_s{seq}_fp16.mlpackage",
+    "tarballPattern": "embed/nomic_bert_b{batch}_s{seq}_fp16.mlpackage.tar.gz",
+    "hiddenDim": 768,
+    "traceSource": {
+      "hfId": "nomic-ai/CodeRankEmbed",
+      "safetensors": "model.safetensors",
+      "config": "config.json"
+    },
+    "variants": [
+      { "batch": 64, "seq": 96,   "rationale": "hardCap × short seq — covers observed (64, 52..107) regime", "tarballSha256": "76eeb863ffe11cc9d21cd0be0bd47d932630a86480c8a4f019d3360990b8ee14", "tarballSizeBytes": 252549277 },
+      { "batch": 64, "seq": 192,  "rationale": "hardCap × short-med",                                        "tarballSha256": "138ae2b406ecc0c2ce87730157791667f007472745079298c9eb605dc4b7ec1c", "tarballSizeBytes": 252608808 },
+      { "batch": 32, "seq": 384,  "rationale": "tokenBudget regime",                                         "tarballSha256": "580c67c9b9d3ac85e2c3a76b2262ad0b0c0489889dddfa3bc8cf1f215e71643a", "tarballSizeBytes": 252627736 },
+      { "batch": 16, "seq": 512,  "rationale": "long, cache-bound start",                                    "tarballSha256": "6e8dfc0b83befc905f2e90df45ae21d232d7983956c8c1526176fb175e774fbe", "tarballSizeBytes": 252608341 },
+      { "batch": 4,  "seq": 1024, "rationale": "long tail",                                                  "tarballSha256": "62afa26642d5531fc227ef730cd372312331631be43281464c9c1fb2c59b3f2f", "tarballSizeBytes": 252626657 },
+      { "batch": 1,  "seq": 2048, "rationale": "extreme tail / oversize docs",                               "tarballSha256": "4e3073e231a03d3c7fca673af81ac1fa9e6d28c4ff8da7856d64183eff090532", "tarballSizeBytes": 252722456 }
+    ]
+  },
+  "li": {
+    "modelKey": "modernbert-li",
+    "filePattern": "li_modernbert_b{batch}_s{seq}_fp16.mlpackage",
+    "tarballPattern": "li/li_modernbert_b{batch}_s{seq}_fp16.mlpackage.tar.gz",
+    "tokenDim": 128,
+    "backboneDim": 768,
+    "traceSource": {
+      "hfId": "lightonai/LateOn-Code",
+      "backbone": "model.safetensors",
+      "projection": "1_Dense/model.safetensors",
+      "config": "config.json"
+    },
+    "variants": [
+      { "batch": 128, "seq": 48,   "rationale": "upperCap × very short — covers observed (128, 18..33)", "tarballSha256": "01dddc23d4a83be98977b0500d9fcf977fb7649bb548bb9977c6d6395f22e1c2", "tarballSizeBytes": 275367487 },
+      { "batch": 128, "seq": 128,  "rationale": "upperCap × short",                                      "tarballSha256": "f81af66aef693c4c1994b560d23f1b0fbf97c38c66e0fadda0774af358b9b1a1", "tarballSizeBytes": 275382654 },
+      { "batch": 64,  "seq": 256,  "rationale": "medium",                                                "tarballSha256": "f5958100ab4a81e724f37338b5ad45c396a5c649402552191632a79d4ef826a9", "tarballSizeBytes": 275405899 },
+      { "batch": 16,  "seq": 512,  "rationale": "long, cache-bound start",                               "tarballSha256": "37906ffe3cc9205306cfb50d0b5821e569fd6ee3ec13e4d71f481f1e53649031", "tarballSizeBytes": 275451379 },
+      { "batch": 4,   "seq": 1024, "rationale": "long tail",                                             "tarballSha256": "e618f8bd981d24e4984c61ee1788c02578aaf601efc16cd926885a2930833d40", "tarballSizeBytes": 275545042 },
+      { "batch": 1,   "seq": 2048, "rationale": "LI max length",                                         "tarballSha256": "d5262bf49f145cadbdbddb82b7934499fc310f5c654c5aae34cfb9c2d90487d2", "tarballSizeBytes": 275743803 }
+    ]
+  }
+}

package/core/infrastructure/coreml-provider.js

@@ -0,0 +1,81 @@
+// core/coreml-provider.js
+// CoreML execution provider detection and configuration for macOS Apple Silicon.
+
+import os from 'os';
+
+/**
+ * Check if running on macOS Apple Silicon (ARM64).
+ * CoreML EP only benefits Apple Silicon; on Intel Macs it falls back to CPU anyway.
+ */
+export function isAppleSilicon() {
+  return process.platform === 'darwin' && os.arch() === 'arm64';
+}
+
+let _coremlAvailable = null;
+
+/**
+ * Check if CoreML EP is available in the onnxruntime-node binary.
+ * Uses ort.listSupportedBackends() which is available in ORT >= 1.18.
+ * Result is cached after first call.
+ */
+export async function isCoreMLProviderAvailable() {
+  if (_coremlAvailable !== null) return _coremlAvailable;
+  try {
+    const ort = await import('onnxruntime-node');
+    if (typeof ort.listSupportedBackends === 'function') {
+      const backends = ort.listSupportedBackends();
+      _coremlAvailable = backends.some(b => b.name === 'coreml' && b.bundled);
+      return _coremlAvailable;
+    }
+  } catch { /* ignore — ORT not installed or too old */ }
+  _coremlAvailable = false;
+  return false;
+}
+
+/**
+ * Determine if CoreML EP should be used, following the same tri-state pattern
+ * as SWEET_SEARCH_USE_OPENVINO: auto | on | off.
+ *
+ * "auto" (default): enable on Apple Silicon when provider is available.
+ * "on"/"1"/"true": force enable (still gated to darwin+arm64).
+ * "off"/"0"/"false": force disable.
+ *
+ * @param {boolean} providerAvailable - result of isCoreMLProviderAvailable()
+ */
+export function shouldUseCoreML(providerAvailable) {
+  const raw = (process.env.SWEET_SEARCH_USE_COREML ?? '').trim().toLowerCase();
+  if (raw === '0' || raw === 'false' || raw === 'off') return false;
+  if (!isAppleSilicon()) return false;
+
+  const autoMode = raw === '' || raw === 'auto';
+  const explicitOn = raw === '1' || raw === 'true' || raw === 'on';
+  if (!autoMode && !explicitOn) return false;
+
+  return providerAvailable;
+}
+
+/**
+ * Build the executionProviders array for CoreML with CPU fallback.
+ *
+ * Two CoreML model formats exist:
+ * - MLProgram (coreMlFlags 0x010): newer, supports ANE, requires Core ML 5+.
+ *   Better performance when supported, but some models fail to compile.
+ * - NeuralNetwork (coreMlFlags 0): older default, broader op coverage,
+ *   silently casts FP32→FP16. Works with more model architectures.
+ *
+ * ORT 1.24+ uses lowercase backend names ('cpu', 'coreml', 'webgpu').
+ * The legacy PascalCase names ('CPUExecutionProvider') are NOT recognized.
+ *
+ * @param {boolean} useMLProgram - true for MLProgram format, false for NeuralNetwork
+ */
+export function getCoreMLExecutionProviders(useMLProgram = true) {
+  return [
+    { name: 'coreml', coreMlFlags: useMLProgram ? 0x010 : 0 },
+    'cpu',
+  ];
+}
+
+/** Reset cached state (for testing and A/B benchmark pass switching). */
+export function _resetCoreMLCache() {
+  _coremlAvailable = null;
+}

package/core/infrastructure/db-utils.js

@@ -0,0 +1,69 @@
+/**
+ * Database Utilities - Shared SQLite configuration helpers.
+ */
+
+import Database from 'better-sqlite3';
+
+/**
+ * Apply read-path PRAGMA optimizations to a read-only database connection.
+ *
+ * - mmap_size = 256MB: Maps entire DB into OS page cache (typical DBs are 5-50MB).
+ *   Subsequent reads bypass SQLite's page cache via xFetch().
+ * - cache_size = 20MB: Modest bump from default ~16MB. Partially redundant with mmap
+ *   but acts as safety net for internal bookkeeping.
+ * - temp_store = MEMORY (optional): Use only for bounded, latency-sensitive read paths.
+ *
+ * These are best-effort optimizations. PRAGMA failures should not change the caller's
+ * fallback behavior or make a readable database look unavailable.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ tempStoreMemory?: boolean }} [options]
+ */
+export function applyReadPragmas(db, options = {}) {
+  if (!db || typeof db.pragma !== 'function') return;
+  const { tempStoreMemory = false } = options;
+
+  for (const pragma of [
+    'mmap_size = 268435456', // 256MB
+    'cache_size = -20000',   // 20MB
+  ]) {
+    try {
+      db.pragma(pragma);
+    } catch {
+      // Best-effort only.
+    }
+  }
+
+  if (tempStoreMemory) {
+    try {
+      db.pragma('temp_store = MEMORY');
+    } catch {
+      // Best-effort only.
+    }
+  }
+}
+
+/**
+ * Warm the graph database page cache with lightweight queries.
+ * Opens an ephemeral connection, touches FTS5/relationship/summary pages, closes.
+ * Intentionally minimal — no heavy imports, no query infrastructure.
+ *
+ * @param {string} dbPath - Path to code_graph.db
+ * @returns {{ summaries: number }}
+ */
+export function warmGraphDbCache(dbPath) {
+  const db = new Database(dbPath, { readonly: true, timeout: 5000 });
+  applyReadPragmas(db);
+  try {
+    try { db.prepare('SELECT count(*) FROM entities_fts WHERE name MATCH "warmup"').get(); } catch { /* table may not exist */ }
+    try { db.prepare('SELECT count(*) FROM relationships').get(); } catch { /* table may not exist */ }
+    let summaries = 0;
+    try {
+      const row = db.prepare('SELECT count(*) as cnt FROM entities WHERE summary IS NOT NULL').get();
+      summaries = row?.cnt || 0;
+    } catch { /* column may not exist */ }
+    return { summaries };
+  } finally {
+    db.close();
+  }
+}

package/core/infrastructure/dedup-hashing.js

@@ -0,0 +1,83 @@
+/**
+ * Dedup hashing — thin JS wrapper over the Rust NAPI addon's
+ * SimHash + MinHash + LSH clustering entrypoints.
+ *
+ * Zero domain logic lives here. If the native addon is missing
+ * (unsupported platform), `isAvailable()` returns false and callers
+ * fall back to a no-op that treats every chunk as its own exemplar.
+ */
+
+import { createRequire } from 'module';
+import { resolveNativeAddon } from './native-resolver.js';
+import { DEDUP_CONFIG } from './config/dedup.js';
+
+const require = createRequire(import.meta.url);
+
+let _addon = null;
+let _loadAttempted = false;
+let _loadError = null;
+
+function loadAddon() {
+  if (_loadAttempted) return _addon;
+  _loadAttempted = true;
+  const addonPath = resolveNativeAddon();
+  if (!addonPath) {
+    _loadError = new Error('dedup-hashing: native addon not resolved for this platform');
+    return null;
+  }
+  try {
+    _addon = require(addonPath);
+  } catch (e) {
+    _loadError = e;
+    _addon = null;
+  }
+  return _addon;
+}
+
+/**
+ * Returns true iff the Rust NAPI dedup functions are callable on this machine.
+ * Used by callers to decide whether to run the dedup phase or skip it cleanly.
+ */
+export function isAvailable() {
+  const addon = loadAddon();
+  return !!(
+    addon &&
+    typeof addon.dedupFingerprintBatch === 'function' &&
+    typeof addon.dedupCluster === 'function'
+  );
+}
+
+export function getLoadError() {
+  loadAddon();
+  return _loadError;
+}
+
+/**
+ * Compute per-chunk SimHash + MinHash fingerprints for a batch of texts.
+ * Returns `[{simhashHex: string, minhash: Buffer(512)}]`, one per input.
+ * Throws if the native addon isn't available — callers should check `isAvailable()` first.
+ */
+export function computeFingerprints(texts, config = DEDUP_CONFIG) {
+  const addon = loadAddon();
+  if (!addon) throw _loadError ?? new Error('dedup native addon unavailable');
+  return addon.dedupFingerprintBatch(texts, config.ngramSize, config.numPerm, config.seed);
+}
+
+/**
+ * Cluster fingerprints into near-duplicate groups via banded LSH +
+ * SimHash Hamming secondary filter + union-find collapse.
+ * Returns `[{exemplarIdx, siblingIdxs, clusterId}]`. Entries include
+ * singletons (siblingIdxs.length === 0) so callers can enumerate every chunk's
+ * cluster assignment — filter them out to get only true clusters.
+ */
+export function clusterFingerprints(fingerprints, config = DEDUP_CONFIG) {
+  const addon = loadAddon();
+  if (!addon) throw _loadError ?? new Error('dedup native addon unavailable');
+  return addon.dedupCluster(
+    fingerprints,
+    config.numPerm,
+    config.numBands,
+    config.jaccardThreshold,
+    config.simhashHammingMax,
+  );
+}

package/core/infrastructure/hardware-capability.js

@@ -0,0 +1,332 @@
+/**
+ * Hardware Capability Detection — identifies the current machine's chip
+ * family, accelerator generation, and preferred native inference backend.
+ *
+ * Used by:
+ *   - coreml-cascade.js         → gates cascade fetch/build on M3+ ANE viability
+ *   - native-inference.js       → backend selection diagnostics
+ *   - scripts/init.js           → decides what artifacts to fetch for the profile
+ *   - scripts/uninstall.js      → only removes cascade cache if it exists
+ *
+ * Design notes:
+ *   - `sysctl` is a cheap (~5 ms) one-shot call. The result is cached so
+ *     repeated consumers (init, native-inference, uninstall) all share one
+ *     detection. Hardware doesn't change at runtime.
+ *   - Never throws. Unknown hardware degrades to "candle-cpu fallback" —
+ *     this module is only advisory; absence of a capability is never an
+ *     error.
+ *   - Unknown new Apple chips (e.g. an M5 shipped after this file) are
+ *     admitted as cascade-eligible via the ">= 3" rule — we prefer
+ *     optimistic new-hardware behavior to silently refusing to try.
+ *   - CUDA detection combines two signals: (1) an "addon built with the
+ *     cuda feature?" probe via `native_cuda_available()`, and
+ *     (2) `nvidia-smi` output for GPU name + compute capability + VRAM.
+ *     The addon probe is authoritative for "is CUDA end-to-end usable";
+ *     `nvidia-smi` fills in the diagnostic fields. See the CUDA Backend
+ *     section in docs/INIT_STRATEGY.md for the full contract.
+ */
+
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import { resolveNativeAddon } from './native-resolver.js';
+import { createRequire } from 'node:module';
+
+let _cached = null;
+
+/**
+ * Parse an Apple chip brand string from `sysctl -n machdep.cpu.brand_string`
+ * into a structured descriptor.
+ *
+ * Known formats:
+ *   "Apple M1"            → { family: "M1", generation: 1, variant: "base" }
+ *   "Apple M2 Pro"        → { family: "M2", generation: 2, variant: "pro" }
+ *   "Apple M3 Max"        → { family: "M3", generation: 3, variant: "max" }
+ *   "Apple M4 Ultra"      → { family: "M4", generation: 4, variant: "ultra" }
+ *
+ * Returns `null` for unrecognised strings (including Intel brand strings).
+ */
+export function parseAppleChipBrandString(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const match = raw.match(/\bApple\s+(M(\d+))(?:\s+(Pro|Max|Ultra))?\b/i);
+  if (!match) return null;
+  return {
+    family: match[1].toUpperCase(),
+    generation: parseInt(match[2], 10),
+    variant: match[3] ? match[3].toLowerCase() : 'base',
+  };
+}
+
+/**
+ * Read CPU brand string via `sysctl`. Only called on darwin; returns
+ * `null` on any failure (sandboxed env, sysctl missing, non-zero exit).
+ */
+function sysctlBrandString() {
+  try {
+    const out = execFileSync('sysctl', ['-n', 'machdep.cpu.brand_string'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Minimum Apple generation for which the CoreML variant cascade is
+ * expected to beat candle Metal BF16 at our NomicBERT + ModernBERT
+ * workload.
+ *
+ * Why M3:
+ *   - M1 ANE ≈ 11 TOPS int8; M2 ≈ 15.8; M3 ≈ 18; M4 ≈ 38.
+ *   - Our end-to-end measurement on M3 Max saw 18% wall-clock reduction
+ *     vs Metal BF16 baseline (commit 4fd9c9a).
+ *   - M1/M2 ANE TOPS are below M3 and the spike's measured per-batch
+ *     latency improvement on smaller shapes does not cover the mlmodelc
+ *     compile overhead for those generations. Rather than ship a
+ *     fancier feature that regresses on older hardware, we gate on M3+.
+ *   - A future measurement on M1/M2 with a smaller cascade subset could
+ *     lower this threshold. For now, conservative gating.
+ */
+const MIN_APPLE_GENERATION_FOR_CASCADE = 3;
+
+/**
+ * Minimum NVIDIA compute capability (as a float) we target for the CUDA
+ * backend.
+ *
+ * Why 7.0:
+ *   - SM 6.x (Pascal, e.g. GTX 1080) has no tensor cores. Candle's
+ *     stock matmul on CUDA cores runs slower than modern CPU BLAS for
+ *     our small (b≤64, s≤1024) shapes. Net regression vs CPU.
+ *   - SM 7.0 (Volta, V100) has first-gen tensor cores + F16 matmul with
+ *     F32 accumulate. Works, but we pin F32 dtype here because F16 has
+ *     precision issues on this generation.
+ *   - SM 7.5 (Turing, T4/RTX 20xx) has second-gen tensor cores. F16
+ *     works cleanly with F32 accumulate via cuBLASLt / cuDNN.
+ *   - SM 8.0+ (Ampere/Ada/Hopper) adds BF16 tensor cores. BF16 is the
+ *     default on this tier, matching the Metal story.
+ *
+ * See the per-CC dtype policy in
+ * crates/sweet-search-native/src/inference/mod.rs::optimal_dtype for
+ * the full mapping. JS layer is responsible for parsing the
+ * `nvidia-smi` compute_cap output and setting
+ * SWEET_SEARCH_CUDA_COMPUTE_CAP before the addon loads models.
+ */
+const MIN_CUDA_COMPUTE_CAPABILITY = 7.0;
+
+/**
+ * Parse `nvidia-smi --query-gpu=name,compute_cap,memory.total,driver_version`
+ * CSV output into a structured descriptor. Returns `null` on anything
+ * unparseable — the surrounding `detectNvidiaGpu()` treats that as
+ * "no GPU" just like a missing `nvidia-smi` binary.
+ *
+ * Expected first data line:
+ *   "NVIDIA GeForce RTX 3090, 8.6, 24576, 535.129.03"
+ */
+export function parseNvidiaSmiOutput(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const firstLine = raw.split(/\r?\n/).find((l) => l.trim().length > 0);
+  if (!firstLine) return null;
+  const cols = firstLine.split(',').map((s) => s.trim());
+  if (cols.length < 4) return null;
+  const [name, computeCapability, memoryMB, driverVersion] = cols;
+  const memInt = parseInt(memoryMB, 10);
+  const ccFloat = parseFloat(computeCapability);
+  if (!name || !Number.isFinite(ccFloat) || !Number.isFinite(memInt)) return null;
+  return {
+    name,
+    computeCapability,            // string "8.6" — kept as string for faithful passthrough
+    computeCapabilityFloat: ccFloat, // float for comparisons
+    memoryMB: memInt,
+    driverVersion,
+  };
+}
+
+/**
+ * Shell out to `nvidia-smi` on Linux and return the first GPU's metadata.
+ * Silent failure (returns `null`) on any of: non-Linux host, missing
+ * binary, non-zero exit, malformed output. Bounded at 2s timeout so a
+ * hung GPU doesn't block init.
+ */
+function detectNvidiaGpu() {
+  if (process.platform !== 'linux') return null;
+  try {
+    const out = execFileSync(
+      'nvidia-smi',
+      [
+        '--query-gpu=name,compute_cap,memory.total,driver_version',
+        '--format=csv,noheader,nounits',
+      ],
+      {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 2000,
+      },
+    );
+    return parseNvidiaSmiOutput(out);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Probe the native Rust addon for CUDA readiness. Returns the boolean
+ * reported by `native_cuda_available()` or `null` when the addon is
+ * missing / doesn't expose that export (older builds).
+ *
+ * The addon may return `Some(false)` when the `cuda` feature IS built in
+ * but the runtime driver is missing — in that case we know the package
+ * is the `-cuda` variant but libcuda.so didn't load, which is worth
+ * surfacing to the user.
+ */
+function probeAddonCudaAvailability() {
+  try {
+    const addonPath = resolveNativeAddon();
+    if (!addonPath) return null;
+    const addonRequire = createRequire(import.meta.url);
+    const addon = addonRequire(addonPath);
+    if (typeof addon?.nativeCudaAvailable !== 'function') return null;
+    return Boolean(addon.nativeCudaAvailable());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect the current hardware capability. Returns a stable, read-only
+ * descriptor that callers use to pick inference backends and decide
+ * which artifacts to fetch at init time.
+ *
+ * Fields:
+ *   platform                     — process.platform
+ *   arch                         — process.arch
+ *   totalMemGB                   — os.totalmem() in GiB (float)
+ *   logicalCores                 — os.cpus().length
+ *   brandString                  — raw sysctl output (darwin-arm64 only)
+ *   appleSilicon                 — parsed chip descriptor or null
+ *   coremlCascadeEligible        — boolean; M3+ darwin-arm64 only
+ *   coremlCascadeReason          — human string explaining eligible/not
+ *   nvidiaGpu                    — { name, computeCapability, computeCapabilityFloat,
+ *                                    memoryMB, driverVersion } | null
+ *   cudaAddonEnabled             — boolean; addon built with cuda feature + libcuda.so loaded
+ *   cudaAvailable                — boolean; cudaAddonEnabled AND nvidiaGpu AND CC ≥ 7.0
+ *   cudaReason                   — human string explaining eligible/not
+ *   candleGpuBackend             — "metal" | "cuda" | null
+ *   inferenceBackendPreference   — "coreml-cascade" | "candle-metal"
+ *                                  | "candle-cuda" | "candle-cpu"
+ */
+export function detectHardwareCapability() {
+  if (_cached) return _cached;
+
+  const platform = process.platform;
+  const arch = process.arch;
+  const totalMemGB = os.totalmem() / (1024 ** 3);
+  const logicalCores = os.cpus().length;
+
+  let brandString = null;
+  let appleSilicon = null;
+  if (platform === 'darwin' && arch === 'arm64') {
+    brandString = sysctlBrandString();
+    appleSilicon = parseAppleChipBrandString(brandString);
+  }
+
+  let coremlCascadeEligible = false;
+  let coremlCascadeReason;
+  if (platform !== 'darwin') {
+    coremlCascadeReason = `CoreML is macOS-only (current platform: ${platform})`;
+  } else if (arch !== 'arm64') {
+    coremlCascadeReason = `CoreML cascade requires Apple Silicon (current arch: ${arch})`;
+  } else if (!appleSilicon) {
+    coremlCascadeReason = `Could not identify Apple Silicon chip (sysctl brand: ${brandString || 'unavailable'})`;
+  } else if (appleSilicon.generation < MIN_APPLE_GENERATION_FOR_CASCADE) {
+    coremlCascadeReason = `${brandString}: ${appleSilicon.family} ANE below cascade threshold (M${MIN_APPLE_GENERATION_FOR_CASCADE}+ required)`;
+  } else {
+    coremlCascadeEligible = true;
+    coremlCascadeReason = `${brandString}: ${appleSilicon.family} ANE suitable for cascade`;
+  }
+
+  // NVIDIA GPU detection — Linux only. `nvidia-smi` tells us what's
+  // installed; the addon probe tells us whether the installed native
+  // package actually knows how to dispatch to it.
+  const nvidiaGpu = detectNvidiaGpu();
+  const addonCudaProbe = probeAddonCudaAvailability();
+  const cudaAddonEnabled = addonCudaProbe === true;
+
+  // Diagnostic opt-out: SWEET_SEARCH_CUDA=0 force-disables CUDA even on
+  // an otherwise-eligible host. Parallels SWEET_SEARCH_COREML_CASCADE=0.
+  const cudaForceDisabled = ['0', 'false', 'off'].includes(
+    (process.env.SWEET_SEARCH_CUDA ?? '').toLowerCase(),
+  );
+
+  let cudaAvailable = false;
+  let cudaReason;
+  if (cudaForceDisabled) {
+    cudaReason = 'CUDA force-disabled via SWEET_SEARCH_CUDA=0';
+  } else if (platform !== 'linux') {
+    cudaReason = `CUDA native backend ships for Linux only (current platform: ${platform})`;
+  } else if (!nvidiaGpu) {
+    cudaReason = 'No NVIDIA GPU detected (nvidia-smi missing or no device 0)';
+  } else if (nvidiaGpu.computeCapabilityFloat < MIN_CUDA_COMPUTE_CAPABILITY) {
+    cudaReason = `${nvidiaGpu.name}: compute capability ${nvidiaGpu.computeCapability} below threshold (${MIN_CUDA_COMPUTE_CAPABILITY}+ required)`;
+  } else if (addonCudaProbe === null) {
+    cudaReason = `${nvidiaGpu.name} detected, but the installed native package does not expose a CUDA probe — reinstall with @sweet-search/native-linux-${arch === 'arm64' ? 'arm64' : 'x64'}-gnu-cuda to enable GPU indexing`;
+  } else if (addonCudaProbe === false) {
+    cudaReason = `${nvidiaGpu.name} detected, but the native addon reports Device::new_cuda(0) failed (driver / libcuda.so mismatch?)`;
+  } else {
+    cudaAvailable = true;
+    cudaReason = `${nvidiaGpu.name} (compute ${nvidiaGpu.computeCapability}, ${nvidiaGpu.memoryMB} MB, driver ${nvidiaGpu.driverVersion}) — suitable for candle-cuda`;
+  }
+
+  // Candle GPU backend availability.
+  //   darwin-arm64 → metal (bundled with the darwin-arm64 native package)
+  //   linux-*-gnu + NVIDIA + cuda-enabled addon → cuda
+  //   everything else → null (falls through to candle CPU)
+  let candleGpuBackend = null;
+  if (platform === 'darwin' && arch === 'arm64') {
+    candleGpuBackend = 'metal';
+  } else if (cudaAvailable) {
+    candleGpuBackend = 'cuda';
+  }
+
+  // Preference order: coreml-cascade > candle-metal > candle-cuda > candle-cpu.
+  // coreml-cascade and candle-cuda never co-exist on the same host
+  // (one is darwin, the other is linux), so the ordering is orthogonal
+  // in practice.
+  let inferenceBackendPreference;
+  if (coremlCascadeEligible) {
+    inferenceBackendPreference = 'coreml-cascade';
+  } else if (candleGpuBackend === 'metal') {
+    inferenceBackendPreference = 'candle-metal';
+  } else if (candleGpuBackend === 'cuda') {
+    inferenceBackendPreference = 'candle-cuda';
+  } else {
+    inferenceBackendPreference = 'candle-cpu';
+  }
+
+  _cached = Object.freeze({
+    platform,
+    arch,
+    totalMemGB,
+    logicalCores,
+    brandString,
+    appleSilicon,
+    coremlCascadeEligible,
+    coremlCascadeReason,
+    nvidiaGpu,
+    cudaAddonEnabled,
+    cudaAvailable,
+    cudaReason,
+    candleGpuBackend,
+    inferenceBackendPreference,
+  });
+  return _cached;
+}
+
+/**
+ * Reset the cached detection result. Tests only — production callers
+ * should never need this because hardware doesn't change at runtime.
+ */
+export function _resetHardwareCapabilityCache() {
+  _cached = null;
+}