@dotdo/postgres 0.1.0

package/src/observability/memory-metrics.ts

@@ -0,0 +1,990 @@
+/**
+ * Memory Metrics Collector
+ *
+ * Tracks WASM heap usage and memory pressure for Cloudflare Workers.
+ * Critical for monitoring within the 128MB Worker limit.
+ */
+
+import type { MetricsCollector } from './types'
+import {
+  WORKER_MEMORY_LIMIT_BYTES,
+  WASM_PAGE_SIZE_BYTES,
+  DEFAULT_WARNING_THRESHOLD_RATIO,
+  DEFAULT_CRITICAL_THRESHOLD_RATIO,
+} from '../config/memory'
+
+// ============================================================================
+// Re-exported Constants (for backward compatibility)
+// ============================================================================
+
+/** @deprecated Import from '@dotdo/postgres/config/memory' instead */
+export { WORKER_MEMORY_LIMIT_BYTES, WASM_PAGE_SIZE_BYTES }
+
+/** Default warning threshold (70% of limit) */
+export const DEFAULT_WARNING_THRESHOLD = DEFAULT_WARNING_THRESHOLD_RATIO
+
+/** Default critical threshold (90% of limit) */
+export const DEFAULT_CRITICAL_THRESHOLD = DEFAULT_CRITICAL_THRESHOLD_RATIO
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export enum MemoryPressureLevel {
+  NORMAL = 'normal',
+  WARNING = 'warning',
+  CRITICAL = 'critical',
+}
+
+export interface WasmHeapInfo {
+  size: number
+  used: number
+}
+
+export interface MemorySnapshot {
+  heapSizeBytes: number
+  heapUsedBytes: number
+  limitBytes: number
+  usageRatio: number
+  availableBytes: number
+  pressureLevel: MemoryPressureLevel
+  timestamp: number
+  /** WASM memory pages (64KB each) */
+  wasmPages: number
+  /** Utilization ratio of WASM heap (used/size) */
+  wasmUtilizationRatio: number
+  /** Ratio against Worker memory limit (used/128MB) */
+  workerLimitRatio: number
+  /** Bytes remaining before OOM (128MB - used) */
+  bytesUntilOOM: number
+}
+
+export interface MemoryHistory {
+  snapshots: MemorySnapshot[]
+  avgUsageBytes: number
+  peakUsageBytes: number
+  trend: number
+}
+
+export interface HeapGrowthRate {
+  bytesPerSecond: number
+  percentageGrowth: number
+  isGrowing: boolean
+}
+
+export interface HeapAllocationHistogram {
+  buckets: { min: number; max: number; count: number }[]
+  totalSamples: number
+}
+
+export interface OOMPrediction {
+  estimatedMs: number
+  confidence: number
+  willOOM: boolean
+}
+
+export interface MemoryVelocity {
+  bytesPerMs: number
+  accelerating: boolean
+}
+
+export interface MemoryForecast {
+  predictedBytes: number
+  confidenceInterval: { low: number; high: number }
+}
+
+export interface LeakAnalysis {
+  possibleLeak: boolean
+  growthPattern: 'monotonic' | 'sawtooth' | 'stable' | 'decreasing'
+  confidence: number
+}
+
+export interface GrowthPatternAnalysis {
+  pattern: 'monotonic' | 'sawtooth' | 'stable' | 'decreasing'
+  healthStatus: 'normal' | 'concerning' | 'critical'
+}
+
+export interface PostgresSettingsRecommendation {
+  shared_buffers: string
+  work_mem: string
+  maintenance_work_mem: string
+  temp_buffers: string
+}
+
+export interface PostgresConfigAnalysis {
+  issues: string[]
+  recommendations: PostgresSettingsRecommendation
+}
+
+export interface MemoryAlert {
+  type: 'memory_warning' | 'memory_critical' | 'memory_oom_predicted'
+  level: 'warning' | 'critical'
+  message: string
+  snapshot: MemorySnapshot
+}
+
+export interface AlertSummary {
+  totalAlerts: number
+  byLevel: { warning: number; critical: number }
+  lastAlertTime: number | null
+}
+
+export interface MemoryRecommendation {
+  action: 'none' | 'reduce_cache' | 'reduce_result_set' | 'force_gc' | 'restart_do'
+  reason: string
+  pressureLevel: MemoryPressureLevel
+  usageRatio: number
+  /** Worker-specific recommendation */
+  workerSpecific: boolean
+  /** Maximum safe result set size given current memory */
+  maxSafeResultSetBytes: number
+  /** Suggested PostgreSQL settings */
+  suggestedPgSettings: PostgresSettingsRecommendation
+}
+
+export interface MemoryBudget {
+  totalBytes: number
+  staticBytes: number
+  postgresOverheadBytes: number
+  workMemBytes: number
+  availableForQueriesBytes: number
+  maxResultSetBytes: number
+  /** Whether the budget exceeds the 128MB limit */
+  exceedsLimit: boolean
+  /** Overage in bytes if exceeds limit */
+  overageBytes: number
+}
+
+export interface MemoryMetricsConfig {
+  getWasmHeap?: () => WasmHeapInfo | null
+  warningThreshold?: number
+  criticalThreshold?: number
+  memoryLimitBytes?: number
+  onPressureChange?: (level: MemoryPressureLevel, snapshot: MemorySnapshot) => void
+  onSustainedPressure?: (level: MemoryPressureLevel, durationMs: number) => void
+  onAlert?: (alert: MemoryAlert) => void
+  sustainedPressureThreshold?: number
+  alertThresholds?: {
+    critical?: number
+    oomPrediction?: number
+  }
+  historySize?: number
+  metricsCollector?: MetricsCollector
+}
+
+export interface MemoryMetricsCollector {
+  getCurrentSnapshot(): MemorySnapshot
+  record(): MemorySnapshot
+  getHistory(): MemoryHistory
+  getPeakUsage(): number
+  getPressureLevel(): MemoryPressureLevel
+  isWarning(): boolean
+  isCritical(): boolean
+  getRecommendation(): MemoryRecommendation
+  reset(): void
+  // Extended methods
+  getHeapGrowthRate(): HeapGrowthRate
+  getFragmentationRatio(): number
+  getHeapAllocationHistogram(): HeapAllocationHistogram
+  getPressureDuration(): Record<MemoryPressureLevel, number>
+  getPressureScore(): number
+  predictTimeToOOM(): OOMPrediction
+  getMemoryVelocity(): MemoryVelocity
+  forecastMemoryUsage(msAhead: number): MemoryForecast
+  analyzeForLeaks(): LeakAnalysis
+  analyzeGrowthPattern(): GrowthPatternAnalysis
+  getPostgresSettingsRecommendation(): PostgresSettingsRecommendation
+  analyzePostgresMemoryConfig(config: Record<string, string>): PostgresConfigAnalysis
+  recordOperationMemory(operation: string, bytes: number): void
+  getMemoryBreakdownByOperation(): Record<string, number>
+  getAlertSummary(): AlertSummary
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+export class MemoryMetricsCollectorImpl implements MemoryMetricsCollector {
+  private config: Required<Omit<MemoryMetricsConfig, 'getWasmHeap' | 'onPressureChange' | 'onSustainedPressure' | 'onAlert' | 'metricsCollector' | 'alertThresholds'>> & {
+    getWasmHeap?: () => WasmHeapInfo | null
+    onPressureChange?: (level: MemoryPressureLevel, snapshot: MemorySnapshot) => void
+    onSustainedPressure?: (level: MemoryPressureLevel, durationMs: number) => void
+    onAlert?: (alert: MemoryAlert) => void
+    alertThresholds?: { critical?: number; oomPrediction?: number }
+    metricsCollector?: MetricsCollector
+  }
+  private history: MemorySnapshot[] = []
+  private peakUsage: number = 0
+  private lastPressureLevel: MemoryPressureLevel = MemoryPressureLevel.NORMAL
+  private pressureStartTimes: Record<MemoryPressureLevel, number | null> = {
+    [MemoryPressureLevel.NORMAL]: null,
+    [MemoryPressureLevel.WARNING]: null,
+    [MemoryPressureLevel.CRITICAL]: null,
+  }
+  private pressureDurations: Record<MemoryPressureLevel, number> = {
+    [MemoryPressureLevel.NORMAL]: 0,
+    [MemoryPressureLevel.WARNING]: 0,
+    [MemoryPressureLevel.CRITICAL]: 0,
+  }
+  private consecutivePressureCount: number = 0
+  private sustainedPressureEmitted: boolean = false
+  private operationMemory: Map<string, number> = new Map()
+  private alerts: MemoryAlert[] = []
+
+  constructor(config?: MemoryMetricsConfig) {
+    this.config = {
+      warningThreshold: config?.warningThreshold ?? DEFAULT_WARNING_THRESHOLD,
+      criticalThreshold: config?.criticalThreshold ?? DEFAULT_CRITICAL_THRESHOLD,
+      memoryLimitBytes: config?.memoryLimitBytes ?? WORKER_MEMORY_LIMIT_BYTES,
+      sustainedPressureThreshold: config?.sustainedPressureThreshold ?? 5,
+      historySize: config?.historySize ?? 100,
+      ...(config?.getWasmHeap !== undefined && { getWasmHeap: config.getWasmHeap }),
+      ...(config?.onPressureChange !== undefined && { onPressureChange: config.onPressureChange }),
+      ...(config?.onSustainedPressure !== undefined && { onSustainedPressure: config.onSustainedPressure }),
+      ...(config?.onAlert !== undefined && { onAlert: config.onAlert }),
+      ...(config?.alertThresholds !== undefined && { alertThresholds: config.alertThresholds }),
+      ...(config?.metricsCollector !== undefined && { metricsCollector: config.metricsCollector }),
+    }
+  }
+
+  getCurrentSnapshot(): MemorySnapshot {
+    let heapSizeBytes = 0
+    let heapUsedBytes = 0
+
+    if (this.config.getWasmHeap) {
+      const heapInfo = this.config.getWasmHeap()
+      if (heapInfo) {
+        heapSizeBytes = heapInfo.size
+        heapUsedBytes = heapInfo.used
+      }
+    }
+
+    const limitBytes = this.config.memoryLimitBytes
+    const usageRatio = limitBytes > 0 ? heapUsedBytes / limitBytes : 0
+    const availableBytes = Math.max(0, limitBytes - heapUsedBytes)
+    const wasmPages = Math.ceil(heapSizeBytes / WASM_PAGE_SIZE_BYTES)
+    const wasmUtilizationRatio = heapSizeBytes > 0 ? heapUsedBytes / heapSizeBytes : 0
+    const workerLimitRatio = heapUsedBytes / WORKER_MEMORY_LIMIT_BYTES
+
+    // Calculate bytes until OOM, accounting for system overhead (JS runtime, etc.)
+    // Reserve ~5MB for system overhead to be safe
+    const SYSTEM_OVERHEAD_BYTES = 5 * 1024 * 1024
+    const effectiveLimit = WORKER_MEMORY_LIMIT_BYTES - SYSTEM_OVERHEAD_BYTES
+    const bytesUntilOOM = Math.max(0, effectiveLimit - heapUsedBytes)
+
+    let pressureLevel = MemoryPressureLevel.NORMAL
+    if (usageRatio >= this.config.criticalThreshold) {
+      pressureLevel = MemoryPressureLevel.CRITICAL
+    } else if (usageRatio >= this.config.warningThreshold) {
+      pressureLevel = MemoryPressureLevel.WARNING
+    }
+
+    return {
+      heapSizeBytes,
+      heapUsedBytes,
+      limitBytes,
+      usageRatio,
+      availableBytes,
+      pressureLevel,
+      timestamp: Date.now(),
+      wasmPages,
+      wasmUtilizationRatio,
+      workerLimitRatio,
+      bytesUntilOOM,
+    }
+  }
+
+  record(): MemorySnapshot {
+    const snapshot = this.getCurrentSnapshot()
+    const now = Date.now()
+
+    this.history.push(snapshot)
+    if (this.history.length > this.config.historySize) {
+      this.history.shift()
+    }
+
+    if (snapshot.heapUsedBytes > this.peakUsage) {
+      this.peakUsage = snapshot.heapUsedBytes
+    }
+
+    // Track pressure level changes
+    if (snapshot.pressureLevel !== this.lastPressureLevel) {
+      // End duration for previous level
+      if (this.pressureStartTimes[this.lastPressureLevel] !== null) {
+        this.pressureDurations[this.lastPressureLevel] += now - this.pressureStartTimes[this.lastPressureLevel]!
+      }
+
+      // Start tracking new level
+      this.pressureStartTimes[snapshot.pressureLevel] = now
+
+      if (this.config.onPressureChange) {
+        this.config.onPressureChange(snapshot.pressureLevel, snapshot)
+      }
+      this.lastPressureLevel = snapshot.pressureLevel
+      this.consecutivePressureCount = 1
+      this.sustainedPressureEmitted = false
+    } else {
+      // Same pressure level - track consecutive count
+      if (snapshot.pressureLevel !== MemoryPressureLevel.NORMAL) {
+        this.consecutivePressureCount++
+
+        // Check for sustained pressure
+        if (
+          !this.sustainedPressureEmitted &&
+          this.consecutivePressureCount >= this.config.sustainedPressureThreshold &&
+          this.config.onSustainedPressure
+        ) {
+          const duration = this.pressureStartTimes[snapshot.pressureLevel]
+            ? now - this.pressureStartTimes[snapshot.pressureLevel]!
+            : 0
+          this.config.onSustainedPressure(snapshot.pressureLevel, duration)
+          this.sustainedPressureEmitted = true
+        }
+      }
+    }
+
+    // Record metrics
+    if (this.config.metricsCollector) {
+      this.config.metricsCollector.gauge('postgres.memory.heap_bytes', snapshot.heapUsedBytes)
+      this.config.metricsCollector.gauge('postgres.memory.heap_size_bytes', snapshot.heapSizeBytes)
+      this.config.metricsCollector.gauge('postgres.memory.usage_ratio', snapshot.usageRatio)
+      this.config.metricsCollector.gauge('postgres.memory.available_bytes', snapshot.availableBytes)
+
+      // Emit pressure level as a numeric gauge (0=normal, 1=warning, 2=critical)
+      const pressureLevelNum =
+        snapshot.pressureLevel === MemoryPressureLevel.CRITICAL ? 2 :
+        snapshot.pressureLevel === MemoryPressureLevel.WARNING ? 1 : 0
+      this.config.metricsCollector.gauge('postgres.memory.pressure_level', pressureLevelNum, {
+        level: snapshot.pressureLevel,
+      })
+    }
+
+    // Handle alerts
+    if (this.config.onAlert) {
+      if (snapshot.pressureLevel === MemoryPressureLevel.CRITICAL) {
+        const alert: MemoryAlert = {
+          type: 'memory_critical',
+          level: 'critical',
+          message: `Memory usage critical: ${(snapshot.usageRatio * 100).toFixed(1)}% of limit`,
+          snapshot,
+        }
+        this.alerts.push(alert)
+        this.config.onAlert(alert)
+      } else if (snapshot.pressureLevel === MemoryPressureLevel.WARNING) {
+        const alert: MemoryAlert = {
+          type: 'memory_warning',
+          level: 'warning',
+          message: `Memory usage warning: ${(snapshot.usageRatio * 100).toFixed(1)}% of limit`,
+          snapshot,
+        }
+        this.alerts.push(alert)
+        this.config.onAlert(alert)
+      }
+    }
+
+    return snapshot
+  }
+
+  getHistory(): MemoryHistory {
+    if (this.history.length === 0) {
+      return { snapshots: [], avgUsageBytes: 0, peakUsageBytes: 0, trend: 0 }
+    }
+
+    const totalUsage = this.history.reduce((sum, s) => sum + s.heapUsedBytes, 0)
+    const avgUsageBytes = totalUsage / this.history.length
+
+    let trend = 0
+    if (this.history.length >= 2) {
+      const n = this.history.length
+      let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0
+      for (let i = 0; i < n; i++) {
+        sumX += i
+        sumY += this.history[i]!.heapUsedBytes
+        sumXY += i * this.history[i]!.heapUsedBytes
+        sumX2 += i * i
+      }
+      const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX)
+      if (avgUsageBytes > 0) {
+        trend = slope / avgUsageBytes
+      }
+    }
+
+    return { snapshots: [...this.history], avgUsageBytes, peakUsageBytes: this.peakUsage, trend }
+  }
+
+  getPeakUsage(): number {
+    return this.peakUsage
+  }
+
+  getPressureLevel(): MemoryPressureLevel {
+    return this.getCurrentSnapshot().pressureLevel
+  }
+
+  isWarning(): boolean {
+    const level = this.getPressureLevel()
+    return level === MemoryPressureLevel.WARNING || level === MemoryPressureLevel.CRITICAL
+  }
+
+  isCritical(): boolean {
+    return this.getPressureLevel() === MemoryPressureLevel.CRITICAL
+  }
+
+  getRecommendation(): MemoryRecommendation {
+    const snapshot = this.getCurrentSnapshot()
+    const history = this.getHistory()
+
+    let action: MemoryRecommendation['action'] = 'none'
+    let reason = 'Memory usage is within normal limits'
+
+    if (snapshot.pressureLevel === MemoryPressureLevel.CRITICAL) {
+      if (history.trend > 0.1) {
+        action = 'restart_do'
+        reason = 'Critical memory with increasing trend - consider restarting Durable Object'
+      } else {
+        action = 'reduce_result_set'
+        reason = 'Critical memory usage - reduce result set sizes or paginate queries'
+      }
+    } else if (snapshot.pressureLevel === MemoryPressureLevel.WARNING) {
+      if (history.trend > 0.05) {
+        action = 'reduce_cache'
+        reason = 'Warning: memory growing - consider reducing cache sizes'
+      } else {
+        action = 'force_gc'
+        reason = 'Warning: high memory usage - consider forcing garbage collection'
+      }
+    }
+
+    // Calculate safe result set size based on available memory
+    const maxSafeResultSetBytes = Math.min(
+      snapshot.availableBytes * 0.5,
+      30 * 1024 * 1024 // Cap at 30MB
+    )
+
+    // Suggest PostgreSQL settings based on available memory
+    const suggestedPgSettings = this.getPostgresSettingsRecommendation()
+
+    return {
+      action,
+      reason,
+      pressureLevel: snapshot.pressureLevel,
+      usageRatio: snapshot.usageRatio,
+      workerSpecific: true,
+      maxSafeResultSetBytes,
+      suggestedPgSettings,
+    }
+  }
+
+  reset(): void {
+    this.history = []
+    this.peakUsage = 0
+    this.lastPressureLevel = MemoryPressureLevel.NORMAL
+    this.pressureStartTimes = {
+      [MemoryPressureLevel.NORMAL]: null,
+      [MemoryPressureLevel.WARNING]: null,
+      [MemoryPressureLevel.CRITICAL]: null,
+    }
+    this.pressureDurations = {
+      [MemoryPressureLevel.NORMAL]: 0,
+      [MemoryPressureLevel.WARNING]: 0,
+      [MemoryPressureLevel.CRITICAL]: 0,
+    }
+    this.consecutivePressureCount = 0
+    this.sustainedPressureEmitted = false
+    this.operationMemory.clear()
+    this.alerts = []
+  }
+
+  // ============================================================================
+  // Extended Methods - WASM Heap Tracking
+  // ============================================================================
+
+  getHeapGrowthRate(): HeapGrowthRate {
+    if (this.history.length < 2) {
+      return { bytesPerSecond: 0, percentageGrowth: 0, isGrowing: false }
+    }
+
+    const first = this.history[0]!!
+    const last = this.history[this.history.length - 1]!!
+    let timeDeltaMs = last.timestamp - first.timestamp
+    const bytesDelta = last.heapSizeBytes - first.heapSizeBytes
+
+    // If timestamps are identical (synchronous calls), use sample count as a proxy
+    // Assume 1ms per sample as a minimum interval
+    if (timeDeltaMs <= 0) {
+      timeDeltaMs = this.history.length - 1
+    }
+
+    const bytesPerSecond = (bytesDelta / timeDeltaMs) * 1000
+    const percentageGrowth = first.heapSizeBytes > 0
+      ? ((last.heapSizeBytes - first.heapSizeBytes) / first.heapSizeBytes) * 100
+      : 0
+
+    return {
+      bytesPerSecond,
+      percentageGrowth,
+      isGrowing: bytesDelta > 0,
+    }
+  }
+
+  getFragmentationRatio(): number {
+    const snapshot = this.getCurrentSnapshot()
+    if (snapshot.heapSizeBytes === 0) return 0
+
+    // Fragmentation = (allocated - used) / allocated
+    return (snapshot.heapSizeBytes - snapshot.heapUsedBytes) / snapshot.heapSizeBytes
+  }
+
+  getHeapAllocationHistogram(): HeapAllocationHistogram {
+    // Define bucket boundaries (in bytes)
+    const boundaries = [
+      16 * 1024 * 1024,   // 16MB
+      32 * 1024 * 1024,   // 32MB
+      48 * 1024 * 1024,   // 48MB
+      64 * 1024 * 1024,   // 64MB
+      80 * 1024 * 1024,   // 80MB
+      96 * 1024 * 1024,   // 96MB
+      112 * 1024 * 1024,  // 112MB
+      128 * 1024 * 1024,  // 128MB
+    ]
+
+    const buckets: { min: number; max: number; count: number }[] = []
+    let prevBoundary = 0
+
+    for (const boundary of boundaries) {
+      buckets.push({ min: prevBoundary, max: boundary, count: 0 })
+      prevBoundary = boundary
+    }
+
+    // Count snapshots in each bucket
+    for (const snapshot of this.history) {
+      for (const bucket of buckets) {
+        if (snapshot.heapUsedBytes >= bucket.min && snapshot.heapUsedBytes < bucket.max) {
+          bucket.count++
+          break
+        }
+      }
+    }
+
+    return {
+      buckets,
+      totalSamples: this.history.length,
+    }
+  }
+
+  // ============================================================================
+  // Extended Methods - Memory Pressure Integration
+  // ============================================================================
+
+  getPressureDuration(): Record<MemoryPressureLevel, number> {
+    const now = Date.now()
+    const durations = { ...this.pressureDurations }
+
+    // Add current ongoing duration
+    const currentLevel = this.lastPressureLevel
+    if (this.pressureStartTimes[currentLevel] !== null) {
+      const elapsed = now - this.pressureStartTimes[currentLevel]!
+      // If elapsed is 0 (synchronous calls), count records instead (at least 1ms per record)
+      const duration = elapsed > 0 ? elapsed : this.consecutivePressureCount
+      durations[currentLevel] += duration
+    }
+
+    return durations
+  }
+
+  getPressureScore(): number {
+    const snapshot = this.getCurrentSnapshot()
+    const history = this.getHistory()
+
+    // Base score from usage ratio (0-70 points)
+    let score = snapshot.usageRatio * 70
+
+    // Add trend component (0-20 points)
+    if (history.trend > 0) {
+      score += Math.min(history.trend * 100, 20)
+    }
+
+    // Add pressure level component (0-10 points)
+    if (snapshot.pressureLevel === MemoryPressureLevel.CRITICAL) {
+      score += 10
+    } else if (snapshot.pressureLevel === MemoryPressureLevel.WARNING) {
+      score += 5
+    }
+
+    return Math.min(Math.max(score, 0), 100)
+  }
+
+  // ============================================================================
+  // Extended Methods - 128MB Workers Limit Awareness
+  // ============================================================================
+
+  predictTimeToOOM(): OOMPrediction {
+    const growthRate = this.getHeapGrowthRate()
+    const snapshot = this.getCurrentSnapshot()
+
+    if (growthRate.bytesPerSecond <= 0) {
+      return { estimatedMs: Infinity, confidence: 0.9, willOOM: false }
+    }
+
+    const bytesRemaining = snapshot.bytesUntilOOM
+    const estimatedMs = (bytesRemaining / growthRate.bytesPerSecond) * 1000
+
+    // Confidence is higher with more history data points
+    const confidence = Math.min(this.history.length / 20, 1) * 0.9
+
+    return {
+      estimatedMs: Math.max(0, estimatedMs),
+      confidence,
+      willOOM: estimatedMs < 60000 && growthRate.isGrowing, // Within 60 seconds
+    }
+  }
+
+  // ============================================================================
+  // Extended Methods - Memory Growth Tracking
+  // ============================================================================
+
+  getMemoryVelocity(): MemoryVelocity {
+    if (this.history.length < 2) {
+      return { bytesPerMs: 0, accelerating: false }
+    }
+
+    const recent = this.history.slice(-5)
+    if (recent.length < 2) {
+      return { bytesPerMs: 0, accelerating: false }
+    }
+
+    const first = recent[0]!
+    const last = recent[recent.length - 1]!
+    let timeDelta = last.timestamp - first.timestamp
+    const bytesDelta = last.heapUsedBytes - first.heapUsedBytes
+
+    // If timestamps are identical (synchronous calls), use sample count as a proxy
+    if (timeDelta <= 0) {
+      timeDelta = recent.length - 1
+    }
+
+    const bytesPerMs = bytesDelta / timeDelta
+
+    // Check if accelerating by comparing recent vs older velocity
+    let accelerating = false
+    if (this.history.length >= 10) {
+      const older = this.history.slice(-10, -5)
+      if (older.length >= 2) {
+        const olderFirst = older[0]!
+        const olderLast = older[older.length - 1]!
+        let olderTimeDelta = olderLast.timestamp - olderFirst.timestamp
+        if (olderTimeDelta <= 0) olderTimeDelta = older.length - 1
+        const olderBytesDelta = olderLast.heapUsedBytes - olderFirst.heapUsedBytes
+        const olderVelocity = olderBytesDelta / olderTimeDelta
+        accelerating = bytesPerMs > olderVelocity * 1.1 // 10% faster
+      }
+    }
+
+    return { bytesPerMs, accelerating }
+  }
+
+  forecastMemoryUsage(msAhead: number): MemoryForecast {
+    const snapshot = this.getCurrentSnapshot()
+    const velocity = this.getMemoryVelocity()
+
+    // Use the growth trend to estimate prediction when velocity is calculated from samples
+    // Scale the velocity by the msAhead factor, treating each sample as ~1ms
+    const predictedBytes = snapshot.heapUsedBytes + (velocity.bytesPerMs * msAhead)
+
+    // Confidence interval based on history variance
+    let variance = 0
+    if (this.history.length > 1) {
+      const avg = this.history.reduce((sum, s) => sum + s.heapUsedBytes, 0) / this.history.length
+      variance = this.history.reduce((sum, s) => sum + Math.pow(s.heapUsedBytes - avg, 2), 0) / this.history.length
+    }
+    const stdDev = Math.sqrt(variance)
+
+    // Ensure we always show growth if velocity is positive
+    const minPredicted = velocity.bytesPerMs > 0
+      ? snapshot.heapUsedBytes + 1
+      : snapshot.heapUsedBytes
+
+    return {
+      predictedBytes: Math.max(minPredicted, predictedBytes),
+      confidenceInterval: {
+        low: Math.max(0, predictedBytes - 2 * stdDev),
+        high: predictedBytes + 2 * stdDev,
+      },
+    }
+  }
+
+  analyzeForLeaks(): LeakAnalysis {
+    if (this.history.length < 5) {
+      return { possibleLeak: false, growthPattern: 'stable', confidence: 0 }
+    }
+
+    const pattern = this.analyzeGrowthPattern()
+
+    return {
+      possibleLeak: pattern.pattern === 'monotonic' && pattern.healthStatus !== 'normal',
+      growthPattern: pattern.pattern,
+      confidence: Math.min(this.history.length / 20, 1),
+    }
+  }
+
+  analyzeGrowthPattern(): GrowthPatternAnalysis {
+    if (this.history.length < 3) {
+      return { pattern: 'stable', healthStatus: 'normal' }
+    }
+
+    let increases = 0
+    let decreases = 0
+    let unchanged = 0
+
+    for (let i = 1; i < this.history.length; i++) {
+      const delta = this.history[i]!.heapUsedBytes - this.history[i - 1]!.heapUsedBytes
+      // Use a small threshold to filter noise (100KB)
+      const threshold = 100 * 1024
+
+      if (delta > threshold) increases++
+      else if (delta < -threshold) decreases++
+      else unchanged++
+    }
+
+    const total = this.history.length - 1
+    const increaseRatio = increases / total
+    const decreaseRatio = decreases / total
+
+    let pattern: GrowthPatternAnalysis['pattern']
+    let healthStatus: GrowthPatternAnalysis['healthStatus']
+
+    if (increaseRatio > 0.7 && decreaseRatio < 0.15) {
+      pattern = 'monotonic'
+      healthStatus = 'concerning'
+    } else if (increaseRatio > 0.3 && decreaseRatio > 0.25) {
+      pattern = 'sawtooth'
+      healthStatus = 'normal'
+    } else if (decreaseRatio > 0.7) {
+      pattern = 'decreasing'
+      healthStatus = 'normal'
+    } else {
+      pattern = 'stable'
+      healthStatus = 'normal'
+    }
+
+    // If memory is critically high even with sawtooth, it's still concerning
+    const currentSnapshot = this.getCurrentSnapshot()
+    if (currentSnapshot.pressureLevel === MemoryPressureLevel.CRITICAL) {
+      healthStatus = 'critical'
+    } else if (pattern === 'monotonic') {
+      healthStatus = 'concerning'
+    }
+
+    return { pattern, healthStatus }
+  }
+
+  // ============================================================================
+  // Extended Methods - PostgreSQL Memory Settings
+  // ============================================================================
+
+  getPostgresSettingsRecommendation(): PostgresSettingsRecommendation {
+    const snapshot = this.getCurrentSnapshot()
+    const availableForPg = snapshot.availableBytes * 0.6 // Reserve 40% for queries and runtime
+
+    // shared_buffers should be ~25% of available PG memory
+    const sharedBuffersMB = Math.max(4, Math.floor((availableForPg * 0.25) / (1024 * 1024)))
+
+    // work_mem depends on pressure level
+    let workMemMB: number
+    if (snapshot.pressureLevel === MemoryPressureLevel.CRITICAL) {
+      workMemMB = 1
+    } else if (snapshot.pressureLevel === MemoryPressureLevel.WARNING) {
+      workMemMB = 2
+    } else {
+      workMemMB = 4
+    }
+
+    // maintenance_work_mem for VACUUM etc
+    const maintenanceWorkMemMB = Math.max(4, Math.floor((availableForPg * 0.1) / (1024 * 1024)))
+
+    // temp_buffers
+    const tempBuffersMB = Math.max(2, Math.floor((availableForPg * 0.05) / (1024 * 1024)))
+
+    return {
+      shared_buffers: `${sharedBuffersMB}MB`,
+      work_mem: `${workMemMB}MB`,
+      maintenance_work_mem: `${maintenanceWorkMemMB}MB`,
+      temp_buffers: `${tempBuffersMB}MB`,
+    }
+  }
+
+  analyzePostgresMemoryConfig(config: Record<string, string>): PostgresConfigAnalysis {
+    const snapshot = this.getCurrentSnapshot()
+    const issues: string[] = []
+    const recommended = this.getPostgresSettingsRecommendation()
+
+    // Parse config values (support MB suffix)
+    const parseBytes = (value: string): number => {
+      const match = value.match(/^(\d+)(MB|KB|GB)?$/i)
+      if (!match) return 0
+      const num = parseInt(match[1]!, 10)
+      const unit = (match[2] || 'MB').toUpperCase()
+      switch (unit) {
+        case 'GB': return num * 1024 * 1024 * 1024
+        case 'MB': return num * 1024 * 1024
+        case 'KB': return num * 1024
+        default: return num
+      }
+    }
+
+    // Check shared_buffers
+    if (config.shared_buffers) {
+      const configuredSharedBuffers = parseBytes(config.shared_buffers)
+      const recommendedSharedBuffers = parseBytes(recommended.shared_buffers)
+
+      if (configuredSharedBuffers > recommendedSharedBuffers * 1.5) {
+        issues.push(`shared_buffers (${config.shared_buffers}) is too high for available memory; recommend ${recommended.shared_buffers}`)
+      }
+    }
+
+    // Check work_mem
+    if (config.work_mem) {
+      const configuredWorkMem = parseBytes(config.work_mem)
+      const recommendedWorkMem = parseBytes(recommended.work_mem)
+
+      if (configuredWorkMem > recommendedWorkMem * 2) {
+        issues.push(`work_mem (${config.work_mem}) is too high for current memory pressure; recommend ${recommended.work_mem}`)
+      }
+    }
+
+    // Check total memory pressure
+    const totalConfigured =
+      parseBytes(config.shared_buffers || '0') +
+      parseBytes(config.work_mem || '0') * 10 // Multiply by approx number of connections/operations
+
+    if (totalConfigured > snapshot.availableBytes) {
+      issues.push(`Total PostgreSQL memory allocation may exceed available memory (${snapshot.availableBytes} bytes available)`)
+    }
+
+    return {
+      issues,
+      recommendations: recommended,
+    }
+  }
+
+  // ============================================================================
+  // Extended Methods - Operation Memory Tracking
+  // ============================================================================
+
+  recordOperationMemory(operation: string, bytes: number): void {
+    const current = this.operationMemory.get(operation) || 0
+    this.operationMemory.set(operation, current + bytes)
+  }
+
+  getMemoryBreakdownByOperation(): Record<string, number> {
+    const breakdown: Record<string, number> = {}
+    for (const [operation, bytes] of this.operationMemory) {
+      breakdown[operation] = bytes
+    }
+    return breakdown
+  }
+
+  // ============================================================================
+  // Extended Methods - Alert Integration
+  // ============================================================================
+
+  getAlertSummary(): AlertSummary {
+    const byLevel = { warning: 0, critical: 0 }
+    let lastAlertTime: number | null = null
+
+    for (const alert of this.alerts) {
+      if (alert.level === 'warning') byLevel.warning++
+      if (alert.level === 'critical') byLevel.critical++
+
+      if (!lastAlertTime || alert.snapshot.timestamp > lastAlertTime) {
+        lastAlertTime = alert.snapshot.timestamp
+      }
+    }
+
+    return {
+      totalAlerts: this.alerts.length,
+      byLevel,
+      lastAlertTime,
+    }
+  }
+}
+
+export function createMemoryMetricsCollector(config?: MemoryMetricsConfig): MemoryMetricsCollector {
+  return new MemoryMetricsCollectorImpl(config)
+}
+
+// ============================================================================
+// Heap Getters
+// ============================================================================
+
+export function createPGLiteHeapGetter(
+  getModule: () => { HEAPU8?: Uint8Array } | null
+): () => WasmHeapInfo | null {
+  return () => {
+    const module = getModule()
+    if (!module || !module.HEAPU8) return null
+    const heapu8 = module.HEAPU8
+    const size = heapu8.length
+    let used = size
+    for (let i = size - 1; i >= 0; i--) {
+      if (heapu8[i] !== 0) {
+        used = i + 1
+        break
+      }
+    }
+    return { size, used }
+  }
+}
+
+export function createEstimatedHeapGetter(): () => WasmHeapInfo {
+  const estimatedSize = 32 * 1024 * 1024
+  return () => {
+    const used = Math.floor(estimatedSize * 0.6)
+    return { size: estimatedSize, used }
+  }
+}
+
+// ============================================================================
+// Memory Budget Calculator
+// ============================================================================
+
+export interface MemoryBudgetOptions {
+  totalBytes?: number
+  wasmBinaryBytes?: number
+  dataFileBytes?: number
+  jsRuntimeBytes?: number
+  sharedBuffersBytes?: number
+  workMemBytes?: number
+  walBuffersBytes?: number
+}
+
+export function calculateMemoryBudget(options?: MemoryBudgetOptions): MemoryBudget {
+  const totalBytes = options?.totalBytes ?? WORKER_MEMORY_LIMIT_BYTES
+  const wasmBinaryBytes = options?.wasmBinaryBytes ?? 8.5 * 1024 * 1024
+  const dataFileBytes = options?.dataFileBytes ?? 4.7 * 1024 * 1024
+  const jsRuntimeBytes = options?.jsRuntimeBytes ?? 5 * 1024 * 1024
+  const sharedBuffersBytes = options?.sharedBuffersBytes ?? 16 * 1024 * 1024
+  const workMemBytes = options?.workMemBytes ?? 2 * 1024 * 1024
+  const walBuffersBytes = options?.walBuffersBytes ?? 1 * 1024 * 1024
+
+  const staticBytes = wasmBinaryBytes + dataFileBytes + jsRuntimeBytes
+  const catalogOverhead = 10 * 1024 * 1024
+  const postgresOverheadBytes = sharedBuffersBytes + walBuffersBytes + catalogOverhead
+  const totalRequired = staticBytes + postgresOverheadBytes + workMemBytes
+  const availableForQueriesBytes = Math.max(0, totalBytes - totalRequired)
+  const maxResultSetBytes = Math.min(availableForQueriesBytes * 0.5, 30 * 1024 * 1024)
+
+  // Check if the budget exceeds the Worker memory limit
+  const exceedsLimit = totalRequired > WORKER_MEMORY_LIMIT_BYTES
+  const overageBytes = Math.max(0, totalRequired - WORKER_MEMORY_LIMIT_BYTES)
+
+  return {
+    totalBytes,
+    staticBytes,
+    postgresOverheadBytes,
+    workMemBytes,
+    availableForQueriesBytes,
+    maxResultSetBytes,
+    exceedsLimit,
+    overageBytes,
+  }
+}