sweet-search 0.0.1 → 2.3.0

package/core/search/sweet-search.js

@@ -0,0 +1,632 @@
+#!/usr/bin/env node
+/**
+ * Sweet Search v2.3 - Unified Search Pipeline with Auto-Warm Server
+ * Server: /tmp/sweet-search.sock (Unix), port 9876 (TCP)
+ * See search-server.js for server implementation.
+ *
+ * SOLID refactor: Functions extracted into search-fusion, search-boost,
+ * search-format, search-semantic, search-hybrid, search-postprocess,
+ * search-server, search-cli modules and wired back via prototype.
+ */
+
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { DB_PATHS, PERFORMANCE_TARGETS, LOGGING, BINARY_HNSW_CONFIG, HCGS_CONFIG, LATE_INTERACTION_CONFIG, EMBEDDING_CONFIG, SEISMIC_CONFIG, CASCADE_CONFIG, loadProjectConfig, shouldUseLocalReranker } from '../infrastructure/config/index.js';
+import { getGlobalLocalReranker } from '../ranking/local-reranker.js';
+import { QueryRouter, routeQuery } from '../query/query-router.js';
+import { GraphSearch } from '../graph/graph-search.js';
+import { SYMBOL_KIND_WEIGHTS, DEFINITION_TYPES } from '../infrastructure/constants.js';
+import { HNSWIndex } from '../vector-store/hnsw-index.js';
+import { BinaryHNSWIndex } from '../vector-store/binary-hnsw-index.js';
+import { Reranker } from '../ranking/flashrank.js';
+import { LateInteractionIndex } from '../ranking/late-interaction-index.js';
+import { getEmbedding, getBinaryEmbedding, truncateForHNSW, int8CosineSimilarity, warmup as warmupEmbedding, isWarm, registerAutoPersistOnExit } from '../embedding/embedding-service.js';
+import { FloatVectorStore, getFloatStorePath } from '../vector-store/float-vector-store.js';
+import { recordQueryTelemetry } from '../embedding/embedding-cache.js';
+import { CodebaseRepository } from '../infrastructure/codebase-repository.js';
+import { CodeGraphRepository } from '../infrastructure/code-graph-repository.js';
+import { loadSparseGramIndex } from '../infrastructure/native-sparse-gram.js';
+import { expandResults } from '../graph/graph-expansion.js';
+import { applyMMR, shouldApplyMMR, getLambdaForIntent, MMR_CONFIG } from '../ranking/mmr.js';
+import { QualityScorer, setRepoMapModule } from '../ranking/quality-scorer.js';
+import { pageRank, loadGraph, buildAdjacency } from '../graph/repo-map.js';
+import { classifyIntent, getIntentPolicy } from '../query/intent-router.js';
+
+// SOLID extracted modules
+import * as fusion from './search-fusion.js';
+import * as boost from './search-boost.js';
+import * as format from './search-format.js';
+import * as semantic from './search-semantic.js';
+import * as hybrid from './search-hybrid.js';
+import * as postprocess from './search-postprocess.js';
+import * as pattern from './search-pattern.js';
+
+export { ROUTE_ALPHAS } from './search-fusion.js';
+
+// =============================================================================
+// STRUCTURAL QUERY PARSING (entity + type extraction for --structural flag)
+// =============================================================================
+
+const STRUCTURAL_PATTERNS = {
+  callers: /\b(?:(?:what|who|show|find|list)\s+(?:calls?|callers?|calling|invokes?|references?|uses)\s+(?:of\s+|to\s+)?|callers?\s+of\s+|what\s+uses\s+|usages?\s+of\s+|references?\s+to\s+)(\w+)/i,
+  callers2: /\bwhere\s+is\s+(\w+)\s+called\b/i,
+  callees: /\bwhat\s+does\s+(\w+)\s+(?:call|invoke|use|depend\s+on|import)\b/i,
+  callees2: /\b(?:callees?\s+of|dependencies\s+of|(?:methods?|functions?)\s+called\s+by)\s+(\w+)/i,
+  implementations: /\b(?:(?:implementations?|implementers?|implementors?|subclasses?|subtypes?)\s+of|(?:classes?|types?)\s+(?:that\s+)?(?:implementing?|extending?)|(?:who|what)\s+(?:extends?|implements?))\s+(\w+)/i,
+  impact: /\b(?:impact\s+of\s+(?:changing|modifying|refactoring|updating|deleting|removing|renaming|moving)|(?:what\s+)?depends?\s+on|(?:will|what)\s+breaks?\s+if\s+(?:I|we)\s+(?:change|modify|update|delete|remove)|affected\s+by\s+(?:changes?\s+to|modifying)?|(?:downstream|ripple)\s+effects?\s+of|what\s+needs?\s+to\s+change\s+if\s+(?:I|we)\s+(?:refactor|modify))\s+(\w+)/i,
+};
+
+/**
+ * Parse a structural query to extract the type and target entity.
+ * Used when structural mode is forced via explicit flag.
+ *
+ * @param {string} query
+ * @returns {{ structuralType: string|null, targetEntity: string|null }}
+ */
+function parseStructuralQuery(query) {
+  for (const [type, pattern] of Object.entries(STRUCTURAL_PATTERNS)) {
+    const match = query.match(pattern);
+    if (match) {
+      // Find last non-undefined capture group
+      let entity = null;
+      for (let i = match.length - 1; i >= 1; i--) {
+        if (match[i] !== undefined) { entity = match[i]; break; }
+      }
+      if (entity) {
+        // Normalize subtypes: callers2→callers, callees2→callees
+        const normalized = type.replace(/\d+$/, '');
+        return { structuralType: normalized, targetEntity: entity };
+      }
+    }
+  }
+  // No pattern matched — caller should fall back to hybrid
+  return { structuralType: null, targetEntity: null };
+}
+
+export class SweetSearch {
+  constructor(options = {}) {
+    const projectRoot = options.projectRoot || process.env.SWEET_SEARCH_PROJECT_ROOT || process.cwd();
+    this.projectRoot = projectRoot;
+    const projectConfig = loadProjectConfig(projectRoot);
+    const projectCascade = projectConfig.cascade || {};
+    const envOrProject = (envKey, cascadeKey, configKey) =>
+      process.env[envKey] != null ? CASCADE_CONFIG[configKey] : projectCascade[cascadeKey];
+
+    this.graphSearch = new GraphSearch(options.graphDbPath || DB_PATHS.codeGraph);
+    this.codeGraphRepo = new CodeGraphRepository(options.graphDbPath || DB_PATHS.codeGraph);
+    this.hnswIndex = new HNSWIndex({ indexPath: options.hnswPath || DB_PATHS.hnswIndex });
+    this.binaryHnswIndex = new BinaryHNSWIndex({ indexPath: options.binaryHnswPath || DB_PATHS.binaryHnswIndex });
+    this.reranker = new Reranker(options);
+    this.lateInteractionIndex = new LateInteractionIndex(options.lateInteractionOptions || {});
+    this.router = new QueryRouter();
+    this.codebaseDbPath = options.codebaseDbPath || DB_PATHS.codebase;
+    this.sparseGramIndexPath = options.sparseGramIndexPath || DB_PATHS.sparseGramIndex;
+    this.verbose = options.verbose ?? LOGGING.verbose;
+    this.timing = options.timing ?? LOGGING.timing;
+    this.use3Stage = options.use3Stage ?? true;
+    this.stage1Candidates = options.stage1Candidates ?? BINARY_HNSW_CONFIG.retrieval.stage1Candidates;
+    this.stage2Candidates = options.stage2Candidates ?? BINARY_HNSW_CONFIG.retrieval.stage2Candidates;
+    this.stage3Candidates = options.stage3Candidates ?? BINARY_HNSW_CONFIG.retrieval.stage3Candidates;
+    this.useLateInteraction = options.useLateInteraction ?? LATE_INTERACTION_CONFIG.enabled;
+    this.lateInteractionBlendWeight = options.lateInteractionBlendWeight ?? LATE_INTERACTION_CONFIG.blendWeight ?? 0.3;
+    this.returnSummaryFirst = options.returnSummaryFirst ?? HCGS_CONFIG.returnSummaryFirst;
+    this.summaryTokenBudget = options.summaryTokenBudget ?? HCGS_CONFIG.summaryTokenBudget;
+    this.fullCodeTokenBudget = options.fullCodeTokenBudget ?? HCGS_CONFIG.fullCodeTokenBudget;
+    // SEISMIC sparse vector path (lazy-loaded when SEISMIC_CONFIG.enabled)
+    this._seismicIndex = null;
+    // Direct-access float vector store for Stage 2.5 (replaces SQLite on hot path)
+    this.floatVectorStore = new FloatVectorStore();
+    this.qualityWeight = options.qualityWeight ?? 0;
+    // Cascade scoring (Section 26): MaxSim → gate → conditional CE
+    this.cascadeEnabled = options.cascadeEnabled
+      ?? envOrProject('SWEET_SEARCH_CASCADE_ENABLED', 'enabled', 'enabled')
+      ?? CASCADE_CONFIG.enabled;
+    this.cascadeCeTopK = options.cascadeCeTopK
+      ?? envOrProject('SWEET_SEARCH_CASCADE_CE_TOP_K', 'ceTopK', 'ceTopK')
+      ?? CASCADE_CONFIG.ceTopK;
+    this.cascadeGateThreshold = options.cascadeGateThreshold
+      ?? envOrProject('SWEET_SEARCH_CASCADE_GATE_THRESHOLD', 'gateThreshold', 'gateThreshold')
+      ?? CASCADE_CONFIG.gateThreshold;
+    this.cascadeForceFullCE = options.cascadeForceFullCE
+      ?? envOrProject('SWEET_SEARCH_FORCE_FULL_CE', 'forceFullCrossEncoder', 'forceFullCrossEncoder')
+      ?? CASCADE_CONFIG.forceFullCrossEncoder;
+    this.cascadeShadowMode = options.cascadeShadowMode
+      ?? CASCADE_CONFIG.shadowMode;
+    setRepoMapModule({ pageRank, loadGraph, buildAdjacency });
+    this._qualityScorer = null;
+    this.codebaseRepo = new CodebaseRepository(this.codebaseDbPath);
+    this.sparseGramIndex = null;
+    this.grepInitialized = false;
+    this.initialized = false;
+  }
+
+  /** @deprecated Use codebaseRepo methods instead. Bridge for legacy callers. */
+  get codebaseDb() {
+    // TODO: Remove once all callers migrate to codebaseRepo
+    return this.codebaseRepo;
+  }
+
+  /** Initialize all search components */
+  async init() {
+    if (this.initialized) return;
+    const start = Date.now();
+
+    this.hasGraphIndex = existsSync(DB_PATHS.codeGraph);
+    this.hasHnswIndex = existsSync(DB_PATHS.hnswIndex.replace('.idx', '.meta.json'));
+    this.hasBinaryHnswIndex = existsSync(DB_PATHS.binaryHnswIndex.replace('.idx', '.meta.json'));
+    this.hasCodebaseIndex = existsSync(this.codebaseDbPath);
+    this.hasLateInteractionIndex = existsSync(this.lateInteractionIndex.indexPath);
+    this.hasSparseGramIndex = existsSync(this.sparseGramIndexPath);
+
+    if (!this.hasGraphIndex && !this.hasCodebaseIndex) {
+      throw new Error('No search indexes found. Run indexing first.');
+    }
+
+    if (this.hasBinaryHnswIndex && this.use3Stage) {
+      try {
+        await this.binaryHnswIndex.load();
+        const stats = this.binaryHnswIndex.getStats();
+        this.log(`BinaryHNSW: Loaded ${stats.totalVectors} vectors (${stats.memorySizeMB} MB)`);
+      } catch (err) {
+        const isPipelineMismatch = err.message.includes('Pipeline version mismatch');
+        if (isPipelineMismatch) {
+          console.error(`[SweetSearch] REBUILD REQUIRED: ${err.message}`);
+          console.error('[SweetSearch] Run: node core/artifact-builder.js (or re-index) to rebuild.');
+        }
+        this.log(`BinaryHNSW: Failed to load: ${err.message}`);
+        this.hasBinaryHnswIndex = false;
+      }
+
+      // Float store loads separately — a corrupt/missing float store must NOT
+      // disable the entire 3-stage pipeline. Stage 2.5 falls back to SQLite.
+      if (this.hasBinaryHnswIndex) {
+        try {
+          const floatStorePath = getFloatStorePath(DB_PATHS.binaryHnswIndex);
+          const floatLoaded = await this.floatVectorStore.load(floatStorePath);
+          if (floatLoaded) {
+            const fStats = this.floatVectorStore.getStats();
+            this.log(`FloatStore: Loaded ${fStats.count} vectors (${fStats.memorySizeMB} MB)`);
+          } else {
+            this.log('FloatStore: Not found, Stage 2.5 will use SQLite fallback');
+          }
+        } catch (err) {
+          this.log(`FloatStore: Failed to load (Stage 2.5 will use SQLite fallback): ${err.message}`);
+        }
+      }
+    }
+
+    if (this.hasHnswIndex) {
+      try {
+        await this.hnswIndex.load(undefined, { mmap: true });
+        this.log(`HNSW: Loaded ${this.hnswIndex.getStats().totalVectors} vectors (mmap)`);
+      } catch (err) {
+        this.log(`HNSW: Failed to load: ${err.message}`);
+        this.hasHnswIndex = false;
+      }
+    }
+
+    if (this.hasLateInteractionIndex && this.useLateInteraction) {
+      try {
+        await this.lateInteractionIndex.init();
+        const stats = this.lateInteractionIndex.getStats();
+        this.log(`LateInteraction: Loaded ${stats.documents} documents (${stats.estimatedSizeMB} MB, ${stats.avgTokensPerDoc} avg tokens)`);
+
+        // Preheat LI ONNX inference model (~900ms cold start otherwise).
+        // The index loads token vectors; this loads the query encoder model.
+        const { encodeQuery } = await import('../ranking/late-interaction-model.js');
+        await encodeQuery('warmup');
+        this.log('LateInteraction: ONNX model preheated');
+      } catch (err) {
+        this.log(`LateInteraction: Failed to load: ${err.message}`);
+        this.hasLateInteractionIndex = false;
+      }
+    }
+
+    if (this.hasSparseGramIndex) {
+      try {
+        this.sparseGramIndex = loadSparseGramIndex(this.sparseGramIndexPath);
+        if (this.sparseGramIndex) {
+          const stats = this.sparseGramIndex.getStats();
+          this.log(
+            `SparseGram: Loaded ${stats.grams} grams across ${stats.totalFiles} files ` +
+            `(${stats.postings} postings${stats.usedFallbackWeights ? ', fallback weights' : ''})`
+          );
+        } else {
+          this.hasSparseGramIndex = false;
+        }
+      } catch (err) {
+        this.log(`SparseGram: Failed to load: ${err.message}`);
+        this.hasSparseGramIndex = false;
+        this.sparseGramIndex = null;
+      }
+    }
+
+    await warmupEmbedding({ initVocabulary: true, initSemanticCache: true });
+
+    if (shouldUseLocalReranker()) {
+      try {
+        const localReranker = getGlobalLocalReranker();
+        await localReranker.init();
+        this.log('LocalReranker: Pre-initialized (gte-reranker-modernbert-base INT8)');
+      } catch (err) {
+        this.log(`LocalReranker: Pre-init failed: ${err.message}`);
+      }
+    }
+
+    this.initialized = true;
+    this.log(`SweetSearch: Initialized in ${Date.now() - start}ms`);
+  }
+
+  async initGrepOnly() {
+    if (this.grepInitialized || this.initialized) return;
+    const start = Date.now();
+
+    this.hasCodebaseIndex = existsSync(this.codebaseDbPath);
+    this.hasSparseGramIndex = existsSync(this.sparseGramIndexPath);
+    if (this.hasSparseGramIndex) {
+      try {
+        this.sparseGramIndex = loadSparseGramIndex(this.sparseGramIndexPath);
+        if (this.sparseGramIndex) {
+          const stats = this.sparseGramIndex.getStats();
+          this.log(
+            `SparseGram: Loaded ${stats.grams} grams across ${stats.totalFiles} files ` +
+            `(${stats.postings} postings${stats.usedFallbackWeights ? ', fallback weights' : ''})`
+          );
+        } else {
+          this.hasSparseGramIndex = false;
+        }
+      } catch (err) {
+        this.log(`SparseGram: Failed to load: ${err.message}`);
+        this.hasSparseGramIndex = false;
+        this.sparseGramIndex = null;
+      }
+    }
+
+    this.grepInitialized = true;
+    this.log(`SweetSearch: Grep-only initialized in ${Date.now() - start}ms`);
+  }
+
+  /** Main search entry point. */
+  async search(query, options = {}) {
+    const {
+      k = 10, mode: requestedMode = 'auto', regex = '', expand = true, rerank = true,
+      fusion: fusionOpt = 'cc', useLateInteraction = this.useLateInteraction,
+      graphExpand = 'none', graphExpandOptions = {},
+      adaptiveHop2 = true, intent = 'none', qualityWeight = this.qualityWeight,
+    } = options;
+    const mode = requestedMode === 'grep' ? 'grep' : (regex ? 'pattern' : requestedMode);
+
+    if (mode === 'grep') {
+      await this.initGrepOnly();
+    } else {
+      await this.init();
+    }
+
+    const start = Date.now();
+    const stats = { query };
+
+    // P2.2: Intent-aware retrieval routing
+    let effectiveGraphExpand = graphExpand;
+    let intentResult;
+    let intentPolicy = null;
+    if (intent === 'auto') {
+      intentResult = classifyIntent(query);
+    } else if (intent && intent !== 'none') {
+      intentResult = { intent, confidence: 1, scores: {} };
+    }
+    if (intentResult) {
+      intentPolicy = getIntentPolicy(intentResult.intent);
+      stats.intent = {
+        classified: intentResult.intent, confidence: intentResult.confidence,
+        expandMode: intentPolicy.expandMode, maxResults: intentPolicy.maxResults,
+      };
+      if (graphExpand === 'none' && intentPolicy.expandMode !== 'none') {
+        effectiveGraphExpand = intentPolicy.expandMode;
+      }
+    }
+
+    // Step 1: Route query
+    const routing = mode === 'auto' ? routeQuery(query) : null;
+    let searchMode;
+    if (mode === 'auto') {
+      searchMode = routing.mode;
+      stats.routing = { mode: routing.mode, confidence: routing.confidence, latency_us: routing.routingLatency_us };
+    } else {
+      searchMode = mode;
+      stats.routing = {
+        mode,
+        forced: true,
+        ...(regex && requestedMode !== 'auto' && requestedMode !== 'pattern'
+          ? { requestedMode, regexForced: true }
+          : {}),
+      };
+    }
+    this.log(`Search mode: ${searchMode}`);
+
+    // Step 2: Execute search based on mode
+    let results;
+    let semanticStats = null;
+
+    switch (searchMode) {
+      case 'grep': {
+        const grepResult = await this.bareGrep(query, routing, {
+          ...options,
+          regex: regex || query,
+        });
+        results = grepResult.results;
+        Object.assign(stats, grepResult.stats);
+        stats.total_ms = grepResult.stats.total_ms ?? (Date.now() - start);
+        return { results, stats };
+      }
+      case 'pattern': {
+        const patternResult = await this.patternSearch(query, routing, options);
+        // Agent mode returns a fully packaged response — bypass post-retrieval.
+        if (patternResult.format === 'agent') {
+          Object.assign(stats, patternResult.stats);
+          stats.total_ms = stats.total_ms ?? (Date.now() - start);
+          return patternResult;
+        }
+        results = patternResult.results;
+        Object.assign(stats, patternResult.stats);
+        break;
+      }
+      case 'structural':
+        results = await this.structuralSearch(query, routing, options);
+        stats.path = 'structural';
+        stats.structuralType = routing?.structuralType;
+        stats.targetEntity = routing?.targetEntity;
+        break;
+      case 'lexical': {
+        const lexResult = await this.lexicalSearch(query, { k, expand });
+        results = lexResult.results;
+        stats.path = 'lexical';
+        stats.confidence = lexResult.stats?.confidence;
+        stats.lexicalMode = lexResult.stats?.mode;
+        // When expansion was deferred (ambiguous + expand=true), ensure
+        // postprocess expansion runs by promoting graphExpand from 'none'.
+        if (stats.confidence === 'ambiguous' && expand && effectiveGraphExpand === 'none') {
+          effectiveGraphExpand = '2hop';
+        }
+        break;
+      }
+      case 'semantic': {
+        const semanticResult = await this.semanticSearch(query, { k, rerank, useLateInteraction });
+        results = semanticResult.results;
+        semanticStats = semanticResult.stats;
+        stats.path = 'semantic';
+        break;
+      }
+      case 'hybrid':
+      default: {
+        const hybridResult = await this.hybridSearchV2(query, { k, useLateInteraction, routing });
+        results = hybridResult.results || hybridResult;
+        semanticStats = hybridResult.semanticStats || null;
+        stats.path = 'hybrid';
+        stats.fusion = hybridResult.fusionStats?.method || 'cc';
+        stats.fusionFallback = hybridResult.fusionStats?.fallbackReason || null;
+        stats.lexicalLatencyMs = hybridResult.fusionStats?.lexicalLatencyMs ?? null;
+        break;
+      }
+    }
+
+    // Enable adaptive 2-hop expansion for semantic + hybrid (graph completion
+    // improves recall; cascade handles precision). Lexical ambiguous case is
+    // handled inside its switch block (depends on stats.confidence).
+    if ((searchMode === 'semantic' || searchMode === 'hybrid')
+        && effectiveGraphExpand === 'none' && expand) {
+      effectiveGraphExpand = '2hop';
+    }
+
+    // Step 3: Post-retrieval processing (delegated to extracted module)
+    return this._applyPostRetrieval(results, query, options, {
+      stats, semanticStats, searchMode, effectiveGraphExpand, intentPolicy, start,
+    });
+  }
+
+  /** Structural search path (GraphRAG structural queries — opt-in via explicit flag) */
+  async structuralSearch(query, routing, options = {}) {
+    // Extract type+entity from routing (if available) or from query patterns
+    const parsed = routing && routing.structuralType
+      ? routing
+      : parseStructuralQuery(query);
+    const { structuralType, targetEntity } = parsed;
+
+    if (!structuralType || !targetEntity) {
+      this.log('Structural: no pattern match, falling back to hybrid');
+      return this.hybridSearchV2(query, options);
+    }
+
+    const start = performance.now();
+    let result;
+    switch (structuralType) {
+      case 'callers': result = await this.graphSearch.findCallers(targetEntity); break;
+      case 'callees': result = await this.graphSearch.findCallees(targetEntity); break;
+      case 'implementations': result = await this.graphSearch.findImplementations(targetEntity); break;
+      case 'impact': result = await this.graphSearch.findImpact(targetEntity); break;
+      default: return this.hybridSearchV2(query, options);
+    }
+    const elapsed = performance.now() - start;
+    this.log(`Structural (${structuralType}): ${elapsed.toFixed(1)}ms, ${result.results.length} results`);
+    return result.results.map(r => ({ ...r, searchPath: 'structural', structuralType }));
+  }
+
+  /** Lexical search path (FTS5/BM25 + Graph) */
+  async lexicalSearch(query, options = {}) {
+    const { k = 10, expand = true } = options;
+    if (!this.hasGraphIndex) {
+      this.log('Lexical search unavailable: no graph index');
+      return { results: [], stats: { confidence: 'exact' } };
+    }
+    const { results, stats } = await this.graphSearch.graphExpandedSearch(query, {
+      k, expand, deferExpansion: expand,
+    });
+    this.log(`Lexical: ${stats.bm25_ms}ms BM25, ${stats.graph_ms || 0}ms graph (confidence: ${stats.confidence})`);
+    return {
+      results: results.map(r => ({ ...r, searchPath: 'lexical' })),
+      stats,
+    };
+  }
+
+  /** Semantic search dispatcher. Delegates to 3Stage or Standard based on config. */
+  async semanticSearch(query, options = {}) {
+    const { k = 10, rerank = true, useLateInteraction = this.useLateInteraction } = options;
+    if (this.hasBinaryHnswIndex && this.use3Stage) {
+      return this.semanticSearch3Stage(query, { k, rerank, useLateInteraction });
+    }
+    return this.semanticSearchStandard(query, { k, rerank });
+  }
+
+  /** O(N) vector scan fallback (when HNSW not available). Filters stale entities. */
+  async vectorScan(queryEmbedding, limit = 100) {
+    // Ephemeral scan — opens, reads, closes (no persistent connection)
+    const rows = this.codebaseRepo.scanAllVectors();
+    const candidates = [];
+
+    const staleEntityIds = this.hasGraphIndex
+      ? await this.graphSearch.getStaleEntityIds().catch(err => {
+          this.log(`A1: Could not load stale entity list: ${err.message}`);
+          return new Set();
+        })
+      : new Set();
+
+    for (const row of rows) {
+      const embeddingBuffer = row.embedding;
+      if (!embeddingBuffer) continue;
+      const embedding = new Float32Array(embeddingBuffer.buffer, embeddingBuffer.byteOffset, embeddingBuffer.length / 4);
+      const score = this.cosineSimilarity(queryEmbedding, Array.from(embedding));
+      let metadata = {};
+      try { metadata = row.metadata ? JSON.parse(row.metadata) : {}; } catch (err) {
+        if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] ${err?.message || err}\n`);
+      }
+      candidates.push({ id: row.id, content: row.text || '', score, metadata, entity_id: metadata.entity_id || null });
+    }
+
+    const activeResults = candidates.filter(r => {
+      if (r.entity_id && staleEntityIds.has(r.entity_id)) return false;
+      if (r.metadata?.entity_id && staleEntityIds.has(r.metadata.entity_id)) return false;
+      return true;
+    });
+    this.log(`A1: Vector scan found ${candidates.length} candidates, ${activeResults.length} active (${staleEntityIds.size} stale entities filtered)`);
+    return activeResults.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  /** Load document content for CE reranking — pure chunk text, no metadata noise */
+  async loadDocumentContent(candidates, query = '') {
+    return candidates.map(c => c.content || c.text || '');
+  }
+
+  /** Cosine similarity — throws on dimension mismatch instead of silently truncating. */
+  cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+      throw new Error(`cosineSimilarity dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; normA += a[i] * a[i]; normB += b[i] * b[i]; }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+
+  /**
+   * Fix 5.5: Load float embeddings from SQLite for a set of chunk IDs.
+   * Uses batch WHERE IN query for efficiency (single round-trip).
+   * Returns Map<id, Float32Array>.
+   */
+  async _loadFloatVectors(ids) {
+    if (!this.codebaseDbPath || !existsSync(this.codebaseDbPath)) return null;
+    if (!ids.length) return new Map();
+    try {
+      return this.codebaseRepo.getEmbeddingsByIds(ids);
+    } catch (err) {
+      this.log(`_loadFloatVectors failed: ${err.message}`);
+      return new Map();
+    }
+  }
+
+  // approximateLateInteractionScore removed — replaced by real per-token MaxSim via LateOn-Code
+  // in search-semantic.js (Phase 4 of LATE_INTERACTION.md)
+
+  /** Log message (if verbose). Uses stderr to avoid corrupting JSON output. */
+  log(message) { if (this.verbose) console.error(`[SweetSearch] ${message}`); }
+
+  /** Log performance stats */
+  logPerformance(stats) {
+    const target = PERFORMANCE_TARGETS.latency;
+    let status = 'OK';
+    if (stats.path === 'lexical' && stats.total_ms > target.lexicalP50 * 2) status = 'SLOW';
+    if (stats.path === 'semantic' && stats.total_ms > target.semanticP50 * 2) status = 'SLOW';
+    console.error(`[Perf] ${stats.path} | ${stats.total_ms}ms | ${status}`);
+  }
+
+  /** Close all connections */
+  close() {
+    this.graphSearch.close();
+    this.codebaseRepo.close();
+    this.codeGraphRepo.close();
+  }
+}
+
+// Prototype wiring (extracted module functions)
+Object.assign(SweetSearch.prototype, {
+  getResultKey: fusion.getResultKey,
+  minMaxNormalize: fusion.minMaxNormalize,
+  quantileNormalize: fusion.quantileNormalize,
+  convexCombination: fusion.convexCombination,
+  shouldFallbackToRRF: fusion.shouldFallbackToRRF,
+  rrfFusion: fusion.rrfFusion,
+  robustCCFusion: fusion.robustCCFusion,
+  variance: fusion.variance,
+  getBoostIntent: boost.getBoostIntent,
+  applyPostFusionBoosts: boost.applyPostFusionBoosts,
+  computeDefinitionBoost: boost.computeDefinitionBoost,
+  computeSyntaxBoost: boost.computeSyntaxBoost,
+  computePositionBoost: boost.computePositionBoost,
+  extractQueryTokens: boost.extractQueryTokens,
+  formatResults: format.formatResults,
+  formatStructuralResults: format.formatStructuralResults,
+  formatSummaryFirst: format.formatSummaryFirst,
+  formatMiddleRes: format.formatMiddleRes,
+  enrichWithSummaries: format.enrichWithSummaries,
+  semanticSearch3Stage: semantic.semanticSearch3Stage,
+  semanticSearchStandard: semantic.semanticSearchStandard,
+  shouldSkipRerank: semantic.shouldSkipRerank,
+  getAdaptiveCandidateCount: semantic.getAdaptiveCandidateCount,
+  hybridSearchV2: hybrid.hybridSearchV2,
+  hybridSearch: hybrid.hybridSearch,
+  patternSearch: pattern.patternSearch,
+  bareGrep: pattern.bareGrep,
+  getChunkLocationMap: pattern.getChunkLocationMap,
+  _applyPostRetrieval: postprocess.applyPostRetrieval,
+});
+
+SweetSearch.BOOST_POLICY = boost.BOOST_POLICY;
+
+// Module-level singleton (warm cache)
+let _warmSearcher = null;
+let _warmInitPromise = null;
+
+/** Get or create a warm SweetSearch instance (singleton). */
+export async function getWarmSearcher(options = {}) {
+  if (_warmSearcher && _warmSearcher.initialized) return _warmSearcher;
+  if (_warmInitPromise) { await _warmInitPromise; return _warmSearcher; }
+  _warmSearcher = new SweetSearch(options);
+  _warmInitPromise = _warmSearcher.init();
+  await _warmInitPromise;
+  return _warmSearcher;
+}
+
+/** Quick search using warm cache (for programmatic use) */
+export async function warmSearch(query, options = {}) {
+  const searcher = await getWarmSearcher();
+  return searcher.search(query, options);
+}
+
+// CLI guard
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const { runCli } = await import('./search-cli.js');
+  await runCli(args);
+}
+
+export default SweetSearch;
+/** @deprecated Use SweetSearch instead. SmartSearch is a legacy alias. */
+export { SweetSearch as SmartSearch };