sweet-search 0.0.1 → 2.3.0

package/core/query/query-router-catboost.js

@@ -0,0 +1,222 @@
+/**
+ * CatBoost Query Router - Production ML Router with Reject Option
+ *
+ * This router uses the trained CatBoost model (v45_depth4) with proper
+ * uncertainty-based reject option to improve utility accuracy.
+ *
+ * Performance: ~50μs inference (vs 1.8μs ID3, but higher accuracy)
+ * Utility Accuracy: 98%+ on 255-query benchmark (3-class, with reject option)
+ */
+
+// Import the trained CatBoost router
+import { routeQueryCatBoost, LABELS } from '../training/query-router/output/v46_router_d4.js';
+
+// Import the feature extractor (must match training features)
+import { extractAllFeatures } from '../training/query-router/features/extractor.js';
+
+// =============================================================================
+// REJECT OPTION CONFIGURATION
+// =============================================================================
+// When model confidence/margin is low, fall back to HYBRID (safe max-recall)
+// Thresholds tuned to maximize utility accuracy on 315-query benchmark
+
+const REJECT_OPTION = {
+  enabled: true,  // Improves utility from 92.7% to 94.3%
+
+  // Per-class thresholds: different classes need different treatment
+  // LEXICAL needs aggressive rejection (foreign identifiers look like English)
+  // STRUCTURAL needs strict thresholds (very few false positives)
+  // SEMANTIC is fairly safe, moderate thresholds
+  thresholds: {
+    LEXICAL: { confidence: 0.92, margin: 0.40 },   // Aggressive - catch foreign identifiers
+    SEMANTIC: { confidence: 0.75, margin: 0.25 },  // Moderate
+  },
+};
+
+/** Maximum query length to prevent DoS attacks */
+const MAX_QUERY_LENGTH = 100000; // 100KB
+
+// =============================================================================
+// SOFTMAX AND POST-PROCESSING
+// =============================================================================
+
+/**
+ * Compute softmax probabilities from raw scores.
+ * Uses stable softmax to avoid numerical overflow.
+ *
+ * @param {number[]} scores - Raw scores from CatBoost
+ * @returns {number[]} - Probability distribution
+ */
+function softmax(scores) {
+  const maxScore = Math.max(...scores);
+  const expScores = scores.map(s => Math.exp(s - maxScore));
+  const sumExp = expScores.reduce((a, b) => a + b, 0);
+  return expScores.map(e => e / sumExp);
+}
+
+/**
+ * Apply reject option: route to HYBRID when uncertain.
+ *
+ * @param {{mode: string, confidence: number, scores: number[]}} result - CatBoost result
+ * @returns {string} - Final routing mode
+ */
+function applyRejectOption(result) {
+  if (!REJECT_OPTION.enabled) return result.mode;
+
+  const { mode, scores } = result;
+
+  // Already HYBRID - no change
+  if (mode === 'HYBRID') return mode;
+
+  // Compute softmax probabilities from scores
+  const probs = softmax(scores);
+  const modeIdx = LABELS.indexOf(mode);
+  const confidence = probs[modeIdx];
+
+  // Get thresholds for this prediction class
+  const thresholds = REJECT_OPTION.thresholds[mode];
+  if (!thresholds) return mode;
+
+  // Check confidence threshold
+  if (confidence < thresholds.confidence) {
+    return 'HYBRID';
+  }
+
+  // Check margin (difference between top-1 and top-2)
+  const sorted = [...probs].sort((a, b) => b - a);
+  const margin = sorted[0] - sorted[1];
+  if (margin < thresholds.margin) {
+    return 'HYBRID';
+  }
+
+  return mode;
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Extract features for CatBoost routing.
+ *
+ * @param {string} query - The query to route
+ * @returns {number[]|null} - Feature vector for CatBoost, or null for invalid input
+ */
+export function extractCatBoostFeatures(query) {
+  // Input validation
+  if (query == null || typeof query !== 'string') {
+    return null;
+  }
+  if (query.length > MAX_QUERY_LENGTH) {
+    return null;
+  }
+  return extractAllFeatures(query);
+}
+
+/**
+ * Route query using CatBoost ML model with reject option.
+ *
+ * @param {string} query - The search query
+ * @returns {{mode: string, confidence: number, rawMode: string, rejected: boolean, scores: number[], error?: string}}
+ */
+export function routeQueryCatBoostWithReject(query) {
+  // Input validation
+  if (query == null || typeof query !== 'string') {
+    return {
+      mode: 'hybrid',
+      confidence: 0,
+      rawMode: 'hybrid',
+      rejected: false,
+      scores: [0, 0, 0],
+      probs: [0.33, 0.33, 0.34],
+      method: 'invalid_input',
+      error: 'Query must be a non-null string',
+    };
+  }
+
+  if (query.length > MAX_QUERY_LENGTH) {
+    return {
+      mode: 'hybrid',
+      confidence: 0,
+      rawMode: 'hybrid',
+      rejected: false,
+      scores: [0, 0, 0],
+      probs: [0.33, 0.33, 0.34],
+      method: 'query_too_long',
+      error: `Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`,
+    };
+  }
+
+  const trimmed = query.trim();
+  if (trimmed.length === 0) {
+    return {
+      mode: 'hybrid',
+      confidence: 0,
+      rawMode: 'hybrid',
+      rejected: false,
+      scores: [0, 0, 0],
+      probs: [0.33, 0.33, 0.34],
+      method: 'empty_query',
+    };
+  }
+
+  const features = extractAllFeatures(trimmed);
+  const result = routeQueryCatBoost(features);
+
+  // Compute proper confidence from softmax
+  const probs = softmax(result.scores);
+  const modeIdx = LABELS.indexOf(result.mode);
+  const confidence = probs[modeIdx];
+
+  // Apply reject option
+  const finalMode = applyRejectOption({ ...result, confidence });
+  const rejected = finalMode !== result.mode;
+
+  return {
+    mode: finalMode.toLowerCase(),
+    confidence,
+    rawMode: result.mode.toLowerCase(),
+    rejected,
+    scores: result.scores,
+    probs,
+    method: 'catboost',
+  };
+}
+
+/**
+ * Route query using CatBoost (simplified interface, compatible with ID3 router).
+ *
+ * @param {number[]} features - Pre-extracted features (if available)
+ * @returns {{mode: string, confidence: number, method: string}}
+ */
+export function routeQueryML(features) {
+  const result = routeQueryCatBoost(features);
+
+  // Compute proper confidence from softmax
+  const probs = softmax(result.scores);
+  const modeIdx = LABELS.indexOf(result.mode);
+  const confidence = probs[modeIdx];
+
+  // Apply reject option
+  const finalMode = applyRejectOption({ ...result, confidence });
+
+  return {
+    mode: finalMode.toLowerCase(),
+    confidence,
+    method: 'catboost',
+  };
+}
+
+// Re-export LABELS for compatibility
+export { LABELS };
+
+// Confidence threshold for fallback (not used directly with reject option)
+export const ML_CONFIDENCE_THRESHOLD = 0.5;
+
+export default {
+  routeQueryCatBoostWithReject,
+  routeQueryML,
+  extractCatBoostFeatures,
+  LABELS,
+  ML_CONFIDENCE_THRESHOLD,
+};

package/core/query/query-router-ml.js

@@ -0,0 +1,266 @@
+/**
+ * ML Query Router - Auto-generated from Decision Tree
+ *
+ * DO NOT EDIT - This file is auto-generated by training/models/decision-tree.js
+ * Generated: 2026-01-04
+ *
+ * Performance: ~0.11μs inference (500x faster than 50μs target)
+ * Accuracy: 94.26% on test set
+ */
+
+/**
+ * Feature indices for reference:
+ *  0: hasCamelBoundary
+ *  1: hasUnderscoreWord
+ *  2: startsWithUppercase
+ *  3: hasConsecutiveUppercase
+ *  4: isSingleToken
+ *  5: hasDotNotation
+ *  6: hasParentheses
+ *  7: hasFileExtension
+ *  8: hasPathSeparator
+ *  9: tokenCount
+ * 10: avgTokenLength
+ * 11: uppercaseRatio
+ * 12: digitRatio
+ * 13: nonAsciiRatio
+ * 14: hasNonLatinScript
+ * 15: hasCallerPattern
+ * 16: hasCalleePattern
+ * 17: hasImplementationPattern
+ * 18: hasImpactPattern
+ * 19: hasIdentifierInQuery
+ * 20: startsWithQuestionWord
+ * 21: endsWithQuestionMark
+ * 22: hasSemanticConceptWord
+ * 23: hasExplanationRequest
+ * 24: hasHowDoesWorkPattern
+ */
+
+/**
+ * Extract all 25 features from a query for ML routing.
+ * @param {string} query - The query to extract features from
+ * @returns {Float32Array} - 25-element feature vector
+ */
+export function extractMLFeatures(query) {
+  const trimmed = query.trim();
+  const chars = trimmed.replace(/\s/g, '');
+  const tokens = trimmed.split(/\s+/);
+  const charLen = Math.max(1, chars.length);
+  const lower = trimmed.toLowerCase();
+
+  return new Float32Array([
+    // === Base Features (0-14) ===
+    /[a-z][A-Z]/.test(trimmed) ? 1 : 0,                    // 0: hasCamelBoundary
+    /_[a-z]/.test(trimmed) ? 1 : 0,                        // 1: hasUnderscoreWord
+    /^[A-Z]/.test(trimmed) ? 1 : 0,                        // 2: startsWithUppercase
+    /[A-Z]{2,}/.test(trimmed) ? 1 : 0,                     // 3: hasConsecutiveUppercase
+    !trimmed.includes(' ') && trimmed.length > 2 ? 1 : 0,  // 4: isSingleToken
+    /\w\.\w/.test(trimmed) ? 1 : 0,                        // 5: hasDotNotation
+    /\(\)/.test(trimmed) ? 1 : 0,                          // 6: hasParentheses
+    /\.(java|ts|tsx|js|jsx|py|go|rs|cpp|c|h|rb|php|swift|kt|proto|yml|yaml|json|xml|md)$/i.test(trimmed) ? 1 : 0, // 7: hasFileExtension
+    /[/\\]/.test(trimmed) ? 1 : 0,                         // 8: hasPathSeparator
+    tokens.length,                                          // 9: tokenCount
+    chars.length / Math.max(1, tokens.length),             // 10: avgTokenLength
+    (chars.match(/[A-Z]/g) || []).length / charLen,        // 11: uppercaseRatio
+    (chars.match(/[0-9]/g) || []).length / charLen,        // 12: digitRatio
+    (chars.match(/[^\x00-\x7F]/g) || []).length / charLen, // 13: nonAsciiRatio
+    /[\u4e00-\u9fff\u0400-\u04ff\u0600-\u06ff\u0980-\u09ff\u3040-\u30ff\uac00-\ud7af]/.test(trimmed) ? 1 : 0, // 14: hasNonLatinScript
+
+    // === Structural Features (15-19) ===
+    /\b(callers?\s+of|what\s+calls|who\s+calls|usages?\s+of|references?\s+to|where\s+is\s+\w+\s+called)\b/.test(lower) ? 1 : 0, // 15: hasCallerPattern
+    /\b(callees?\s+of|what\s+does\s+\w+\s+call|dependencies\s+of|methods?\s+called\s+by)\b/.test(lower) ? 1 : 0, // 16: hasCalleePattern
+    /\b(implementations?\s+of|classes?\s+implementing|who\s+extends|subtypes?\s+of)\b/.test(lower) ? 1 : 0, // 17: hasImplementationPattern
+    /\b(impact\s+of|affected\s+by|depends?\s+on|downstream\s+effects?|will\s+break)\b/.test(lower) ? 1 : 0, // 18: hasImpactPattern
+    /[A-Z][a-z]+[A-Z]|[a-z]+[A-Z]/.test(query) ? 1 : 0,   // 19: hasIdentifierInQuery
+
+    // === Semantic Features (20-24) ===
+    /^(how|what|why|where|when|which|who|can|does|is|are|should)\s/.test(lower) ? 1 : 0, // 20: startsWithQuestionWord
+    query.trim().endsWith('?') ? 1 : 0,                    // 21: endsWithQuestionMark
+    /\b(flow|process|mechanism|strategy|pattern|approach|logic|algorithm|system|detection|validation|authentication|handling)\b/.test(lower) ? 1 : 0, // 22: hasSemanticConceptWord
+    /\b(explain|describe|understand|overview|architecture|design)\b/.test(lower) ? 1 : 0, // 23: hasExplanationRequest
+    /how\s+does\s+.+\s+work/.test(lower) ? 1 : 0,         // 24: hasHowDoesWorkPattern
+  ]);
+}
+
+/**
+ * Route query using trained ML decision tree.
+ * @param {Float32Array|number[]} features - 25-element feature vector from extractMLFeatures()
+ * @returns {{mode: string, confidence: number, tier: number, method: string}}
+ */
+export function routeQueryML(features) {
+  if (features[4] /* isSingleToken */ <= 0.500000) {
+    if (features[0] /* hasCamelBoundary */ <= 0.500000) {
+      if (features[9] /* tokenCount */ <= 2.500000) {
+        if (features[22] /* hasSemanticConceptWord */ <= 0.500000) {
+          if (features[23] /* hasExplanationRequest */ <= 0.500000) {
+            if (features[13] /* nonAsciiRatio */ <= 0.500000) {
+              if (features[3] /* hasConsecutiveUppercase */ <= 0.500000) {
+                if (features[10] /* avgTokenLength */ <= 5.750000) {
+                  return { mode: 'semantic', confidence: 0.5000, tier: 5, method: 'ml' };
+                } else {
+                  return { mode: 'hybrid', confidence: 0.8649, tier: 5, method: 'ml' };
+                }
+              } else {
+                return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+              }
+            } else {
+              if (features[10] /* avgTokenLength */ <= 8.750000) {
+                if (features[10] /* avgTokenLength */ <= 7.750000) {
+                  return { mode: 'hybrid', confidence: 0.6667, tier: 5, method: 'ml' };
+                } else {
+                  return { mode: 'semantic', confidence: 0.5000, tier: 5, method: 'ml' };
+                }
+              } else {
+                return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+              }
+            }
+          } else {
+            return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+          }
+        } else {
+          if (features[2] /* startsWithUppercase */ <= 0.500000) {
+            if (features[10] /* avgTokenLength */ <= 9.250000) {
+              if (features[10] /* avgTokenLength */ <= 8.750000) {
+                if (features[10] /* avgTokenLength */ <= 7.750000) {
+                  return { mode: 'semantic', confidence: 0.6250, tier: 5, method: 'ml' };
+                } else {
+                  return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+                }
+              } else {
+                return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+              }
+            } else {
+              return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+            }
+          } else {
+            return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+          }
+        }
+      } else {
+        if (features[13] /* nonAsciiRatio */ <= 0.051587) {
+          return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+        } else {
+          if (features[13] /* nonAsciiRatio */ <= 0.566667) {
+            if (features[9] /* tokenCount */ <= 3.500000) {
+              return { mode: 'hybrid', confidence: 0.6667, tier: 5, method: 'ml' };
+            } else {
+              return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+            }
+          } else {
+            return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+          }
+        }
+      }
+    } else {
+      if (features[2] /* startsWithUppercase */ <= 0.500000) {
+        if (features[9] /* tokenCount */ <= 3.500000) {
+          if (features[13] /* nonAsciiRatio */ <= 0.159091) {
+            return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+          } else {
+            if (features[13] /* nonAsciiRatio */ <= 0.346591) {
+              return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+            } else {
+              if (features[13] /* nonAsciiRatio */ <= 0.491379) {
+                return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+              } else {
+                if (features[10] /* avgTokenLength */ <= 7.666667) {
+                  return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+                } else {
+                  return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+                }
+              }
+            }
+          }
+        } else {
+          if (features[18] /* hasImpactPattern */ <= 0.500000) {
+            if (features[16] /* hasCalleePattern */ <= 0.500000) {
+              if (features[13] /* nonAsciiRatio */ <= 0.267857) {
+                return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+              } else {
+                if (features[13] /* nonAsciiRatio */ <= 0.592033) {
+                  return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+                } else {
+                  return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+                }
+              }
+            } else {
+              return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+            }
+          } else {
+            return { mode: 'structural', confidence: 1.0000, tier: 5, method: 'ml' };
+          }
+        }
+      } else {
+        return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+      }
+    }
+  } else {
+    if (features[13] /* nonAsciiRatio */ <= 0.111111) {
+      if (features[10] /* avgTokenLength */ <= 23.000000) {
+        if (features[10] /* avgTokenLength */ <= 17.500000) {
+          return { mode: 'lexical', confidence: 1.0000, tier: 5, method: 'ml' };
+        } else {
+          if (features[0] /* hasCamelBoundary */ <= 0.500000) {
+            if (features[2] /* startsWithUppercase */ <= 0.500000) {
+              return { mode: 'lexical', confidence: 1.0000, tier: 5, method: 'ml' };
+            } else {
+              return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+            }
+          } else {
+            return { mode: 'lexical', confidence: 1.0000, tier: 5, method: 'ml' };
+          }
+        }
+      } else {
+        if (features[2] /* startsWithUppercase */ <= 0.500000) {
+          return { mode: 'lexical', confidence: 1.0000, tier: 5, method: 'ml' };
+        } else {
+          return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+        }
+      }
+    } else {
+      if (features[0] /* hasCamelBoundary */ <= 0.500000) {
+        if (features[10] /* avgTokenLength */ <= 7.500000) {
+          if (features[10] /* avgTokenLength */ <= 5.000000) {
+            return { mode: 'hybrid', confidence: 0.6000, tier: 5, method: 'ml' };
+          } else {
+            if (features[10] /* avgTokenLength */ <= 6.500000) {
+              return { mode: 'semantic', confidence: 0.6667, tier: 5, method: 'ml' };
+            } else {
+              return { mode: 'semantic', confidence: 0.7500, tier: 5, method: 'ml' };
+            }
+          }
+        } else {
+          return { mode: 'semantic', confidence: 1.0000, tier: 5, method: 'ml' };
+        }
+      } else {
+        return { mode: 'hybrid', confidence: 1.0000, tier: 5, method: 'ml' };
+      }
+    }
+  }
+}
+
+/**
+ * ML confidence threshold for accepting ML routing.
+ * Below this, fall back to hybrid mode.
+ */
+export const ML_CONFIDENCE_THRESHOLD = 0.7;
+
+/**
+ * Route query end-to-end: extract features and route.
+ * @param {string} query - The query to route
+ * @returns {{mode: string, confidence: number, tier: number, method: string}}
+ */
+export function routeWithML(query) {
+  const features = extractMLFeatures(query);
+  const result = routeQueryML(features);
+
+  // Apply confidence threshold
+  if (result.confidence < ML_CONFIDENCE_THRESHOLD) {
+    return { mode: 'hybrid', confidence: result.confidence, tier: 6, method: 'ml_fallback' };
+  }
+
+  return result;
+}
+
+export default { extractMLFeatures, routeQueryML, routeWithML, ML_CONFIDENCE_THRESHOLD };

package/core/query/query-router.js

@@ -0,0 +1,213 @@
+/**
+ * Query Router - CatBoost WASM (Production)
+ *
+ * Single high-performance router using compiled CatBoost model in WebAssembly.
+ *
+ * Performance:
+ *   - Latency: ~10μs per query (22x faster than JS)
+ *   - Size: 225KB WASM (4.5x smaller than 1MB JS)
+ *   - Accuracy: 100% match rate with reference implementation
+ *   - Throughput: ~100k queries/sec
+ *
+ * The WASM module includes:
+ *   - CatBoost model (499 trees, depth 4)
+ *   - Feature extraction (50 features)
+ *   - Reject option for uncertainty handling
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { createRequire } from 'module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** Maximum query length to prevent DoS attacks */
+const MAX_QUERY_LENGTH = 100000; // 100KB
+
+// =============================================================================
+// WASM MODULE LOADING
+// =============================================================================
+
+let wasmModule = null;
+let wasmLoadError = null;
+
+/**
+ * Load the WASM module synchronously on first use.
+ * The WASM file is loaded via require() for Node.js compatibility.
+ */
+function loadWasm() {
+  if (wasmModule) return wasmModule;
+  if (wasmLoadError) throw wasmLoadError;
+
+  try {
+    // Use createRequire for ES module compatibility with CommonJS WASM glue
+    const require = createRequire(import.meta.url);
+    const wasmPath = join(__dirname, '..', '..', 'crates', 'wasm-router', 'pkg', 'query_router_wasm.js');
+    wasmModule = require(wasmPath);
+    return wasmModule;
+  } catch (err) {
+    wasmLoadError = new Error(`Failed to load WASM router: ${err.message}`);
+    throw wasmLoadError;
+  }
+}
+
+// =============================================================================
+// QUERY ROUTER CLASS
+// =============================================================================
+
+export class QueryRouter {
+  constructor(options = {}) {
+    this.wasm = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Ensure WASM module is loaded.
+   */
+  ensureLoaded() {
+    if (!this.wasm) {
+      this.wasm = loadWasm();
+      this.initialized = true;
+    }
+    return this.wasm;
+  }
+
+  /**
+   * Route a query to the optimal search path.
+   *
+   * Pipeline:
+   *   1. Input validation - Handles null, undefined, empty, too-long queries
+   *   2. File path check (~0.1μs) - Fast path for file extensions
+   *   3. WASM CatBoost ML (~10μs) - 3-class routing (lexical/semantic/hybrid)
+   *
+   * Structural mode is opt-in only (explicit --structural flag).
+   *
+   * @param {string} query - The search query
+   * @returns {{mode: string, confidence: number, method: string, routingLatency_us: number}}
+   */
+  route(query) {
+    const start = performance.now();
+
+    // === INPUT VALIDATION ===
+    // Handle null, undefined, and non-string inputs
+    if (query == null || typeof query !== 'string') {
+      return {
+        mode: 'hybrid',
+        confidence: 0,
+        method: 'invalid_input',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+        error: 'Query must be a non-null string',
+      };
+    }
+
+    // Handle queries exceeding maximum length (DoS protection)
+    if (query.length > MAX_QUERY_LENGTH) {
+      return {
+        mode: 'hybrid',
+        confidence: 0,
+        method: 'query_too_long',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+        error: `Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`,
+      };
+    }
+
+    const trimmed = query.trim();
+
+    // Handle empty or whitespace-only queries
+    if (trimmed.length === 0) {
+      return {
+        mode: 'hybrid',
+        confidence: 0,
+        method: 'empty_query',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+      };
+    }
+
+    // === FILE PATH CHECK (~0.1μs) ===
+    // File extensions and paths are always lexical
+    if (/\.(java|js|jsx|ts|tsx|py|go|rs|kt|swift|rb|php|c|cpp|h|proto|json|xml|yml|yaml|md|sql)$/i.test(trimmed) ||
+        /[/\\]/.test(trimmed)) {
+      return {
+        mode: 'lexical',
+        confidence: 0.95,
+        method: 'file_pattern',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+      };
+    }
+
+    // === WASM CATBOOST ML (~10μs) ===
+    let result = null;
+    try {
+      const wasm = this.ensureLoaded();
+      result = wasm.route_query(trimmed);
+
+      const mode = result.mode_str.toLowerCase();
+      const confidence = result.confidence;
+      const rejected = result.rejected;
+
+      return {
+        mode: rejected ? 'hybrid' : mode,
+        confidence,
+        method: rejected ? 'wasm_rejected' : 'wasm_catboost',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+      };
+    } catch (err) {
+      // Fallback to hybrid if WASM fails
+      console.error(`[QueryRouter] WASM error: ${err.message}`);
+      return {
+        mode: 'hybrid',
+        confidence: 0.5,
+        method: 'fallback_error',
+        routingLatency_us: Math.round((performance.now() - start) * 1000),
+      };
+    } finally {
+      // Always free WASM result to prevent memory leak
+      if (result && typeof result.free === 'function') {
+        try {
+          result.free();
+        } catch {
+          // Ignore free errors (may already be freed or invalid)
+        }
+      }
+    }
+  }
+}
+
+// =============================================================================
+// CONVENIENCE EXPORTS
+// =============================================================================
+
+// Default singleton instance
+const defaultRouter = new QueryRouter();
+
+/**
+ * Route a query using the default router.
+ * @param {string} query - The search query
+ * @returns {{mode: string, confidence: number, method: string, routingLatency_us: number}}
+ */
+export function routeQuery(query) {
+  return defaultRouter.route(query);
+}
+
+/**
+ * Extract features from a query (for debugging/testing).
+ * @param {string} query - The query to extract features from
+ * @returns {Float32Array|null} - Feature vector, or null for invalid input
+ */
+export function extractFeatures(query) {
+  // Input validation
+  if (query == null || typeof query !== 'string') {
+    return null;
+  }
+  if (query.length > MAX_QUERY_LENGTH) {
+    return null;
+  }
+  const wasm = loadWasm();
+  return wasm.extract_features_js(query);
+}
+
+export default QueryRouter;