@dotdo/postgres 0.1.0

package/src/routing/adaptive-router.ts

@@ -0,0 +1,845 @@
+/**
+ * Adaptive Routing (learn from history)
+ *
+ * Task: postgres-d6g.10
+ *
+ * Purpose: Learn from execution history to improve routing decisions.
+ * Uses actual CPU time measurements to adjust complexity estimates.
+ */
+
+import {
+  QueryComplexityEstimator,
+  QueryComplexityFactors,
+  ConfidenceLevel,
+} from './query-complexity-estimator'
+
+export type RuntimeTarget = 'worker' | 'durable-object'
+export type RoutingStrategy = 'primary' | 'alternative'
+
+export interface ExecutionOutcome {
+  sql: string
+  sqlHash: string
+  predictedCpuTimeMs: number
+  actualCpuTimeMs: number
+  runtime: RuntimeTarget
+  timestamp: number
+  factors?: Partial<QueryComplexityFactors>
+  strategy?: RoutingStrategy
+}
+
+export interface PredictionResult {
+  estimatedMs: number
+  confidence: ConfidenceLevel
+  source: 'history' | 'model' | 'estimator'
+}
+
+export interface RoutingDecision {
+  target: RuntimeTarget
+  estimatedMs: number
+  confidence: ConfidenceLevel
+  strategy: RoutingStrategy
+  reason: string
+}
+
+export interface PredictionAccuracy {
+  meanAbsoluteError: number
+  meanAbsolutePercentageError: number
+  predictionCount: number
+}
+
+export interface StrategyStats {
+  avgPredictionError: number
+  avgActualCpuTimeMs: number
+  correctRoutingPercent: number
+  sampleCount: number
+}
+
+export interface StrategyComparison {
+  primary: StrategyStats
+  alternative: StrategyStats
+  winner: RoutingStrategy | null
+}
+
+export interface PerformanceAnomaly {
+  timestamp: number
+  actualCpuTimeMs: number
+  expectedCpuTimeMs: number
+  deviationPercent: number
+}
+
+export interface LearningModel {
+  queryModels: Record<string, { avgCpuTimeMs: number; sampleCount: number; variance: number }>
+  adjustedWeights: ComplexityWeights
+  strategyOutcomes: Record<RoutingStrategy, ExecutionOutcome[]>
+  history: Record<string, ExecutionOutcome[]>
+  version: string
+}
+
+export interface ComplexityWeights {
+  baseQuery: number
+  perJoin: number
+  perSubquery: number
+  perUnion: number
+  perCte: number
+  perWindowFunction: number
+  aggregation: number
+  groupBy: number
+  having: number
+  orderBy: number
+  distinct: number
+  noLimit: number
+  fullTableScan: number
+  largeTableMultiplier: number
+  transaction: number
+}
+
+export interface SeedData {
+  sqlHash: string
+  avgCpuTimeMs: number
+  sampleCount: number
+}
+
+/**
+ * Configuration options for the AdaptiveRouter.
+ *
+ * The AdaptiveRouter learns from query execution history to improve routing
+ * decisions over time. It routes queries to either Workers (fast queries) or
+ * Durable Objects (complex queries) based on predicted CPU time.
+ *
+ * @example
+ * ```typescript
+ * const router = new AdaptiveRouter({
+ *   cpuTimeThresholdMs: 30,  // Lower threshold for faster routing
+ *   complexityWeights: {
+ *     // Custom weights tuned for your workload
+ *     baseQuery: 1,
+ *     perJoin: 20,       // Higher if your joins are expensive
+ *     perSubquery: 25,
+ *     perWindowFunction: 30,
+ *     // ... other weights
+ *   },
+ *   enableABTesting: true,
+ * })
+ * ```
+ */
+export interface AdaptiveConfig {
+  /** CPU time threshold for routing decision (default: 50ms) */
+  cpuTimeThresholdMs?: number
+
+  /** Enable A/B testing of routing strategies */
+  enableABTesting?: boolean
+
+  /** Ratio of traffic to send to alternative strategy (0-1) */
+  abTestingRatio?: number
+
+  /** Minimum samples before auto-selecting strategy */
+  minSamplesForDecision?: number
+
+  /** Conservative routing for low confidence predictions */
+  conservativeThreshold?: ConfidenceLevel
+
+  /** Half-life for time-based decay (ms) */
+  decayHalfLifeMs?: number
+
+  /**
+   * Partial complexity weight overrides. These values are merged with
+   * DEFAULT_WEIGHTS, allowing you to adjust specific weights while
+   * keeping defaults for others.
+   *
+   * @example
+   * ```typescript
+   * initialWeights: {
+   *   perJoin: 20,      // Only override JOIN weight
+   *   aggregation: 15,  // And aggregation weight
+   * }
+   * ```
+   *
+   * @see ComplexityWeights for available weight fields
+   * @see complexityWeights for full replacement (no merging)
+   */
+  initialWeights?: Partial<ComplexityWeights>
+
+  /**
+   * Complete complexity weights replacement. When provided, these weights
+   * fully replace the defaults (no merging with DEFAULT_WEIGHTS).
+   *
+   * Use this when you have a complete set of weights tuned for your
+   * specific workload, or when exporting/importing router configurations.
+   *
+   * @example
+   * ```typescript
+   * complexityWeights: {
+   *   baseQuery: 1,
+   *   perJoin: 18,
+   *   perSubquery: 22,
+   *   perUnion: 12,
+   *   perCte: 16,
+   *   perWindowFunction: 28,
+   *   aggregation: 12,
+   *   groupBy: 9,
+   *   having: 6,
+   *   orderBy: 9,
+   *   distinct: 11,
+   *   noLimit: 17,
+   *   fullTableScan: 22,
+   *   largeTableMultiplier: 0.00001,
+   *   transaction: 6,
+   * }
+   * ```
+   *
+   * @see ComplexityWeights for field descriptions
+   * @see initialWeights for partial overrides (merged with defaults)
+   */
+  complexityWeights?: ComplexityWeights
+
+  /**
+   * Seed data to bootstrap the router's query models on cold start.
+   *
+   * Provide pre-computed query statistics to avoid the learning period
+   * for known query patterns. Each entry associates a SQL hash with its
+   * expected CPU time and sample count, allowing the router to make
+   * informed routing decisions immediately.
+   *
+   * @example
+   * ```typescript
+   * seedData: [
+   *   { sqlHash: 'sql-abc123', avgCpuTimeMs: 25, sampleCount: 100 },
+   *   { sqlHash: 'sql-def456', avgCpuTimeMs: 75, sampleCount: 50 },
+   * ]
+   * ```
+   *
+   * @see SeedData for the structure of seed entries
+   */
+  seedData?: SeedData[]
+
+  /** Minimum samples to create query-specific model */
+  minSamplesForQueryModel?: number
+
+  /** Maximum number of unique query hashes to track in history (default: 1000) */
+  maxHistoryEntries?: number
+
+  /** Maximum age for history entries in milliseconds (default: 3600000 = 1 hour) */
+  maxHistoryAgeMs?: number
+}
+
+/**
+ * Default complexity weights for SQL query routing decisions.
+ *
+ * These weights represent **relative complexity units** that estimate CPU time
+ * overhead for different SQL operations. They are used by the AdaptiveRouter
+ * to predict query execution time and route queries to the appropriate runtime
+ * (Worker for fast queries, Durable Object for complex queries).
+ *
+ * ## Weight Derivation
+ *
+ * These values were derived from:
+ * 1. **PostgreSQL documentation** - Understanding relative costs of operations
+ *    (e.g., nested loop joins vs hash joins, sequential vs index scans)
+ * 2. **Empirical testing** - Benchmarking common query patterns on PGLite/WASM
+ *    in Cloudflare Workers to measure actual CPU time overhead
+ * 3. **Industry best practices** - Referencing query cost models from PostgreSQL's
+ *    EXPLAIN ANALYZE and similar database query planners
+ *
+ * ## How Weights Affect Routing
+ *
+ * The total complexity score is calculated as:
+ *   score = baseQuery + (joinCount * perJoin) + (subqueryCount * perSubquery) + ...
+ *
+ * This score is then used to estimate CPU time in milliseconds. Queries with
+ * estimated CPU time below `cpuTimeThresholdMs` (default: 50ms) are routed to
+ * Workers; those above are routed to Durable Objects.
+ *
+ * ## Weight Categories
+ *
+ * - **Structural costs** (perJoin, perSubquery, perUnion, perCte): Increase
+ *   linearly with each occurrence. Joins and subqueries are expensive due to
+ *   additional table scans and nested loop processing.
+ *
+ * - **Operation costs** (aggregation, groupBy, having, orderBy, distinct):
+ *   Fixed overhead for using these operations. GROUP BY and ORDER BY require
+ *   sorting; aggregations need accumulator state.
+ *
+ * - **Scan costs** (noLimit, fullTableScan, largeTableMultiplier): Penalize
+ *   queries that may process large result sets. The largeTableMultiplier
+ *   scales with estimated row count (e.g., 100K rows * 0.00001 = 1 unit).
+ *
+ * - **Compute costs** (perWindowFunction): Window functions are particularly
+ *   expensive as they require buffering and sorting result sets.
+ *
+ * ## Adaptive Learning
+ *
+ * These defaults serve as initial values. The AdaptiveRouter adjusts weights
+ * based on actual execution outcomes using online learning. Over time, weights
+ * converge to values that minimize prediction error for your specific workload.
+ *
+ * @see AdaptiveConfig.initialWeights - Override these defaults at construction
+ * @see AdaptiveConfig.complexityWeights - Fully replace the weight configuration
+ */
+export const DEFAULT_WEIGHTS: ComplexityWeights = {
+  /** Base cost for any query (minimum complexity floor) */
+  baseQuery: 1,
+
+  /**
+   * Cost per JOIN clause. JOINs multiply row processing and require
+   * matching keys across tables. Nested loops are O(n*m) worst case.
+   */
+  perJoin: 15,
+
+  /**
+   * Cost per subquery. Subqueries execute as separate query plans and
+   * may be re-evaluated for each outer row (correlated subqueries).
+   */
+  perSubquery: 20,
+
+  /**
+   * Cost per UNION/INTERSECT/EXCEPT. Requires executing multiple queries
+   * and combining results (with deduplication for UNION/INTERSECT).
+   */
+  perUnion: 10,
+
+  /**
+   * Cost per Common Table Expression (CTE/WITH clause). CTEs materialize
+   * intermediate results, adding memory overhead.
+   */
+  perCte: 15,
+
+  /**
+   * Cost per window function (OVER clause). Window functions buffer the
+   * entire partition, sort by ORDER BY, and compute running aggregates.
+   * Among the most expensive operations in SQL.
+   */
+  perWindowFunction: 25,
+
+  /**
+   * Cost for aggregate functions (COUNT, SUM, AVG, MIN, MAX, etc.).
+   * Requires maintaining accumulator state across all rows.
+   */
+  aggregation: 10,
+
+  /**
+   * Cost for GROUP BY clause. Requires sorting or hashing rows by
+   * grouping keys, then aggregating within each group.
+   */
+  groupBy: 8,
+
+  /**
+   * Cost for HAVING clause. Evaluated after GROUP BY, filtering
+   * aggregate results. Minor overhead compared to GROUP BY itself.
+   */
+  having: 5,
+
+  /**
+   * Cost for ORDER BY clause. Requires sorting the result set,
+   * which is O(n log n) in the number of rows.
+   */
+  orderBy: 8,
+
+  /**
+   * Cost for DISTINCT keyword. Requires sorting or hashing to
+   * eliminate duplicates from the result set.
+   */
+  distinct: 10,
+
+  /**
+   * Penalty for queries without LIMIT clause. Unbounded result sets
+   * can return arbitrarily large amounts of data.
+   */
+  noLimit: 15,
+
+  /**
+   * Penalty for suspected full table scans (queries without WHERE
+   * clauses or using non-indexed columns). Processes every row.
+   */
+  fullTableScan: 20,
+
+  /**
+   * Multiplier applied to estimated table size. Allows complexity to
+   * scale with data volume. Value of 0.00001 means 100K rows = 1 unit.
+   */
+  largeTableMultiplier: 0.00001,
+
+  /**
+   * Overhead for transaction boundaries (BEGIN/COMMIT/ROLLBACK).
+   * Minor but non-zero cost for transaction state management.
+   */
+  transaction: 5,
+}
+
+export class AdaptiveRouter {
+  private config: Required<AdaptiveConfig>
+  private estimator: QueryComplexityEstimator
+  private history: Map<string, ExecutionOutcome[]> = new Map()
+  private queryModels: Map<string, { avgCpuTimeMs: number; sampleCount: number; variance: number }> = new Map()
+  private adjustedWeights: ComplexityWeights
+  private strategyOutcomes: Map<RoutingStrategy, ExecutionOutcome[]> = new Map([
+    ['primary', []],
+    ['alternative', []],
+  ])
+  private selectedStrategy: RoutingStrategy | null = null
+  /** Track last access time for each query hash (for LRU eviction) */
+  private lastAccessTime: Map<string, number> = new Map()
+
+  constructor(config: AdaptiveConfig = {}) {
+    // Check if complexityWeights was explicitly provided (not defaulted)
+    const hasExplicitComplexityWeights = config.complexityWeights !== undefined
+
+    this.config = {
+      cpuTimeThresholdMs: config.cpuTimeThresholdMs ?? 50,
+      enableABTesting: config.enableABTesting ?? false,
+      abTestingRatio: config.abTestingRatio ?? 0.1,
+      minSamplesForDecision: config.minSamplesForDecision ?? 100,
+      conservativeThreshold: config.conservativeThreshold ?? 'low',
+      decayHalfLifeMs: config.decayHalfLifeMs ?? 86400000, // 1 day default
+      initialWeights: config.initialWeights ?? {},
+      complexityWeights: config.complexityWeights ?? DEFAULT_WEIGHTS,
+      seedData: config.seedData ?? [],
+      minSamplesForQueryModel: config.minSamplesForQueryModel ?? 10,
+      maxHistoryEntries: config.maxHistoryEntries ?? 1000,
+      maxHistoryAgeMs: config.maxHistoryAgeMs ?? 3600000, // 1 hour default
+    }
+
+    // Initialize weights: complexityWeights takes precedence (full replacement),
+    // otherwise merge initialWeights with defaults
+    if (hasExplicitComplexityWeights) {
+      this.adjustedWeights = { ...this.config.complexityWeights }
+    } else {
+      this.adjustedWeights = { ...DEFAULT_WEIGHTS, ...this.config.initialWeights }
+    }
+
+    this.estimator = new QueryComplexityEstimator({
+      cpuTimeThresholdMs: this.config.cpuTimeThresholdMs,
+    })
+
+    // Initialize with seed data
+    for (const seed of this.config.seedData) {
+      this.queryModels.set(seed.sqlHash, {
+        avgCpuTimeMs: seed.avgCpuTimeMs,
+        sampleCount: seed.sampleCount,
+        variance: 0,
+      })
+    }
+  }
+
+  async recordOutcome(outcome: ExecutionOutcome): Promise<void> {
+    const { sqlHash, strategy } = outcome
+
+    // Update last access time for LRU tracking (use outcome timestamp for consistency)
+    this.lastAccessTime.set(sqlHash, outcome.timestamp)
+
+    // Enforce maxHistoryEntries limit via LRU eviction
+    if (!this.history.has(sqlHash) && this.history.size >= this.config.maxHistoryEntries) {
+      this.evictLRUEntry()
+    }
+
+    // Add to history
+    if (!this.history.has(sqlHash)) {
+      this.history.set(sqlHash, [])
+    }
+    this.history.get(sqlHash)!.push(outcome)
+
+    // Update query model
+    this.updateQueryModel(sqlHash, outcome.actualCpuTimeMs)
+
+    // Update factor weights
+    if (outcome.factors) {
+      this.updateWeights(outcome)
+    }
+
+    // Track strategy outcomes
+    if (strategy) {
+      this.strategyOutcomes.get(strategy)!.push(outcome)
+      this.checkStrategySelection()
+    }
+  }
+
+  /**
+   * Evict the least recently used entry from history
+   */
+  private evictLRUEntry(): void {
+    let oldestHash: string | null = null
+    let oldestTime = Infinity
+
+    for (const [hash, time] of this.lastAccessTime.entries()) {
+      if (time < oldestTime && this.history.has(hash)) {
+        oldestTime = time
+        oldestHash = hash
+      }
+    }
+
+    if (oldestHash) {
+      this.history.delete(oldestHash)
+      this.lastAccessTime.delete(oldestHash)
+      // Also clean up the query model for evicted entries
+      this.queryModels.delete(oldestHash)
+    }
+  }
+
+  private updateQueryModel(sqlHash: string, actualCpuTimeMs: number): void {
+    const existing = this.queryModels.get(sqlHash)
+
+    if (!existing) {
+      this.queryModels.set(sqlHash, {
+        avgCpuTimeMs: actualCpuTimeMs,
+        sampleCount: 1,
+        variance: 0,
+      })
+    } else {
+      const n = existing.sampleCount
+      const oldMean = existing.avgCpuTimeMs
+      const newMean = oldMean + (actualCpuTimeMs - oldMean) / (n + 1)
+
+      // Welford's online algorithm for variance
+      const delta = actualCpuTimeMs - oldMean
+      const delta2 = actualCpuTimeMs - newMean
+      const newVariance = (existing.variance * n + delta * delta2) / (n + 1)
+
+      this.queryModels.set(sqlHash, {
+        avgCpuTimeMs: newMean,
+        sampleCount: n + 1,
+        variance: newVariance,
+      })
+    }
+  }
+
+  private updateWeights(outcome: ExecutionOutcome): void {
+    const error = outcome.actualCpuTimeMs - outcome.predictedCpuTimeMs
+    const learningRate = 0.1
+
+    if (outcome.factors?.joinCount && outcome.factors.joinCount > 0) {
+      const adjustment = (error / outcome.factors.joinCount) * learningRate
+      this.adjustedWeights.perJoin = Math.max(1, this.adjustedWeights.perJoin + adjustment)
+    }
+
+    if (outcome.factors?.hasAggregation) {
+      const adjustment = error * learningRate
+      this.adjustedWeights.aggregation = Math.max(1, this.adjustedWeights.aggregation + adjustment)
+    }
+
+    if (outcome.factors?.subqueryCount && outcome.factors.subqueryCount > 0) {
+      const adjustment = (error / outcome.factors.subqueryCount) * learningRate
+      this.adjustedWeights.perSubquery = Math.max(1, this.adjustedWeights.perSubquery + adjustment)
+    }
+
+    if (outcome.factors?.hasGroupBy) {
+      const adjustment = error * learningRate
+      this.adjustedWeights.groupBy = Math.max(1, this.adjustedWeights.groupBy + adjustment)
+    }
+  }
+
+  private checkStrategySelection(): void {
+    if (this.selectedStrategy) return
+
+    const primary = this.strategyOutcomes.get('primary')!
+    const alternative = this.strategyOutcomes.get('alternative')!
+
+    if (primary.length >= this.config.minSamplesForDecision &&
+      alternative.length >= this.config.minSamplesForDecision) {
+      const primaryStats = this.calculateStrategyStats(primary)
+      const alternativeStats = this.calculateStrategyStats(alternative)
+
+      // Select strategy with lower average prediction error
+      if (primaryStats.avgPredictionError < alternativeStats.avgPredictionError) {
+        this.selectedStrategy = 'primary'
+      } else {
+        this.selectedStrategy = 'alternative'
+      }
+    }
+  }
+
+  private calculateStrategyStats(outcomes: ExecutionOutcome[]): StrategyStats {
+    if (outcomes.length === 0) {
+      return {
+        avgPredictionError: Infinity,
+        avgActualCpuTimeMs: 0,
+        correctRoutingPercent: 0,
+        sampleCount: 0,
+      }
+    }
+
+    const totalError = outcomes.reduce((sum, o) => sum + Math.abs(o.actualCpuTimeMs - o.predictedCpuTimeMs), 0)
+    const totalActual = outcomes.reduce((sum, o) => sum + o.actualCpuTimeMs, 0)
+    const correctRouting = outcomes.filter(o => {
+      const shouldBeWorker = o.actualCpuTimeMs < this.config.cpuTimeThresholdMs
+      return (o.runtime === 'worker') === shouldBeWorker
+    }).length
+
+    return {
+      avgPredictionError: totalError / outcomes.length,
+      avgActualCpuTimeMs: totalActual / outcomes.length,
+      correctRoutingPercent: (correctRouting / outcomes.length) * 100,
+      sampleCount: outcomes.length,
+    }
+  }
+
+  getHistory(sqlHash: string): ExecutionOutcome[] {
+    return this.history.get(sqlHash) ?? []
+  }
+
+  /**
+   * Get the number of unique query hashes in history
+   */
+  getHistorySize(): number {
+    return this.history.size
+  }
+
+  /**
+   * Get the current configuration
+   */
+  getConfig(): Required<AdaptiveConfig> {
+    return { ...this.config }
+  }
+
+  /**
+   * Get the default complexity weights.
+   *
+   * Returns a copy of the default weight values used when no custom
+   * weights are provided. Useful for inspecting defaults or creating
+   * modified weight configurations based on defaults.
+   *
+   * @example
+   * ```typescript
+   * const defaults = AdaptiveRouter.getDefaultWeights()
+   * const customWeights = {
+   *   ...defaults,
+   *   perJoin: defaults.perJoin * 1.5,  // 50% higher JOIN cost
+   * }
+   * const router = new AdaptiveRouter({ complexityWeights: customWeights })
+   * ```
+   */
+  static getDefaultWeights(): ComplexityWeights {
+    return { ...DEFAULT_WEIGHTS }
+  }
+
+  /**
+   * Prune entries older than maxHistoryAgeMs
+   */
+  pruneOldEntries(): void {
+    const now = Date.now()
+    const maxAge = this.config.maxHistoryAgeMs
+
+    for (const [sqlHash, outcomes] of this.history.entries()) {
+      // Filter out old outcomes
+      const recentOutcomes = outcomes.filter(o => (now - o.timestamp) < maxAge)
+
+      if (recentOutcomes.length === 0) {
+        // Remove entire entry if all outcomes are old
+        this.history.delete(sqlHash)
+        this.lastAccessTime.delete(sqlHash)
+        this.queryModels.delete(sqlHash)
+      } else if (recentOutcomes.length < outcomes.length) {
+        // Update with only recent outcomes
+        this.history.set(sqlHash, recentOutcomes)
+      }
+    }
+  }
+
+  getPredictionAccuracy(): PredictionAccuracy {
+    let totalAbsoluteError = 0
+    let totalPercentageError = 0
+    let count = 0
+
+    for (const outcomes of this.history.values()) {
+      for (const outcome of outcomes) {
+        const absError = Math.abs(outcome.actualCpuTimeMs - outcome.predictedCpuTimeMs)
+        totalAbsoluteError += absError
+        if (outcome.actualCpuTimeMs > 0) {
+          totalPercentageError += (absError / outcome.actualCpuTimeMs) * 100
+        }
+        count++
+      }
+    }
+
+    return {
+      meanAbsoluteError: count > 0 ? totalAbsoluteError / count : 0,
+      meanAbsolutePercentageError: count > 0 ? totalPercentageError / count : 0,
+      predictionCount: count,
+    }
+  }
+
+  async predictCpuTime(sql: string, sqlHash: string): Promise<PredictionResult> {
+    const queryModel = this.queryModels.get(sqlHash)
+
+    // Use query-specific model if available with enough samples
+    if (queryModel && queryModel.sampleCount >= this.config.minSamplesForQueryModel) {
+      const stdDev = Math.sqrt(queryModel.variance)
+      const coefficientOfVariation = queryModel.avgCpuTimeMs > 0 ? stdDev / queryModel.avgCpuTimeMs : 1
+
+      let confidence: ConfidenceLevel = 'high'
+      if (coefficientOfVariation > 0.3 || queryModel.sampleCount < 20) {
+        confidence = 'medium'
+      }
+      if (coefficientOfVariation > 0.5 || queryModel.sampleCount < 10) {
+        confidence = 'low'
+      }
+
+      return {
+        estimatedMs: queryModel.avgCpuTimeMs,
+        confidence,
+        source: 'history',
+      }
+    }
+
+    // Use history with time-based decay
+    const history = this.getHistory(sqlHash)
+    if (history.length > 0) {
+      const now = Date.now()
+      let weightedSum = 0
+      let totalWeight = 0
+
+      for (const outcome of history) {
+        const age = now - outcome.timestamp
+        const weight = Math.pow(0.5, age / this.config.decayHalfLifeMs)
+        weightedSum += outcome.actualCpuTimeMs * weight
+        totalWeight += weight
+      }
+
+      if (totalWeight > 0) {
+        return {
+          estimatedMs: weightedSum / totalWeight,
+          confidence: history.length >= 10 ? 'high' : history.length >= 3 ? 'medium' : 'low',
+          source: 'history',
+        }
+      }
+    }
+
+    // Fall back to complexity estimator
+    const estimate = this.estimator.estimate(sql)
+    return {
+      estimatedMs: estimate.estimatedMs,
+      confidence: estimate.confidence,
+      source: 'estimator',
+    }
+  }
+
+  hasQueryModel(sqlHash: string): boolean {
+    const model = this.queryModels.get(sqlHash)
+    return model !== undefined && model.sampleCount >= this.config.minSamplesForQueryModel
+  }
+
+  getAdjustedWeights(): ComplexityWeights {
+    return { ...this.adjustedWeights }
+  }
+
+  async route(sql: string, sqlHash?: string): Promise<RoutingDecision> {
+    const hash = sqlHash ?? this.hashSql(sql)
+    const prediction = await this.predictCpuTime(sql, hash)
+
+    // Determine strategy for A/B testing
+    let strategy: RoutingStrategy = 'primary'
+    if (this.config.enableABTesting && !this.selectedStrategy) {
+      strategy = Math.random() < this.config.abTestingRatio ? 'alternative' : 'primary'
+    } else if (this.selectedStrategy) {
+      strategy = this.selectedStrategy
+    }
+
+    // Determine target based on prediction and confidence
+    let target: RuntimeTarget
+    if (prediction.confidence === this.config.conservativeThreshold) {
+      // Conservative: prefer DO for uncertain queries
+      target = prediction.estimatedMs >= this.config.cpuTimeThresholdMs * 0.7
+        ? 'durable-object' : 'worker'
+    } else {
+      target = prediction.estimatedMs >= this.config.cpuTimeThresholdMs
+        ? 'durable-object' : 'worker'
+    }
+
+    const reason = prediction.estimatedMs >= this.config.cpuTimeThresholdMs
+      ? `complex query (estimated ${prediction.estimatedMs.toFixed(1)}ms from ${prediction.source})`
+      : `fast query (estimated ${prediction.estimatedMs.toFixed(1)}ms from ${prediction.source})`
+
+    return {
+      target,
+      estimatedMs: prediction.estimatedMs,
+      confidence: prediction.confidence,
+      strategy,
+      reason,
+    }
+  }
+
+  private hashSql(sql: string): string {
+    // Simple hash function
+    let hash = 0
+    for (let i = 0; i < sql.length; i++) {
+      const char = sql.charCodeAt(i)
+      hash = ((hash << 5) - hash) + char
+      hash = hash & hash
+    }
+    return `sql-${Math.abs(hash).toString(36)}`
+  }
+
+  compareStrategies(): StrategyComparison {
+    const primary = this.strategyOutcomes.get('primary')!
+    const alternative = this.strategyOutcomes.get('alternative')!
+
+    const primaryStats = this.calculateStrategyStats(primary)
+    const alternativeStats = this.calculateStrategyStats(alternative)
+
+    let winner: RoutingStrategy | null = null
+    if (primary.length >= this.config.minSamplesForDecision &&
+      alternative.length >= this.config.minSamplesForDecision) {
+      winner = primaryStats.avgPredictionError < alternativeStats.avgPredictionError
+        ? 'primary' : 'alternative'
+    }
+
+    return {
+      primary: primaryStats,
+      alternative: alternativeStats,
+      winner,
+    }
+  }
+
+  getSelectedStrategy(): RoutingStrategy | null {
+    return this.selectedStrategy
+  }
+
+  detectPerformanceAnomalies(sqlHash: string): PerformanceAnomaly[] {
+    const history = this.getHistory(sqlHash)
+    if (history.length < 5) return []
+
+    // Calculate mean and std dev
+    const values = history.map(h => h.actualCpuTimeMs)
+    const mean = values.reduce((a, b) => a + b, 0) / values.length
+    const variance = values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length
+    const stdDev = Math.sqrt(variance)
+
+    const anomalies: PerformanceAnomaly[] = []
+    const threshold = 3 // 3 standard deviations
+
+    for (const outcome of history) {
+      const deviation = Math.abs(outcome.actualCpuTimeMs - mean)
+      if (deviation > threshold * stdDev) {
+        anomalies.push({
+          timestamp: outcome.timestamp,
+          actualCpuTimeMs: outcome.actualCpuTimeMs,
+          expectedCpuTimeMs: mean,
+          deviationPercent: ((outcome.actualCpuTimeMs - mean) / mean) * 100,
+        })
+      }
+    }
+
+    return anomalies
+  }
+
+  exportModel(): string {
+    const model: LearningModel = {
+      queryModels: Object.fromEntries(this.queryModels),
+      adjustedWeights: this.adjustedWeights,
+      strategyOutcomes: {
+        primary: this.strategyOutcomes.get('primary') || [],
+        alternative: this.strategyOutcomes.get('alternative') || [],
+      },
+      history: Object.fromEntries(this.history),
+      version: '1.0.0',
+    }
+    return JSON.stringify(model)
+  }
+
+  importModel(modelJson: string): void {
+    const model: LearningModel = JSON.parse(modelJson)
+
+    this.queryModels = new Map(Object.entries(model.queryModels))
+    this.adjustedWeights = model.adjustedWeights
+    this.strategyOutcomes = new Map(Object.entries(model.strategyOutcomes) as [RoutingStrategy, ExecutionOutcome[]][])
+    this.history = new Map(Object.entries(model.history))
+  }
+}