sweet-search 0.0.1 → 2.3.0

package/core/infrastructure/manifest.json

@@ -0,0 +1,46 @@
+{
+  "version": 2,
+  "runtimeAssets": {
+    "wasmRouter": "crates/wasm-router/pkg/query_router_wasm.js",
+    "wasmRouterBinary": "crates/wasm-router/pkg/query_router_wasm_bg.wasm",
+    "maxsimWasm": "core/infrastructure/maxsim.wasm",
+    "simdDistanceWasm": "core/infrastructure/simd-distance.wasm",
+    "catboostRouter": "core/training/query-router/output/v45_router_d4.js",
+    "featureExtractor": "core/training/query-router/features/extractor.js"
+  },
+  "nativePackages": {
+    "darwin-arm64": "@sweet-search/native-darwin-arm64",
+    "darwin-x64": "@sweet-search/native-darwin-x64",
+    "linux-x64-gnu": "@sweet-search/native-linux-x64-gnu",
+    "linux-arm64-gnu": "@sweet-search/native-linux-arm64-gnu"
+  },
+  "profiles": {
+    "core": {
+      "description": "Lightweight search (no models)",
+      "models": []
+    },
+    "full": {
+      "description": "Full search with all models",
+      "models": [
+        "lateon-code",
+        "lateon-code-edge",
+        "gte-reranker-modernbert-base",
+        "coderankembed-int8"
+      ]
+    }
+  },
+  "modelSources": {
+    "lateon-code": {
+      "type": "init-managed"
+    },
+    "lateon-code-edge": {
+      "type": "init-managed"
+    },
+    "gte-reranker-modernbert-base": {
+      "type": "init-managed"
+    },
+    "coderankembed-int8": {
+      "type": "init-managed"
+    }
+  }
+}

package/core/infrastructure/model-fetcher.js

@@ -0,0 +1,423 @@
+/**
+ * Model Fetcher — robust model file downloader with checksums, resumability,
+ * atomic writes, retries, and progress reporting.
+ *
+ * Replaces the bare fetch→writeFileSync in late-interaction-model.js.
+ */
+
+import { createHash } from 'crypto';
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import os from 'os';
+import { pipeline } from 'stream/promises';
+import { MODEL_DELIVERY_CONFIG } from './config/index.js';
+import { getModelEntry } from './model-registry.js';
+
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 1000;
+
+// =============================================================================
+// VERIFICATION CACHE (H6 — avoid N-worker SHA256 stall)
+// =============================================================================
+//
+// Without this cache, every worker_thread that calls `fetchModel(...)` for
+// the same ~600 MB safetensors file independently runs its own SHA256 stream
+// over the bytes. Node's microtask scheduler is unfair under ORT load, so
+// several concurrent verifications can stall for minutes.
+//
+// Two-layer cache:
+//   1. In-process Map<absPath, {mtimeMs,size,dev,ino,sha256,verifiedAt}>
+//      — skips repeat verifications within the same worker.
+//   2. Disk sidecar `{filePath}.verified.json` — lets a DIFFERENT worker
+//      (separate V8 isolate, separate Map) short-circuit on next load
+//      without re-streaming. The sidecar is invalidated on any stat mismatch.
+//
+// TRUST MODEL — READ BEFORE CHANGING ANY OF THIS:
+//
+// This is a MEMOIZATION OPTIMIZATION, NOT a cryptographic trust anchor. The
+// cache remembers a prior successful SHA256 stream, and returns it when the
+// file "looks the same" by a stat-fingerprint: (size, mtimeMs, dev, ino).
+// Adding (dev, ino) raises the bar for a local same-user attacker who
+// replaces the file via `unlink + write` — the new file gets a fresh inode
+// and `stat.ino !== sidecar.ino` triggers a re-hash (2026-04-15 hardening).
+// On an in-place overwrite that preserves (size, ino, mtimeMs) — which a
+// determined local attacker can forge — the memoized hash is trusted.
+//
+// This is an acceptable trade-off ONLY because:
+//   (a) the H6 speedup (~2 min → ~1 s under worker-pool contention) is real;
+//   (b) a local same-user attacker who controls the model cache dir has
+//       already cleared a significant bar on a developer workstation;
+//   (c) the trust anchor for model bytes remains the registry SHA256 in
+//       `core/infrastructure/model-registry.js` (code, reviewed via git),
+//       which is what gets written as `record.sha256` when we first hash.
+//
+// Defense-in-depth follow-ups under consideration (not yet implemented):
+//   - HMAC the sidecar with a per-install secret in `.sweet-search/install-secret`
+//   - Re-verify in the Rust loader before mmap (defense-in-depth across the
+//     JS→Rust boundary)
+//
+// Mandatory invariants — any change that weakens these regresses security:
+//   1. The cache NEVER skips verification against a NEW expected hash. A
+//      caller supplying `expectedSha256 = X` gets a fresh stream unless the
+//      cache already holds a positive record for X.
+//   2. The in-process Map is invalidated on every explicit `fetchModelFile`
+//      atomic rename (see `invalidateVerifiedSidecar` before the rename).
+//   3. A positive record is written ONLY after a successful streaming hash.
+//      `recordVerified` is never called without a prior `computeFileHash`
+//      that matched `expectedSha256`.
+
+const _verificationMemCache = new Map();
+
+function verifiedSidecarPath(filePath) {
+  return filePath + '.verified.json';
+}
+
+function readVerifiedSidecar(filePath) {
+  const sidecarPath = verifiedSidecarPath(filePath);
+  if (!existsSync(sidecarPath)) return null;
+  try {
+    const raw = readFileSync(sidecarPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeVerifiedSidecar(filePath, record) {
+  try {
+    writeFileSync(verifiedSidecarPath(filePath), JSON.stringify(record));
+  } catch {
+    // Best-effort — a failed sidecar write just means the next run re-verifies.
+  }
+}
+
+function invalidateVerifiedSidecar(filePath) {
+  try {
+    unlinkSync(verifiedSidecarPath(filePath));
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') { /* ignore */ }
+  }
+  _verificationMemCache.delete(filePath);
+}
+
+/**
+ * Check if the cached stat-fingerprint matches the live file.
+ *
+ * The fingerprint is `(size, mtimeMs, dev, ino)`. Adding `(dev, ino)` to the
+ * original `(size, mtime)` pair raises the bar for local same-user file
+ * replacement: an attacker who does `unlink + write` to plant a forged file
+ * while reusing a matching `verified.json` sidecar gets a FRESH inode on
+ * the new file, so `stat.ino !== record.ino` triggers a re-hash. This is
+ * not cryptographic protection, but it turns a common forgery pattern from
+ * a silent bypass into a logged re-verification.
+ *
+ * Records from older sidecars that lack dev/ino (written before this
+ * hardening landed) still validate on (size, mtime) alone — this is
+ * necessary for backwards compatibility with existing caches.
+ */
+function stableStatFingerprint(stat) {
+  return { size: stat.size, mtimeMs: stat.mtimeMs, dev: stat.dev, ino: stat.ino };
+}
+
+function fingerprintMatches(record, stat) {
+  if (record.size !== stat.size) return false;
+  if (record.mtimeMs !== stat.mtimeMs) return false;
+  // dev / ino are optional on legacy sidecars. When the record carries them,
+  // require a match; when it doesn't, accept on (size, mtime) alone so we
+  // don't force a re-hash on every existing cache entry.
+  if (record.dev != null && record.dev !== stat.dev) return false;
+  if (record.ino != null && record.ino !== stat.ino) return false;
+  return true;
+}
+
+/**
+ * Check the verification cache for a file. Returns true iff the file's
+ * current stat-fingerprint matches a cached record AND the cached
+ * record's sha256 matches `expectedSha256`. Checks the in-process map
+ * first, falls back to the on-disk sidecar.
+ */
+function isVerified(filePath, expectedSha256) {
+  if (!expectedSha256) return false;
+  let stat;
+  try { stat = statSync(filePath); } catch { return false; }
+
+  const memRecord = _verificationMemCache.get(filePath);
+  if (memRecord && memRecord.sha256 === expectedSha256 && fingerprintMatches(memRecord, stat)) {
+    return true;
+  }
+
+  const diskRecord = readVerifiedSidecar(filePath);
+  if (diskRecord && diskRecord.sha256 === expectedSha256 && fingerprintMatches(diskRecord, stat)) {
+    _verificationMemCache.set(filePath, diskRecord);
+    return true;
+  }
+
+  return false;
+}
+
+function recordVerified(filePath, sha256) {
+  let stat;
+  try { stat = statSync(filePath); } catch { return; }
+  const record = {
+    sha256,
+    ...stableStatFingerprint(stat),
+    verifiedAt: Date.now(),
+  };
+  _verificationMemCache.set(filePath, record);
+  writeVerifiedSidecar(filePath, record);
+}
+
+/**
+ * Get the managed cache directory for a HuggingFace model.
+ */
+export function getModelCacheDir(hfId) {
+  const normalized = hfId.replace('/', '--');
+  const dir = join(MODEL_DELIVERY_CONFIG.modelCacheRoot, normalized);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Compute SHA256 of a local file.
+ */
+export async function computeFileHash(filePath) {
+  const hash = createHash('sha256');
+  await pipeline(createReadStream(filePath), hash);
+  return hash.digest('hex');
+}
+
+/**
+ * Check if a cached file is valid (exists, correct size, correct checksum if known).
+ *
+ * Short-circuits via the verification cache when possible: if a previous
+ * call to this function (in this process OR a prior one) verified the same
+ * (path, mtime, size, sha256) tuple and the stat hasn't changed, we skip
+ * the expensive streaming hash. This is the H6 fix — without it, N embedding
+ * workers each independently re-hash the 596 MB safetensors file.
+ */
+export async function isCacheValid(filePath, expectedSize, expectedSha256) {
+  if (!existsSync(filePath)) return false;
+
+  const stat = statSync(filePath);
+  if (stat.size === 0) return false;
+  if (expectedSize && stat.size !== expectedSize) return false;
+
+  if (expectedSha256) {
+    if (isVerified(filePath, expectedSha256)) {
+      return true;
+    }
+    const hash = await computeFileHash(filePath);
+    if (hash !== expectedSha256) {
+      invalidateVerifiedSidecar(filePath);
+      return false;
+    }
+    recordVerified(filePath, hash);
+  }
+
+  return true;
+}
+
+/**
+ * Download a single file from HuggingFace with retries, resumability, and atomic writes.
+ *
+ * @param {string} hfId - HuggingFace model ID (e.g. 'lightonai/LateOn-Code')
+ * @param {string} filePath - File path within the model repo (e.g. 'model_int8.onnx')
+ * @param {string} destDir - Local directory to save into
+ * @param {object} options
+ * @param {string} [options.sha256] - Expected SHA256 checksum
+ * @param {number} [options.expectedSize] - Expected file size in bytes
+ * @param {string} [options.hfEndpoint] - HuggingFace endpoint override
+ * @param {function} [options.onProgress] - Progress callback(downloadedBytes, totalBytes)
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @param {boolean} [options.allowDownload] - Explicit override for
+ *   MODEL_DELIVERY_CONFIG.allowRuntimeModelDownload. When true, bypasses
+ *   the config-based download gate. Used by `scripts/init.js` during its
+ *   own download phase — the `allowRuntimeModelDownload: false` flag
+ *   is meant to stop RUNTIME (query-time) downloads, not init-time
+ *   downloads, but the config is persisted before init re-runs can
+ *   download more, so init needs the explicit bypass. Runtime callers
+ *   (embedding-service, model-pool, etc.) omit this and stay gated.
+ * @returns {string} Absolute path to the verified local file
+ */
+export async function fetchModelFile(hfId, filePath, destDir, options = {}) {
+  const { sha256, expectedSize, onProgress, signal, allowDownload } = options;
+  const hfEndpoint = options.hfEndpoint || MODEL_DELIVERY_CONFIG.hfEndpoint;
+
+  // Preserve directory structure (e.g. onnx/model.onnx stays as onnx/model.onnx)
+  const finalPath = join(destDir, filePath);
+  mkdirSync(join(finalPath, '..'), { recursive: true });
+  const tmpPath = finalPath + '.tmp';
+
+  // Check existing cache
+  if (await isCacheValid(finalPath, expectedSize, sha256)) {
+    return finalPath;
+  }
+
+  // Check if runtime download is allowed. Explicit `options.allowDownload`
+  // overrides the persisted config flag — init passes `true` so re-runs
+  // can fetch a bumped SHA256, a newly added model, or a `--force` rebuild.
+  const downloadAllowed = allowDownload === true || MODEL_DELIVERY_CONFIG.allowRuntimeModelDownload;
+  if (!downloadAllowed) {
+    throw new Error(
+      `[ModelFetcher] Model file not found: ${hfId}/${filePath}\n` +
+      `  Expected at: ${finalPath}\n` +
+      `  Runtime model downloads are disabled.\n` +
+      `  Run \`sweet-search init\` to download required models.`
+    );
+  }
+
+  const url = `${hfEndpoint}/${hfId}/resolve/main/${filePath}`;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      // Check for partial download (resumability)
+      let startByte = 0;
+      if (existsSync(tmpPath)) {
+        startByte = statSync(tmpPath).size;
+      }
+
+      const headers = {};
+      if (startByte > 0) {
+        headers['Range'] = `bytes=${startByte}-`;
+      }
+
+      const resp = await fetch(url, { headers, signal });
+
+      if (resp.status === 416) {
+        // Range not satisfiable — file changed on server, restart
+        if (existsSync(tmpPath)) unlinkSync(tmpPath);
+        startByte = 0;
+        continue;
+      }
+
+      if (!resp.ok && resp.status !== 206) {
+        throw new Error(`HTTP ${resp.status} downloading ${url}`);
+      }
+
+      const totalSize = expectedSize || parseInt(resp.headers.get('content-length') || '0', 10) + startByte;
+      const isResume = resp.status === 206;
+
+      process.stderr.write(`[ModelFetcher] ${isResume ? 'Resuming' : 'Downloading'} ${filePath} from ${hfId}...`);
+
+      const writeStream = createWriteStream(tmpPath, { flags: isResume ? 'a' : 'w' });
+      const reader = resp.body.getReader();
+      let downloaded = startByte;
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        writeStream.write(Buffer.from(value));
+        downloaded += value.byteLength;
+        if (onProgress) onProgress(downloaded, totalSize);
+      }
+
+      writeStream.end();
+      await new Promise((resolve, reject) => {
+        writeStream.on('finish', resolve);
+        writeStream.on('error', reject);
+      });
+
+      const downloadedSize = statSync(tmpPath).size;
+      const sizeMB = (downloadedSize / 1024 / 1024).toFixed(1);
+      process.stderr.write(` ${sizeMB} MB\n`);
+
+      // Verify size
+      if (expectedSize && downloadedSize !== expectedSize) {
+        unlinkSync(tmpPath);
+        throw new Error(`Size mismatch: expected ${expectedSize} bytes, got ${downloadedSize}`);
+      }
+
+      // Verify checksum
+      if (sha256) {
+        process.stderr.write(`[ModelFetcher] Verifying checksum...`);
+        const hash = await computeFileHash(tmpPath);
+        if (hash !== sha256) {
+          unlinkSync(tmpPath);
+          throw new Error(`Checksum mismatch for ${filePath}: expected ${sha256}, got ${hash}`);
+        }
+        process.stderr.write(` OK\n`);
+      }
+
+      // Atomic rename — a fresh file overwrites the verification sidecar's
+      // mtime/size assumptions, so drop the cache before we record a new one.
+      invalidateVerifiedSidecar(finalPath);
+      renameSync(tmpPath, finalPath);
+      if (sha256) {
+        recordVerified(finalPath, sha256);
+      }
+      return finalPath;
+
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      if (attempt < MAX_RETRIES) {
+        const delay = RETRY_BASE_MS * Math.pow(2, attempt - 1);
+        process.stderr.write(`\n[ModelFetcher] Attempt ${attempt} failed: ${err.message}. Retrying in ${delay}ms...\n`);
+        await new Promise(r => setTimeout(r, delay));
+      } else {
+        // Clean up tmp on final failure
+        if (existsSync(tmpPath)) unlinkSync(tmpPath);
+        throw new Error(`[ModelFetcher] Failed to download ${hfId}/${filePath} after ${MAX_RETRIES} attempts: ${err.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Download all files for a registered model.
+ *
+ * @param {string} registryKey - Key in MODEL_REGISTRY
+ * @param {object} [options] - Options passed to fetchModelFile
+ * @returns {{ files: Map<string, string>, cached: number, downloaded: number }}
+ */
+export async function fetchModel(registryKey, options = {}) {
+  const entry = getModelEntry(registryKey);
+  if (!entry) throw new Error(`[ModelFetcher] Unknown model: ${registryKey}`);
+
+  const destDir = getModelCacheDir(entry.hfId);
+  const files = new Map();
+  let cached = 0;
+  let downloaded = 0;
+
+  for (const file of entry.files) {
+    const finalPath = join(destDir, file.path);
+
+    const wasPresent = await isCacheValid(finalPath, file.sizeBytes, file.sha256);
+
+    const resultPath = await fetchModelFile(entry.hfId, file.path, destDir, {
+      sha256: file.sha256,
+      expectedSize: file.sizeBytes,
+      ...options,
+    });
+
+    files.set(file.path, resultPath);
+    if (wasPresent) cached++;
+    else downloaded++;
+  }
+
+  return { files, cached, downloaded };
+}
+
+/**
+ * Resolve the local cache path for a model file. Returns null if not cached or invalid.
+ */
+export async function resolveModelFile(hfId, filePath, expectedSize, expectedSha256) {
+  const destDir = getModelCacheDir(hfId);
+  const finalPath = join(destDir, filePath);
+
+  if (await isCacheValid(finalPath, expectedSize, expectedSha256)) {
+    return finalPath;
+  }
+  return null;
+}

package/core/infrastructure/model-registry.js

@@ -0,0 +1,214 @@
+/**
+ * Model Registry — known model artifacts with HuggingFace IDs, file paths,
+ * sizes, and SHA256 content checksums.
+ *
+ * Only models with active runtime paths in the current full-profile search.
+ * Checksums are LFS content SHA256 from the HuggingFace API.
+ * Small non-LFS files (tokenizer.json, config.json) omit sha256 — they are
+ * integrity-checked by git and verified by size only.
+ *
+ * Use scripts/verify-model-registry.js to regenerate/verify checksums.
+ */
+
+export const MODEL_REGISTRY = {
+  'lateon-code': {
+    hfId: 'lightonai/LateOn-Code',
+    profile: 'full',
+    description: 'Late interaction model (INT8, 128d)',
+    files: [
+      { path: 'model_int8.onnx', sizeBytes: 150008364, sha256: 'a62a88b4e3ebb76e8bc5f0263d17b773c667d27bc73c5120e3131048dd1554ef' },
+      { path: '1_Dense/model.safetensors', sizeBytes: 393304, sha256: '22ea6a53cad3ed034934b5db7a214a0bcc28ff4cc440babea44029989e4bbcca' },
+      { path: 'tokenizer.json', sizeBytes: 3583847, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 21372, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 581, sha256: null },
+      { path: 'config.json', sizeBytes: 1208, sha256: null },
+    ],
+  },
+
+  'lateon-code-edge': {
+    hfId: 'lightonai/LateOn-Code-edge',
+    profile: 'full',
+    description: 'Late interaction edge model (FP32, 48d)',
+    files: [
+      { path: 'model.onnx', sizeBytes: 67970609, sha256: 'ac5a92a685512b163c3c591438f518379309d2a98c4818a9c6e2986f789dc8ef' },
+      { path: '1_Dense/model.safetensors', sizeBytes: 524376, sha256: '9efb17fcb2106cd8fcb01d57a9cd9c997a487ad20630ec8e44ce3f9d89efe0a7' },
+      { path: '2_Dense/model.safetensors', sizeBytes: 98392, sha256: 'a7a388138b3c4bb1a81c8c3bcb9de123f1e652b9e9464a72707ca19ee86a26b1' },
+      { path: 'tokenizer.json', sizeBytes: 3583847, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 21373, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 581, sha256: null },
+      { path: 'config.json', sizeBytes: 1252, sha256: null },
+    ],
+  },
+
+  'gte-reranker-modernbert-base': {
+    hfId: 'Alibaba-NLP/gte-reranker-modernbert-base',
+    profile: 'full',
+    description: 'Local reranker (INT8 quantized) — opt-in',
+    // Disabled by default since commit 43a61eb (2026-04-22): measured
+    // MRR-neutral on gencodesearchnet (82.15% with vs without) at 3x
+    // latency cost. init should NOT fetch this 143 MB model unless
+    // the user explicitly opts in via SWEET_SEARCH_ENABLE_LOCAL_RERANKER=1.
+    // Infrastructure (local-reranker.js, this registry entry) remains
+    // intact so the CE can be swapped back in without re-adding code.
+    optIn: {
+      envVars: ['SWEET_SEARCH_ENABLE_LOCAL_RERANKER'],
+      reason: 'Local cross-encoder reranker — disabled by default (MRR-neutral at 3x latency, see commit 43a61eb)',
+    },
+    files: [
+      { path: 'onnx/model_quantized.onnx', sizeBytes: 150871837, sha256: 'ecc6a0ae67cee3d898167802383112d9185ca9250e07bd5d1fa65019b050179d' },
+      { path: 'tokenizer.json', sizeBytes: 3583499, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 21031, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 694, sha256: null },
+      { path: 'config.json', sizeBytes: 1333, sha256: null },
+    ],
+  },
+
+  'coderankembed-int8': {
+    hfId: 'mrsladoje/CodeRankEmbed-onnx-int8',
+    profile: 'full',
+    description: 'Local embedding model (INT8 quantized, 768d)',
+    files: [
+      // SHA256 updated 2026-04-23: re-quantized with `reduce_range=True`
+      // to fix AVX2-only INT8 kernel overflow on pre-VNNI x86 CPUs
+      // (notably AMD Zen 3 EPYC). Size unchanged — reduce_range only
+      // affects weight *values*, not storage format. See HF model card
+      // for full details: https://huggingface.co/mrsladoje/CodeRankEmbed-onnx-int8
+      { path: 'onnx/model.onnx', sizeBytes: 138619279, sha256: '4eae31d09b1843103a1ebd5e2b2e24b5a5cad441a33906b35b12b1e2ed91d1db' },
+      { path: 'tokenizer.json', sizeBytes: 711649, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 1447, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 695, sha256: null },
+      { path: 'config.json', sizeBytes: 1371, sha256: null },
+      { path: 'vocab.txt', sizeBytes: 231508, sha256: null },
+    ],
+  },
+
+  'coderankembed-fp32': {
+    hfId: 'nomic-ai/CodeRankEmbed',
+    profile: 'full',
+    description: 'Local embedding model (FP32 safetensors, 768d) for native inference',
+    files: [
+      { path: 'model.safetensors', sizeBytes: 546938168, sha256: '827529bcd58aef0d9082e66eeff7e7d53a02f62bd005f841a26b3d3e2fb17ebe' },
+      { path: 'config.json', sizeBytes: 1525, sha256: null },
+    ],
+  },
+
+  'lateon-code-fp32': {
+    hfId: 'lightonai/LateOn-Code',
+    profile: 'full',
+    description: 'Late interaction model (FP32 safetensors, backbone 768d) for native inference',
+    files: [
+      { path: 'model.safetensors', sizeBytes: 596076280, sha256: '45c40bb4ba6b45f0c66b2deb3d27dd06efc3af23c78c8093b8cad2af61c683b2' },
+      { path: '1_Dense/model.safetensors', sizeBytes: 393304, sha256: '22ea6a53cad3ed034934b5db7a214a0bcc28ff4cc440babea44029989e4bbcca' },
+      { path: 'config.json', sizeBytes: 1208, sha256: null },
+    ],
+  },
+
+  'ms-marco-tinybert': {
+    hfId: 'Xenova/ms-marco-TinyBERT-L-2-v2',
+    profile: 'full',
+    description: 'FlashRank cross-encoder reranker (quantized, ~4.3MB) — opt-in',
+    // Disabled by default since commits 43a61eb + d92a5a7 (2026-04-22):
+    // the MaxSim+CE cascade is no longer active in the default config
+    // (CASCADE_CONFIG.enabled=false, shadowMode=false). init should not
+    // fetch this model unless the user explicitly opts into cascade or
+    // shadow mode.
+    optIn: {
+      envVars: ['SWEET_SEARCH_CASCADE_ENABLED', 'SWEET_SEARCH_CASCADE_SHADOW'],
+      reason: 'FlashRank cross-encoder for MaxSim+CE cascade — disabled by default (see commits 43a61eb, d92a5a7)',
+    },
+    files: [
+      { path: 'onnx/model_quantized.onnx', sizeBytes: 4496298, sha256: '026c2ec3257cd351696e45bbd6040bb83cf818ba89059b4344bd6350138b62ce' },
+      { path: 'tokenizer.json', sizeBytes: 711396, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 1242, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 125, sha256: null },
+      { path: 'config.json', sizeBytes: 824, sha256: null },
+      { path: 'vocab.txt', sizeBytes: 231508, sha256: null },
+    ],
+  },
+
+  'all-minilm-l6-v2': {
+    hfId: 'Xenova/all-MiniLM-L6-v2',
+    profile: 'full',
+    description: 'Semantic cache embedding model (quantized, ~23MB)',
+    files: [
+      { path: 'onnx/model_quantized.onnx', sizeBytes: 22972370, sha256: 'afdb6f1a0e45b715d0bb9b11772f032c399babd23bfc31fed1c170afc848bdb1' },
+      { path: 'tokenizer.json', sizeBytes: 711661, sha256: null },
+      { path: 'tokenizer_config.json', sizeBytes: 366, sha256: null },
+      { path: 'special_tokens_map.json', sizeBytes: 125, sha256: null },
+      { path: 'config.json', sizeBytes: 650, sha256: null },
+      { path: 'vocab.txt', sizeBytes: 231508, sha256: null },
+    ],
+  },
+};
+
+/**
+ * Get registry entry by key. Returns null if not found.
+ */
+export function getModelEntry(key) {
+  return MODEL_REGISTRY[key] || null;
+}
+
+/**
+ * Truthy env-flag parser. Matches the conventions used across the codebase:
+ *   "1" / "true" / "on" / "yes" (case-insensitive) → true
+ *   anything else / unset                           → false
+ */
+function isEnvTruthy(name) {
+  const raw = (process.env[name] ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes';
+}
+
+/**
+ * Check whether an opt-in model should be included given the current
+ * environment. Opt-in entries declare a list of env vars; if ANY is
+ * truthy, the model is pulled in. Entries without `optIn` are always
+ * considered enabled (standard models).
+ */
+export function isModelEnabled(entry) {
+  if (!entry?.optIn) return true;
+  const vars = entry.optIn.envVars ?? [];
+  return vars.some((v) => isEnvTruthy(v));
+}
+
+/**
+ * Get all model keys for a given profile, excluding opt-in models
+ * whose enabling env vars are unset.
+ *
+ * Currently-skipped-by-default models (since 2026-04-22 ranking refactor):
+ *   - gte-reranker-modernbert-base  — needs SWEET_SEARCH_ENABLE_LOCAL_RERANKER=1
+ *   - ms-marco-tinybert             — needs SWEET_SEARCH_CASCADE_ENABLED=1
+ *                                      or SWEET_SEARCH_CASCADE_SHADOW=1
+ *
+ * This matches the runtime behavior: the ranking config defaults to
+ * these rerankers OFF, so init shouldn't fetch their ~155 MB of weights
+ * for no reason. The models stay in the registry (with SHA256 and size)
+ * so flipping the opt-in env var on any host fetches them on the next init.
+ */
+export function getModelsForProfile(profile) {
+  return Object.entries(MODEL_REGISTRY)
+    .filter(([, entry]) => {
+      const inProfile = entry.profile === profile || profile === 'offline-max';
+      if (!inProfile) return false;
+      return isModelEnabled(entry);
+    })
+    .map(([key]) => key);
+}
+
+/**
+ * Get the keys of models currently SKIPPED by `getModelsForProfile(profile)`
+ * because their opt-in env vars aren't set. Used by init to print a
+ * one-line summary so users know optional models exist without being
+ * surprised they weren't installed.
+ */
+export function getSkippedOptInModels(profile) {
+  return Object.entries(MODEL_REGISTRY)
+    .filter(([, entry]) => {
+      const inProfile = entry.profile === profile || profile === 'offline-max';
+      return inProfile && entry.optIn && !isModelEnabled(entry);
+    })
+    .map(([key, entry]) => ({
+      key,
+      envVars: entry.optIn.envVars,
+      reason: entry.optIn.reason,
+    }));
+}