sweet-search 2.4.2 → 2.5.1

package/core/ranking/file-kind-ranking.js

@@ -0,0 +1,264 @@
+/**
+ * Intent-aware file-kind ranking (conservative variant).
+ *
+ * Background: real-codebase miss analysis found that documentation, test, and
+ * TypeScript-declaration files often outrank the implementation file users
+ * were actually looking for on multi-file codebases. The first version of
+ * this rule (commit f6fcfd1) lifted graph-2hop R@1 from 47.46 % → 64.41 %
+ * but catastrophically regressed GenCodeSearchNet under the dense profile
+ * (full-6 000 dense run: MRR@10 84.4 % → 47.4 %, Recall@5 92.0 % → 48.4 %).
+ * Root cause: the legacy LI-rerank pipeline assembles
+ * `results = [...liScored, ...tail]`, where `liScored` carries MaxSim
+ * scores that are sometimes *lower* (in absolute value) than the int8
+ * cosine scores already on the un-reranked tail. The concatenated list is
+ * therefore not globally score-monotonic. The old helper unconditionally
+ * spread and re-sorted *all* results by `score`, which floated the
+ * int8-only tail above the LI-reranked head and undid the rerank — even
+ * when every multiplier was 1 (GenCodeSearchNet is a single-source
+ * corpus, so no docs/tests/types kind ever matches there).
+ *
+ * Conservative variant fixes both regressions with three guards:
+ *
+ *   1. Confident-intent gating. `classifyFileKindIntent` now returns
+ *      `'unknown'` for queries with no implementation-seeking signal. Only
+ *      explicit `'implementation'` intent triggers demotion. `'unknown'`,
+ *      `'docs'`, `'tests'`, `'types'` are no-ops.
+ *
+ *   2. Structural skip. The rule looks at the top-N candidates (default 30).
+ *      If the window has zero docs/tests/types files (single-source corpus
+ *      like GCSN) or zero implementation files (nothing to promote), the
+ *      input is returned untouched. No re-sort, no new objects.
+ *
+ *   3. Window-bounded re-sort. When the rule does fire, only the top-N
+ *      window is re-ranked. The tail — where the rerank/non-rerank score-
+ *      scale boundary usually lives — is concatenated unchanged. This
+ *      keeps mixed-scale damage contained.
+ *
+ * Disable at runtime with `SWEET_SEARCH_FILE_KIND_RANKING=0`. Tune the soft
+ * factor with `SWEET_SEARCH_FILE_KIND_FACTOR` (default 0.85; range (0, 1]).
+ * Tune the window with `SWEET_SEARCH_FILE_KIND_WINDOW` (default 30).
+ */
+
+const DOCS_RE  = /\.md$|\.mdx$|\.rst$|(?:^|\/)docs?\//i;
+const TESTS_RE = /(?:^|\/)tests?\/|(?:^|\/)spec\/|\.test\.[a-z0-9]+$|_test\.[a-z0-9]+$|\.spec\.[a-z0-9]+$|_spec\.[a-z0-9]+$/i;
+const TYPES_RE = /\.d\.ts$|(?:^|\/)types\//i;
+
+// Strong implementation-seeking signals. A query that fires one of these is
+// confidently asking for source code; anything else is treated as `'unknown'`.
+// Curated to cover the validated guard-set queries plus common phrasings,
+// without matching pure descriptive corpus prose like "Convert XML to URL List".
+const IMPL_INTENT_RE = new RegExp(
+  '\\b(' + [
+    // English wh-questions about location/behaviour
+    'where', 'how does', 'how do',
+    // Definition / implementation phrasing
+    'implements?', 'implementation', 'defines?', 'definition', 'declared?',
+    // Code-structure nouns
+    'function', 'functions', 'method', 'methods', 'class', 'classes',
+    'constructor', 'module', 'library', 'crate', 'package',
+    // Verbs that strongly signal a code unit
+    'dispatch(?:es|er)?', 'handles?', 'handler', 'handlers',
+    'parses?', 'parser', 'parsers',
+    'router?', 'routes?', 'routing',
+    'register(?:s|ed|ing)?',
+    'builds?', 'builder', 'builders',
+    'generat(?:es?|or|ors|ed|ing)',
+    'creat(?:es?|or|ed|ion|ing)',
+    'loads?', 'loader',
+    'writes?', 'writer',
+    'reads?', 'reader',
+    'sends?', 'receives?',
+    'computes?', 'computed',
+    'encodes?', 'encoder', 'decodes?', 'decoder',
+    'transforms?', 'transformer',
+    'invokes?', 'calls?', 'returns?',
+    'valid(?:ate|ates|ator|ation)',
+    'serial(?:ize|izes|izer)', 'deserial(?:ize|izes|izer)',
+    'wrap(?:s|per|ped|ping)?',
+    'matchers?', 'matches?',
+    'printers?', 'prints?',
+    'searchers?', 'searches?',
+    // Specific terms common in real-repo guard queries
+    'callback', 'callbacks',
+    'factory', 'factories',
+    'controller', 'controllers',
+    'middleware',
+    'fallback', 'fallbacks',
+    'entrypoint', 'entry-point', 'main',
+    'init', 'initialise', 'initialize', 'initialiser', 'initializer',
+    'kernel', 'engine',
+    'wrapper', 'wrappers',
+    'singleton',
+    'factory',
+    'decorator', 'decorators',
+    'closure', 'closures',
+  ].join('|') + ')\\b',
+  'i',
+);
+
+const DOCS_INTENT_RE  = /\b(doc|docs|documentation|readme|guide|tutorial|reference|example)\b/i;
+const TESTS_INTENT_RE = /\b(test|tests|spec|specs|fixture|fixtures|mock|mocks)\b/i;
+const TYPES_INTENT_RE = /\b(type|types|interface|declaration|signature|typings|typedef)\b/i;
+
+/**
+ * Detect the file kind from a result path.
+ * @returns {'docs'|'tests'|'types'|'implementation'}
+ */
+export function detectFileKind(filePath) {
+  if (!filePath || typeof filePath !== 'string') return 'implementation';
+  if (DOCS_RE.test(filePath))  return 'docs';
+  if (TESTS_RE.test(filePath)) return 'tests';
+  if (TYPES_RE.test(filePath)) return 'types';
+  return 'implementation';
+}
+
+/**
+ * Detect file-kind intent of a query along the docs/tests/types/implementation
+ * axis. Conservative: a query with no implementation-seeking signal returns
+ * `'unknown'`, and the helper treats `'unknown'` as a no-op (just like the
+ * docs/tests/types intents).
+ *
+ * @returns {'docs'|'tests'|'types'|'implementation'|'unknown'}
+ */
+export function classifyFileKindIntent(query) {
+  const q = (query || '').toLowerCase();
+  if (!q) return 'unknown';
+  // Type-seeking trumps test-seeking when both fire (existing convention).
+  if (TYPES_INTENT_RE.test(q)) return 'types';
+  if (DOCS_INTENT_RE.test(q))  return 'docs';
+  if (TESTS_INTENT_RE.test(q)) return 'tests';
+  if (IMPL_INTENT_RE.test(q))  return 'implementation';
+  return 'unknown';
+}
+
+function resolveFilePath(r) {
+  return r?.file
+    || r?.file_path
+    || r?.path
+    || r?.metadata?.file
+    || r?.metadata?.file_path
+    || r?.metadata?.path
+    || '';
+}
+
+function envOff() {
+  return process.env.SWEET_SEARCH_FILE_KIND_RANKING === '0'
+      || process.env.SWEET_SEARCH_FILE_KIND_RANKING === 'false';
+}
+
+function envFactor(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) && n > 0 && n <= 1 ? n : fallback;
+}
+
+function envWindow(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+const DEFAULT_FACTOR = 0.85;
+const DEFAULT_WINDOW = 30;
+
+/**
+ * Apply intent-aware file-kind score multipliers, then re-sort the top-N
+ * window descending. The original array is not mutated.
+ *
+ * Demotion fires only when:
+ *   - intent === 'implementation' (confident, NOT 'unknown'), AND
+ *   - the top-N window contains at least one docs/tests/types candidate, AND
+ *   - the top-N window contains at least one implementation candidate.
+ *
+ * In every other case the original `results` array is returned unchanged
+ * (same reference, no copy, no re-sort) — this is critical so the helper is
+ * a structural no-op on single-source corpora (GCSN) and on cascades whose
+ * top-N has no demotable competition.
+ *
+ * @param {Array} results - search results carrying .score and a file-path
+ *                          field (.file / .file_path / .path / .metadata.*).
+ * @param {Object} [opts]
+ * @param {string} [opts.query]            - raw query (used to infer intent
+ *                                            if opts.intent isn't supplied)
+ * @param {'docs'|'tests'|'types'|'implementation'|'unknown'} [opts.intent]
+ *                                            - explicit intent override
+ * @param {number} [opts.docFactor]        - default from env / 0.85
+ * @param {number} [opts.testFactor]       - default from env / 0.85
+ * @param {number} [opts.typeFactor]       - default from env / 0.85
+ * @param {number} [opts.window]           - top-N window for analysis +
+ *                                            bounded re-sort (default 30)
+ * @returns {Array} either the original `results` (no-op) or a new array
+ *                  whose head is sorted by adjusted score and whose tail is
+ *                  the unchanged input tail. Stable on ties.
+ */
+export function applyFileKindRanking(results, opts = {}) {
+  if (envOff()) return results;
+  if (!Array.isArray(results) || results.length === 0) return results;
+
+  const intent = opts.intent != null
+    ? opts.intent
+    : classifyFileKindIntent(opts.query || '');
+
+  // Conservative gate: only confident 'implementation' intent fires.
+  if (intent !== 'implementation') return results;
+
+  const window = opts.window != null
+    ? opts.window
+    : envWindow('SWEET_SEARCH_FILE_KIND_WINDOW', DEFAULT_WINDOW);
+  const windowSize = Math.min(window, results.length);
+
+  // Walk the window once: classify kinds and check for competition.
+  const kinds = new Array(windowSize);
+  let demotableCount = 0;
+  let implCount = 0;
+  for (let i = 0; i < windowSize; i++) {
+    const k = detectFileKind(resolveFilePath(results[i]));
+    kinds[i] = k;
+    if (k === 'docs' || k === 'tests' || k === 'types') demotableCount++;
+    else if (k === 'implementation') implCount++;
+  }
+
+  // Structural skip: nothing to demote, or nothing to promote.
+  if (demotableCount === 0 || implCount === 0) return results;
+
+  const factor = envFactor('SWEET_SEARCH_FILE_KIND_FACTOR', DEFAULT_FACTOR);
+  const docFactor  = opts.docFactor  != null ? opts.docFactor  : factor;
+  const testFactor = opts.testFactor != null ? opts.testFactor : factor;
+  const typeFactor = opts.typeFactor != null ? opts.typeFactor : factor;
+
+  const reranked = new Array(windowSize);
+  for (let i = 0; i < windowSize; i++) {
+    const r = results[i];
+    const kind = kinds[i];
+    let mult = 1;
+    if (kind === 'docs')  mult = docFactor;
+    else if (kind === 'tests') mult = testFactor;
+    else if (kind === 'types') mult = typeFactor;
+    const baseScore = (typeof r.score === 'number') ? r.score : 0;
+    reranked[i] = {
+      ...r,
+      _fileKindOrigScore: baseScore,
+      _fileKindMult: mult,
+      _fileKindKind: kind,
+      _fileKindOrigIndex: i,
+      score: baseScore * mult,
+    };
+  }
+
+  // Stable sort: descending score, tie-break on original index.
+  reranked.sort((a, b) => {
+    const d = (b.score || 0) - (a.score || 0);
+    return d !== 0 ? d : a._fileKindOrigIndex - b._fileKindOrigIndex;
+  });
+
+  for (const r of reranked) delete r._fileKindOrigIndex;
+
+  // Concatenate unchanged tail. The cascade's CE/MaxSim score-scale
+  // boundary typically lives near rank `ceTopK`, so leaving rank
+  // `windowSize`+ untouched contains the damage from any cross-scale
+  // re-sort that might happen inside the window.
+  if (windowSize === results.length) return reranked;
+  return reranked.concat(results.slice(windowSize));
+}

package/core/ranking/late-interaction-index.js

@@ -1414,10 +1414,16 @@ export class LateInteractionIndex {
     // don't support importance weighting, so we must use the JS-tier weighted path.
     const nativeScored = new Set();
 
+    // Resolve a doc-lookup ID for each candidate. Graph-expanded candidates
+    // carry `_liChunkId` (a chunk id pointing into the LI index) while their
+    // public `id` is the entity id from the code graph. Honouring _liChunkId
+    // lets expanded candidates participate in MaxSim rerank.
+    const docIdOf = (c) => c._liChunkId || c.id;
+
     if (useFlatPath && !this.useTokenWeights) {
       const groups = { bit4: [], perToken: [], perDoc: [] };
       for (const candidate of toScore) {
-        const doc = this.documents.get(candidate.id);
+        const doc = this.documents.get(docIdOf(candidate));
         if (!doc) continue;
         if (doc.quantBits === 4 && doc.minArray && doc.tokenNorms) {
           groups.bit4.push({ candidate, doc });
@@ -1453,7 +1459,7 @@ export class LateInteractionIndex {
     // Try WASM fused kernels first (avoids JS-side dequant), fall back to JS dequant + wasmMaxSimF32.
     for (const candidate of toScore) {
       if (nativeScored.has(candidate.id)) continue;
-      const doc = this.documents.get(candidate.id);
+      const doc = this.documents.get(docIdOf(candidate));
       if (!doc) { pushFallback(candidate); continue; }
 
       if (useFlatPath) {
@@ -1488,7 +1494,7 @@ export class LateInteractionIndex {
         }
 
         // JS dequant → WASM f32 or JS fallback
-        const flatData = this.getTokensFlat(candidate.id);
+        const flatData = this.getTokensFlat(docIdOf(candidate));
         if (flatData) {
           pushScored(candidate, this.maxSimScoreFlat(
             effectiveQueryTokens, flatData.flat, flatData.numTokens, flatData.dim,
@@ -1498,7 +1504,7 @@ export class LateInteractionIndex {
           pushFallback(candidate);
         }
       } else {
-        const docTokens = this.getTokens(candidate.id);
+        const docTokens = this.getTokens(docIdOf(candidate));
         if (docTokens) {
           pushScored(candidate, this.maxSimScore(effectiveQueryTokens, docTokens, pruneOpts));
         } else {

package/core/ranking/late-interaction-policy.js

@@ -0,0 +1,304 @@
+/**
+ * Late-interaction search-rerank policy resolver.
+ *
+ * Pure function — no I/O. The two product concepts (LI indexing model vs
+ * search-side LI rerank policy) are separate. This resolver computes the
+ * effective search-side state from explicit user choices, env vars,
+ * persisted init config, and the on-disk LI index manifest.
+ *
+ * The on-disk manifest is the source of truth: if the user (or auto)
+ * asks for rerank ON but the loaded index is missing, mismatched, or
+ * built with an edge model that's known to underperform as a reranker
+ * on benchmarked corpora, the resolver downgrades or warns accordingly.
+ *
+ * Bench evidence backing the auto rules (gencodesearchnet, 2026-05-03):
+ *   standard `lateon-code` + LI on  : 85.57 % MRR  ← auto resolves ON
+ *   edge `lateon-code-edge` + LI on : 80.65 % MRR  ← auto resolves OFF
+ *   edge      + LI off              : 82.91 % MRR  (best edge config)
+ *   standard  + LI off              : 82.91 % MRR  (index-independent floor)
+ * See docs/BENCH_TODO.md "Phase 3 — Honest sweep before v2.5.0 (post-fix re-run)".
+ */
+
+// ---------------------------------------------------------------------------
+// Public model identifiers — kept in lockstep with
+// `core/infrastructure/config/ranking.js::LATE_INTERACTION_CONFIG.models`.
+// ---------------------------------------------------------------------------
+
+export const LI_MODEL_STANDARD = 'lateon-code';
+export const LI_MODEL_EDGE = 'lateon-code-edge';
+export const LI_MODEL_NONE = 'none';
+
+export const VALID_LI_MODELS = Object.freeze([
+  LI_MODEL_STANDARD,
+  LI_MODEL_EDGE,
+  LI_MODEL_NONE,
+]);
+
+export const VALID_RERANK_POLICIES = Object.freeze(['auto', 'on', 'off']);
+
+// ---------------------------------------------------------------------------
+// Env-var coercion (same shape as other env opt-outs in the repo —
+// SWEET_SEARCH_COREML_CASCADE, SWEET_SEARCH_NATIVE_INFERENCE, etc.)
+// ---------------------------------------------------------------------------
+
+function isEnvOff(value) {
+  if (value == null) return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '0' || v === 'false' || v === 'off' || v === 'no';
+}
+
+function isEnvOn(value) {
+  if (value == null) return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve effective search-side LI rerank state.
+ *
+ * @param {object} input
+ * @param {object} [input.persisted]               - parsed `.sweet-search/config.json`
+ * @param {string} [input.persisted.liModel]       - 'lateon-code' | 'lateon-code-edge' | 'none'
+ * @param {string} [input.persisted.searchReranking] - 'auto' | 'on' | 'off'
+ * @param {object} [input.indexManifest]           - loaded LI index header
+ * @param {string} [input.indexManifest.modelId]   - id baked into the SSLX header
+ * @param {number} [input.indexManifest.tokenDim]  - per-token dimension
+ * @param {boolean} [input.indexManifest.modelMismatch] - true when loaded
+ *   modelId disagrees with the active config model
+ * @param {boolean} [input.indexManifest.exists]   - false when no index file on disk
+ * @param {object} [input.env]                     - env-var snapshot (defaults to process.env)
+ * @param {boolean} [input.optionOverride]         - explicit per-call override from caller
+ *   (search-time options.useLateInteraction). If a boolean, it short-circuits the
+ *   resolver and wins over everything else.
+ * @param {string} [input.activeConfigModel]       - LATE_INTERACTION_CONFIG.model fallback
+ *   (used when the index hasn't been loaded yet so we can still emit a sensible
+ *   default — preserves back-compat with the pre-Phase-4 behaviour).
+ *
+ * @returns {{
+ *   effective: boolean,
+ *   policy: 'auto'|'on'|'off',
+ *   reason: string,
+ *   warning?: string
+ * }}
+ */
+export function resolveSearchRerankPolicy(input = {}) {
+  const env = input.env ?? process.env;
+  const persisted = input.persisted ?? {};
+  const manifest = input.indexManifest ?? null;
+  const declaredPolicy = normalizePolicy(persisted.searchReranking);
+
+  // 1. Per-call explicit override (existing API, highest precedence).
+  if (typeof input.optionOverride === 'boolean') {
+    return {
+      effective: input.optionOverride,
+      policy: declaredPolicy,
+      reason: `per-call override (${input.optionOverride ? 'on' : 'off'})`,
+    };
+  }
+
+  // 2. Env-var hard kill switch — opt-out for benchmarks / scripts that
+  //    must defeat any persisted policy. Mirrors SWEET_SEARCH_COREML_CASCADE=0.
+  if (isEnvOff(env.SWEET_SEARCH_LI_RERANK)) {
+    return {
+      effective: false,
+      policy: declaredPolicy,
+      reason: 'SWEET_SEARCH_LI_RERANK=0 (env opt-out)',
+    };
+  }
+  if (isEnvOn(env.SWEET_SEARCH_LI_RERANK)) {
+    // Env-on still goes through the safety check below — we never silently
+    // rerank with a missing or mismatched index.
+    if (!manifestUsable(manifest)) {
+      return {
+        effective: false,
+        policy: declaredPolicy,
+        reason: 'SWEET_SEARCH_LI_RERANK=1 but no usable LI index',
+        warning: manifestUnusableReason(manifest),
+      };
+    }
+    return {
+      effective: true,
+      policy: declaredPolicy,
+      reason: 'SWEET_SEARCH_LI_RERANK=1 (env opt-in)',
+      ...(isEdgeManifest(manifest) ? { warning: edgeOnWarning() } : {}),
+    };
+  }
+
+  // 3. Persisted explicit ON / OFF (init wizard / --search-reranking).
+  if (declaredPolicy === 'off') {
+    return {
+      effective: false,
+      policy: 'off',
+      reason: 'persisted searchReranking=off',
+    };
+  }
+  if (declaredPolicy === 'on') {
+    if (!manifestUsable(manifest)) {
+      return {
+        effective: false,
+        policy: 'on',
+        reason: 'persisted searchReranking=on but no usable LI index',
+        warning: manifestUnusableReason(manifest),
+      };
+    }
+    return {
+      effective: true,
+      policy: 'on',
+      reason: 'persisted searchReranking=on',
+      ...(isEdgeManifest(manifest) ? { warning: edgeOnWarning() } : {}),
+    };
+  }
+
+  // 4. Auto (the default): consult the index manifest.
+  //    - missing/mismatched → off (with diagnostic)
+  //    - edge modelId       → off (Phase 3 shows edge LI rerank is net-negative)
+  //    - any standard model → on
+  if (manifest != null && (manifest.exists === false)) {
+    return {
+      effective: false,
+      policy: 'auto',
+      reason: 'auto: no LI index on disk',
+    };
+  }
+  if (manifest != null && manifest.modelMismatch === true) {
+    return {
+      effective: false,
+      policy: 'auto',
+      reason: `auto: LI index model mismatch (header=${manifest.modelId ?? '?'})`,
+    };
+  }
+  if (manifest != null && isEdgeManifest(manifest)) {
+    return {
+      effective: false,
+      policy: 'auto',
+      reason: `auto: edge LI index (${manifest.modelId}) — search rerank disabled by default (see Phase 3 bench)`,
+    };
+  }
+  if (manifest != null && manifest.modelId) {
+    return {
+      effective: true,
+      policy: 'auto',
+      reason: `auto: standard LI index (${manifest.modelId})`,
+    };
+  }
+
+  // 5. Fallback — manifest not yet loaded (early call path) OR no manifest
+  //    info at all. Defer to the active config model so existing flows that
+  //    constructed SweetSearch before init() still get the historical
+  //    behaviour. Edge model active → off; anything else → on.
+  if (input.activeConfigModel === LI_MODEL_EDGE) {
+    return {
+      effective: false,
+      policy: 'auto',
+      reason: 'auto: edge LI active in config (manifest not yet loaded)',
+    };
+  }
+  return {
+    effective: true,
+    policy: 'auto',
+    reason: 'auto: standard LI active in config (manifest not yet loaded)',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (also exported for test reuse)
+// ---------------------------------------------------------------------------
+
+export function normalizePolicy(value) {
+  if (typeof value !== 'string') return 'auto';
+  const v = value.trim().toLowerCase();
+  return VALID_RERANK_POLICIES.includes(v) ? v : 'auto';
+}
+
+export function normalizeLiModel(value) {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  return VALID_LI_MODELS.includes(v) ? v : null;
+}
+
+export function isEdgeManifest(manifest) {
+  return !!manifest && manifest.modelId === LI_MODEL_EDGE;
+}
+
+export function manifestUsable(manifest) {
+  if (manifest == null) return false;
+  if (manifest.exists === false) return false;
+  if (manifest.modelMismatch === true) return false;
+  if (!manifest.modelId) return false;
+  return true;
+}
+
+function manifestUnusableReason(manifest) {
+  if (manifest == null) return 'no LI index manifest';
+  if (manifest.exists === false) return 'no LI index file on disk';
+  if (manifest.modelMismatch === true) {
+    return `LI index built with ${manifest.modelId ?? '?'} but config says otherwise — re-index to fix`;
+  }
+  if (!manifest.modelId) return 'LI index manifest missing modelId';
+  return 'unusable LI index manifest';
+}
+
+function edgeOnWarning() {
+  return (
+    'Edge LI search reranking benchmarked below no-rerank search on '
+    + 'gencodesearchnet (80.65% vs 82.91% MRR). The recommended edge '
+    + 'setup is search reranking off — edge LI tokens still power '
+    + 'read-semantic and ColGrep without participating in search rerank.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Init-side hardware-aware default
+// ---------------------------------------------------------------------------
+
+/**
+ * Recommend an LI model + rerank policy from a hardware capability snapshot.
+ * Pure function — caller passes in detectHardwareCapability() output.
+ *
+ * Conservative: accuracy-first by default. Only recommends edge when the
+ * machine is clearly RAM- or disk-constrained.
+ *
+ * @param {object} hw - shape returned by detectHardwareCapability()
+ * @returns {{ liModel: string, searchReranking: 'auto', reason: string }}
+ */
+export function recommendInitDefaults(hw = {}) {
+  const ramGB = Number(hw.totalMemGB ?? 0);
+  // Constrained heuristic (intentionally narrow — "accuracy-first unless
+  // hardware/disk clearly indicates constrained mode" per Phase 4 brief):
+  //   - RAM ≤ 8 GB                                  → edge
+  //   - Apple Silicon M1/M2 (older ANE)             → edge candidate
+  //   - everything else                              → standard
+  // The bench shows standard LI is the accuracy default; only flip when
+  // the constrained signal is unambiguous.
+  const isLowRam = ramGB > 0 && ramGB <= 8;
+  const isOlderApple =
+    hw.appleSilicon && typeof hw.appleSilicon === 'object'
+      ? Number(hw.appleSilicon.generation ?? hw.appleSilicon.gen ?? 99) <= 2
+      : false;
+
+  if (isLowRam) {
+    return {
+      liModel: LI_MODEL_EDGE,
+      searchReranking: 'auto',
+      reason: `constrained: RAM=${ramGB} GB (≤8) — edge LI for indexing, search rerank auto-disables on edge per Phase 3 bench`,
+    };
+  }
+  if (isOlderApple && ramGB > 0 && ramGB <= 16) {
+    return {
+      liModel: LI_MODEL_EDGE,
+      searchReranking: 'auto',
+      reason: `constrained: M1/M2 + RAM=${ramGB} GB — edge LI recommended for indexing speed + disk savings`,
+    };
+  }
+  return {
+    liModel: LI_MODEL_STANDARD,
+    searchReranking: 'auto',
+    reason: ramGB > 0
+      ? `capable: RAM=${ramGB} GB — standard LI (accuracy default at 85.57% MRR on gencodesearchnet)`
+      : 'capable (default): standard LI (accuracy default)',
+  };
+}