@dotdo/postgres 0.1.0

package/src/worker/memory-pressure.ts

@@ -0,0 +1,2650 @@
+/**
+ * Memory Pressure Monitoring and OOM Protection for PostgresDO
+ *
+ * This module provides memory monitoring capabilities for PGLite running
+ * in Cloudflare Workers (128MB limit). It detects high memory usage and
+ * can automatically take protective actions to prevent OOM crashes.
+ *
+ * ## Key Features
+ *
+ * - **Real-time memory pressure tracking** - Monitors heap usage and classifies
+ *   pressure levels (normal, warning, critical, oom)
+ * - **Automatic extension unloading** - Drops least-important PostgreSQL extensions
+ *   when memory is critically low
+ * - **GC hint triggering** - Suggests garbage collection at configurable thresholds
+ *   with rate limiting to prevent thrashing
+ * - **Cache eviction** - Automatically evicts cache entries under pressure using
+ *   configurable strategies (LRU, largest-first)
+ * - **Query management** - Pauses or rejects queries under extreme pressure
+ * - **Recovery with hysteresis** - Prevents oscillation by requiring sustained
+ *   normal pressure before full recovery
+ * - **Metrics export** - Prometheus and JSON format metrics for observability
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createMemoryPressureManager } from './memory-pressure'
+ *
+ * const manager = createMemoryPressureManager({
+ *   warningThresholdPercent: 70,
+ *   criticalThresholdPercent: 85,
+ *   autoUnloadExtensions: true,
+ * })
+ *
+ * // Listen for pressure changes
+ * const unsubscribe = manager.onPressureChange((event) => {
+ *   console.log(`Pressure: ${event.previousLevel} -> ${event.currentLevel}`)
+ * })
+ *
+ * // Start monitoring
+ * manager.startMonitoring()
+ *
+ * // Check status at any time
+ * const stats = manager.getMemoryStats()
+ *
+ * // Clean up when done
+ * manager.dispose()
+ * ```
+ *
+ * ## Cloudflare Workers Constraints
+ *
+ * - 128MB total memory limit per isolate
+ * - ~15MB static (WASM + data + JS)
+ * - ~16MB shared_buffers
+ * - ~16MB WAL + buffers
+ * - ~10MB PostgreSQL catalog/metadata
+ * - ~71MB available for queries, results, and runtime
+ *
+ * @module worker/memory-pressure
+ */
+
+import type {
+  MemoryPressureLevel,
+  MemoryStats,
+  MemoryPressureEvent,
+  MemoryPressureAction,
+  MemoryPressureActionResult,
+  MemoryPressureConfig,
+  MemoryPressureListener,
+} from './types'
+
+import type { TieredStorageOrchestrator, TierMigrationEvent } from '../storage/tiered-orchestrator'
+
+// =============================================================================
+// Imported Constants (from centralized config)
+// =============================================================================
+
+import {
+  WORKER_MEMORY_LIMIT_BYTES,
+  PGLITE_BASELINE_BYTES,
+  DEFAULT_WARNING_THRESHOLD_PERCENT,
+  DEFAULT_CRITICAL_THRESHOLD_PERCENT,
+  DEFAULT_OOM_THRESHOLD_PERCENT,
+  MEMORY_SPIKE_THRESHOLD_BYTES,
+  DEFAULT_METRICS_HISTORY_SIZE,
+} from '../config/memory'
+
+import {
+  DEFAULT_CHECK_INTERVAL_MS,
+  DEFAULT_GC_HINT_MIN_INTERVAL_MS,
+  DEFAULT_RECOVERY_HYSTERESIS_MS,
+  DEFAULT_QUERY_PAUSE_TIMEOUT_MS,
+  DEFAULT_RECOVERY_STEP_INTERVAL_MS,
+  DEFAULT_SUSTAINED_PRESSURE_THRESHOLD_MS,
+  DEFAULT_MAX_LISTENERS,
+} from '../config/timeouts'
+
+// =============================================================================
+// Local Constant Aliases (for backward compatibility in this module)
+// =============================================================================
+
+/** Default Cloudflare Worker memory limit: 128MB */
+const DEFAULT_MEMORY_LIMIT_BYTES = WORKER_MEMORY_LIMIT_BYTES
+
+/** Default pressure thresholds (percentage of memory limit) */
+const DEFAULT_WARNING_THRESHOLD = DEFAULT_WARNING_THRESHOLD_PERCENT
+const DEFAULT_CRITICAL_THRESHOLD = DEFAULT_CRITICAL_THRESHOLD_PERCENT
+const DEFAULT_OOM_THRESHOLD = DEFAULT_OOM_THRESHOLD_PERCENT
+
+/** Spike detection threshold: 10MB sudden increase */
+const SPIKE_DETECTION_THRESHOLD_BYTES = MEMORY_SPIKE_THRESHOLD_BYTES
+
+/**
+ * Extensions safe to unload under memory pressure, ordered by priority.
+ * First = least important = dropped first.
+ */
+const DEFAULT_EXTENSION_UNLOAD_PRIORITY = [
+  'tablefunc', // Rarely used in typical workloads
+  'fuzzystrmatch', // Nice to have for fuzzy matching
+  'unaccent', // Text processing utility
+  'btree_gist', // Index type - usually not critical
+  'btree_gin', // Index type - usually not critical
+  'intarray', // Array functions
+  'cube', // Multi-dimensional data
+  'earthdistance', // Geo calculations (depends on cube)
+  'ltree', // Tree data
+  'hstore', // Key-value pairs
+  'citext', // Case-insensitive text
+  'pg_trgm', // Trigram matching
+  'pgcrypto', // Crypto functions - often important
+  'uuid_ossp', // UUID generation - often important
+  'vector', // Vector search - often critical for AI apps
+]
+
+/** Default features that can be disabled under pressure */
+const DEFAULT_FEATURES_TO_DISABLE = ['caching', 'prefetching', 'parallel-queries']
+
+/** Default eviction target percentages by pressure level */
+const DEFAULT_EVICTION_TARGET_PERCENT: Record<MemoryPressureLevel, number> = {
+  normal: 0,
+  warning: 20,
+  critical: 50,
+  oom: 100,
+}
+
+/** Pressure level numeric indices for fast comparison */
+const PRESSURE_LEVEL_INDEX: Record<MemoryPressureLevel, number> = {
+  normal: 0,
+  warning: 1,
+  critical: 2,
+  oom: 3,
+}
+
+/** Default demotion configuration per pressure level */
+const DEFAULT_DEMOTION_CONFIG: DemotionConfig = {
+  warning: { hotEvictCount: 10, warmDemoteCount: 0 },
+  critical: { hotEvictCount: 25, warmDemoteCount: 5 },
+  oom: { hotEvictCount: 50, warmDemoteCount: 15 },
+}
+
+/** Default minimum interval between pressure-triggered demotions */
+const DEFAULT_DEMOTION_MIN_INTERVAL_MS = 500
+
+// =============================================================================
+// Optimized Constants for Memory Pressure Heuristics
+// =============================================================================
+
+/**
+ * EMA (Exponential Moving Average) smoothing factor for heap usage.
+ * Range: 0-1, higher = more weight on recent samples, lower = more smoothing.
+ * 0.3 provides good balance between responsiveness and noise reduction.
+ */
+const EMA_SMOOTHING_FACTOR = 0.3
+
+/**
+ * Minimum samples required for reliable trend detection.
+ * Below this, predictions have low confidence.
+ */
+const MIN_SAMPLES_FOR_TREND = 5
+
+/**
+ * Minimum samples for high-confidence OOM prediction.
+ */
+const MIN_SAMPLES_FOR_OOM_PREDICTION = 10
+
+/**
+ * Growth rate threshold for "stable" classification (1KB/s).
+ * Memory changes below this are considered noise.
+ */
+const STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC = 1024
+
+/**
+ * Rapid growth threshold (5MB/s) - triggers more aggressive responses.
+ */
+const RAPID_GROWTH_THRESHOLD_BYTES_PER_SEC = 5 * 1024 * 1024
+
+/**
+ * OOM prediction horizon - warn if OOM predicted within this time.
+ */
+const OOM_PREDICTION_HORIZON_MS = 60000
+
+/**
+ * Hysteresis margin for pressure level changes (2%).
+ * Prevents oscillation when hovering near thresholds.
+ * Reserved for future hysteresis implementation.
+ */
+const _PRESSURE_HYSTERESIS_PERCENT = 2
+void _PRESSURE_HYSTERESIS_PERCENT // Suppress unused warning - reserved for future use
+
+/**
+ * Heap sampling constants - optimized for balance between accuracy and speed.
+ * Reserved for future heap sampling implementation.
+ */
+const _HEAP_SAMPLE_STRIDE_SHIFT = 8 // ~256 samples, uses bit shift for speed
+const _HEAP_SAMPLE_UNROLL_FACTOR = 4 // Unroll factor for loop optimization
+void _HEAP_SAMPLE_STRIDE_SHIFT // Suppress unused warning - reserved for future use
+void _HEAP_SAMPLE_UNROLL_FACTOR // Suppress unused warning - reserved for future use
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Demotion counts per pressure level
+ */
+export interface DemotionLevelConfig {
+  /** Number of entries to evict from hot tier */
+  hotEvictCount: number
+  /** Number of entries to demote from warm tier */
+  warmDemoteCount: number
+}
+
+/**
+ * Configuration for demotions per pressure level
+ */
+export interface DemotionConfig {
+  warning: DemotionLevelConfig
+  critical: DemotionLevelConfig
+  oom: DemotionLevelConfig
+}
+
+/**
+ * Demotion metrics tracking pressure-triggered demotions
+ */
+export interface DemotionMetrics {
+  /** Total number of pressure-triggered demotions */
+  pressureTriggeredDemotions: number
+  /** Demotions by pressure level */
+  demotionsByPressureLevel: Record<MemoryPressureLevel, number>
+  /** Failed demotions */
+  failedDemotions: number
+  /** Total bytes freed by demotions */
+  bytesFreedByDemotion: number
+  /** Last demotion timestamp */
+  lastDemotionTimestamp: number | null
+}
+
+/**
+ * Pressure demotion event emitted when pressure-triggered demotion occurs
+ */
+export interface PressureDemotionEvent {
+  /** Pressure level that triggered the demotion */
+  pressureLevel: MemoryPressureLevel
+  /** Demotions performed */
+  demotions: TierMigrationEvent[]
+  /** Total number of entries demoted */
+  totalDemoted: number
+  /** Timestamp of the event */
+  timestamp: Date
+}
+
+/**
+ * Result of a manual demotion trigger
+ */
+export interface TriggerDemotionResult {
+  /** Whether the demotion was successful */
+  success: boolean
+  /** Number of entries demoted */
+  demotedCount: number
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Options for triggering demotions manually
+ */
+export interface TriggerDemotionOptions {
+  /** Number of entries to evict from hot tier */
+  hotEvictCount: number
+  /** Number of entries to demote from warm tier */
+  warmDemoteCount: number
+}
+
+/**
+ * Memory spike event - emitted when heap grows suddenly
+ */
+export interface MemorySpikeEvent {
+  /** Bytes gained since last sample */
+  deltaBytes: number
+  /** Previous heap usage */
+  previousBytes: number
+  /** Current heap usage */
+  currentBytes: number
+  /** When the spike was detected */
+  timestamp: Date
+}
+
+/**
+ * Single metrics sample for history tracking
+ */
+export interface MetricsSample {
+  timestamp: Date
+  heapUsed: number
+  pressureLevel: MemoryPressureLevel
+}
+
+/**
+ * Collection of metrics samples
+ */
+export interface MetricsHistory {
+  samples: MetricsSample[]
+}
+
+/**
+ * Memory growth rate calculation result
+ */
+export interface MemoryGrowthRate {
+  /** Bytes per second growth rate (negative = decreasing) */
+  bytesPerSecond: number
+  /** Overall trend direction */
+  trend: 'increasing' | 'stable' | 'decreasing'
+}
+
+/**
+ * OOM prediction based on current growth rate
+ */
+export interface OOMPrediction {
+  /** Estimated milliseconds until OOM (Infinity if not growing) */
+  estimatedMs: number
+  /** Confidence level (0-1) based on sample count and consistency */
+  confidence: number
+  /** Whether OOM is predicted within 60 seconds */
+  willOOM: boolean
+  /** Regression quality (R-squared) - how well the linear model fits */
+  rSquared?: number
+  /** Predicted memory usage at OOM horizon */
+  predictedUsageAtHorizon?: number
+}
+
+/**
+ * Smoothed pressure state for EMA-based detection
+ */
+export interface SmoothedPressureState {
+  /** EMA of heap usage in bytes */
+  emaHeapUsage: number
+  /** EMA of pressure level (as numeric index 0-3) */
+  emaPressureLevel: number
+  /** Variance in recent samples */
+  recentVariance: number
+  /** Whether pressure is trending up or down */
+  trend: 'rising' | 'falling' | 'stable'
+  /** Last raw heap usage for delta calculation */
+  lastRawHeapUsage: number
+}
+
+/**
+ * Result of a GC hint request
+ */
+export interface GCResult {
+  /** Whether GC was actually triggered */
+  triggered: boolean
+  /** Estimated bytes freed (if measurable) */
+  bytesFreedEstimate: number
+  /** Time spent in GC (if triggered) */
+  durationMs: number
+}
+
+/**
+ * Aggregated GC metrics
+ */
+export interface GCMetrics {
+  /** Total number of GC hints issued */
+  totalHints: number
+  /** Average bytes freed per hint */
+  avgBytesFreed: number
+  /** Average duration per hint */
+  avgDurationMs: number
+  /** Percentage of hints that freed memory */
+  successRate: number
+}
+
+/**
+ * Recovery event - emitted when pressure drops
+ */
+export interface RecoveryEvent {
+  /** Pressure level we're recovering from */
+  fromLevel: MemoryPressureLevel
+  /** New pressure level */
+  toLevel: MemoryPressureLevel
+  /** How long we were at elevated pressure */
+  recoveryDurationMs: number
+}
+
+/**
+ * Paused operation tracking
+ */
+export interface PausedOperation {
+  /** Unique operation identifier */
+  id: string
+  /** Current status */
+  status: 'paused' | 'resumed' | 'cancelled'
+  /** When the operation was paused */
+  pausedAt: Date
+  /** Promise that resolves when operation can resume */
+  resumePromise: Promise<void>
+  /** Resolve the resume promise */
+  resolve: () => void
+  /** Reject the resume promise */
+  reject: (error: Error) => void
+}
+
+/**
+ * Time spent at each pressure level
+ */
+export interface PressureDurations {
+  normal: number
+  warning: number
+  critical: number
+  oom: number
+}
+
+/**
+ * JSON metrics export format
+ */
+export interface JSONMetricsExport {
+  current: MemoryStats
+  history: MetricsHistory
+  aggregates: {
+    avgHeapUsed: number
+    peakHeapUsed: number
+    totalGCCount: number
+    pressureTriggeredDemotions: number
+    failedDemotions: number
+    bytesFreedByDemotion: number
+  }
+  /** Enhanced heuristics metrics (new in optimized version) */
+  heuristics?: {
+    /** Smoothed pressure state from EMA */
+    smoothedState: SmoothedPressureState
+    /** Adaptive thresholds based on memory behavior */
+    adaptiveThresholds: {
+      warningThresholdPercent: number
+      criticalThresholdPercent: number
+      oomThresholdPercent: number
+    }
+    /** OOM prediction with confidence */
+    oomPrediction: OOMPrediction
+    /** Memory growth rate */
+    growthRate: MemoryGrowthRate
+    /** Whether pressure is currently volatile */
+    isVolatile: boolean
+  }
+}
+
+/**
+ * Cache manager interface for eviction
+ */
+export interface CacheManager {
+  /** Evict entries until targetBytes are freed, returns actual bytes freed */
+  evictLRU?: (targetBytes: number) => number
+  /** Evict the single largest entry, returns bytes freed */
+  evictLargest?: () => number
+  /** Get total size of cached data */
+  getTotalSize: () => number
+  /** Clear all entries */
+  clear?: () => void
+}
+
+/**
+ * Error thrown when memory pressure prevents an operation
+ */
+export class MemoryPressureError extends Error {
+  readonly code: string = 'MEMORY_PRESSURE_HIGH'
+  readonly memoryStats: MemoryStats
+
+  constructor(message: string, memoryStats: MemoryStats) {
+    super(message)
+    this.name = 'MemoryPressureError'
+    this.memoryStats = memoryStats
+  }
+}
+
+/**
+ * Extended configuration options for the memory pressure manager.
+ *
+ * These options control advanced behaviors like GC hints, cache eviction,
+ * query handling, and recovery behavior.
+ */
+export interface ExtendedMemoryPressureConfig extends MemoryPressureConfig {
+  // === GC Hint Configuration ===
+
+  /** Callback invoked when a GC hint should be issued */
+  onGCHint?: (level: MemoryPressureLevel, options?: { aggressive: boolean }) => void
+  /** Thresholds for different GC intensities */
+  gcHintThresholds?: { mild: number; normal: number; aggressive: number }
+  /** Minimum interval between GC hints to prevent thrashing */
+  gcHintMinIntervalMs?: number
+
+  // === Cache Eviction Configuration ===
+
+  /** Enable automatic cache eviction under pressure */
+  autoCacheEviction?: boolean
+  /** Strategy for cache eviction */
+  cacheEvictionStrategy?: 'lru' | 'largest-first'
+  /** Percentage of cache to evict at each pressure level */
+  evictionTargetPercent?: Record<MemoryPressureLevel, number>
+  /** Callback when a cache entry is evicted */
+  onCacheEviction?: (entry: { key: string; size: number }) => void
+
+  // === Query Handling Configuration ===
+
+  /** Enable pausing queries at critical pressure */
+  queryPausingEnabled?: boolean
+  /** Enable rejecting queries at OOM pressure */
+  queryRejectionEnabled?: boolean
+  /** Resume paused queries when usage drops below this percentage */
+  queryResumeThresholdPercent?: number
+  /** Maximum time to pause a query before timing out */
+  queryPauseTimeoutMs?: number
+  /** Enable query memory estimation */
+  estimateQueryMemory?: boolean
+  /** Queries with estimated results below this are always allowed */
+  smallQueryThresholdBytes?: number
+  /** Allow queries that started before pressure to complete */
+  allowInFlightCompletion?: boolean
+  /** Cancel queries running longer than threshold at OOM */
+  cancelLongRunningAtOOM?: boolean
+  /** Threshold for "long running" query */
+  longRunningThresholdMs?: number
+
+  // === Metrics Configuration ===
+
+  /** Number of samples to keep in metrics history */
+  metricsHistorySize?: number
+
+  // === Recovery Configuration ===
+
+  /** Callback when recovery completes */
+  onRecovery?: (event: RecoveryEvent) => void
+  /** Automatically disable features under pressure */
+  autoDisableFeatures?: boolean
+  /** Features to disable under pressure */
+  featuresToDisable?: string[]
+  /** Enable gradual feature re-enablement during recovery */
+  gradualRecovery?: boolean
+  /** Interval between recovery steps */
+  recoveryStepIntervalMs?: number
+  /** Callback for each recovery step */
+  onRecoveryStep?: (step: string) => void
+  /** Time to wait at normal pressure before full recovery */
+  recoveryHysteresisMs?: number
+
+  // === Sustained Pressure Configuration ===
+
+  /** Time at elevated pressure before alert */
+  sustainedPressureThresholdMs?: number
+  /** Callback for sustained pressure alerts */
+  onSustainedPressure?: (level: MemoryPressureLevel, durationMs: number) => void
+
+  // === Hard Limit Enforcement ===
+
+  /** Strictly enforce memory limit for guarded operations */
+  hardLimitEnforcement?: boolean
+
+  // === Tiered Storage Demotion Configuration ===
+
+  /** Enable automatic demotion on memory pressure (default: true) */
+  autoDemoteOnPressure?: boolean
+  /** Configuration for demotion counts per pressure level */
+  demotionConfig?: DemotionConfig
+  /** Minimum interval between pressure-triggered demotions in ms */
+  demotionMinIntervalMs?: number
+  /** Trigger GC hint before demotion (default: false) */
+  gcBeforeDemotion?: boolean
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+// Cache performance.memory reference to avoid repeated property access
+let cachedPerformanceMemory: { usedJSHeapSize: number } | null | undefined
+
+/**
+ * Estimate WASM heap memory usage.
+ *
+ * In Cloudflare Workers, we can't directly access Emscripten's HEAP.
+ * This function provides an estimate based on available metrics.
+ *
+ * Optimized: Caches performance.memory reference to reduce property lookups.
+ *
+ * Priority:
+ * 1. performance.memory.usedJSHeapSize (if available)
+ * 2. Conservative estimate based on typical PGLite footprint
+ */
+function estimateHeapUsage(): number {
+  // Check cache first (undefined = not checked, null = not available)
+  if (cachedPerformanceMemory === undefined) {
+    if (typeof performance !== 'undefined' && 'memory' in performance) {
+      cachedPerformanceMemory = (performance as Performance & { memory?: { usedJSHeapSize: number } }).memory ?? null
+    } else {
+      cachedPerformanceMemory = null
+    }
+  }
+
+  if (cachedPerformanceMemory && typeof cachedPerformanceMemory.usedJSHeapSize === 'number') {
+    return cachedPerformanceMemory.usedJSHeapSize
+  }
+
+  // Fallback: use pre-computed constant
+  return PGLITE_BASELINE_BYTES
+}
+
+/**
+ * Determine memory pressure level from usage percentage.
+ * Optimized: Uses direct comparisons in descending order for early exit.
+ */
+function getPressureLevelFromPercent(
+  usagePercent: number,
+  thresholds: { warningThresholdPercent: number; criticalThresholdPercent: number; oomThresholdPercent: number }
+): MemoryPressureLevel {
+  // Check highest threshold first for fast rejection
+  if (usagePercent >= thresholds.oomThresholdPercent) return 'oom'
+  if (usagePercent >= thresholds.criticalThresholdPercent) return 'critical'
+  if (usagePercent >= thresholds.warningThresholdPercent) return 'warning'
+  return 'normal'
+}
+
+/**
+ * Get numeric index for pressure level comparison.
+ * Optimized: Uses pre-computed lookup table instead of array search.
+ */
+function getPressureLevelIndex(level: MemoryPressureLevel): number {
+  return PRESSURE_LEVEL_INDEX[level]
+}
+
+/**
+ * Calculate average of an array of numbers.
+ * Optimized: Uses for loop instead of reduce for better performance.
+ */
+function average(values: number[]): number {
+  const len = values.length
+  if (len === 0) return 0
+  let sum = 0
+  for (let i = 0; i < len; i++) {
+    sum += values[i] ?? 0
+  }
+  return sum / len
+}
+
+/**
+ * Calculate variance of an array of numbers.
+ * Optimized: Single-pass Welford's algorithm for numerical stability.
+ */
+function variance(values: number[]): number {
+  const len = values.length
+  if (len < 2) return 0
+
+  let mean = 0
+  let m2 = 0
+
+  for (let i = 0; i < len; i++) {
+    const value = values[i] ?? 0
+    const delta = value - mean
+    mean += delta / (i + 1)
+    m2 += delta * (value - mean)
+  }
+
+  return m2 / (len - 1)
+}
+
+/**
+ * Simple linear regression for trend analysis.
+ * Returns slope (bytes/ms), intercept, and R-squared.
+ * Optimized: Single-pass calculation.
+ */
+function linearRegression(
+  samples: { timestamp: Date; heapUsed: number }[]
+): { slope: number; intercept: number; rSquared: number } {
+  const n = samples.length
+  if (n < 2) return { slope: 0, intercept: 0, rSquared: 0 }
+
+  // Use first timestamp as origin for numerical stability
+  const t0 = samples[0]!.timestamp.getTime()
+
+  let sumX = 0
+  let sumY = 0
+  let sumXY = 0
+  let sumX2 = 0
+  let sumY2 = 0
+
+  for (let i = 0; i < n; i++) {
+    const sample = samples[i]!
+    const x = sample.timestamp.getTime() - t0
+    const y = sample.heapUsed
+    sumX += x
+    sumY += y
+    sumXY += x * y
+    sumX2 += x * x
+    sumY2 += y * y
+  }
+
+  const denom = n * sumX2 - sumX * sumX
+  if (Math.abs(denom) < 1e-10) return { slope: 0, intercept: sumY / n, rSquared: 0 }
+
+  const slope = (n * sumXY - sumX * sumY) / denom
+  const intercept = (sumY - slope * sumX) / n
+
+  // Calculate R-squared
+  const meanY = sumY / n
+  let ssRes = 0
+  let ssTot = 0
+
+  for (let i = 0; i < n; i++) {
+    const sample = samples[i]!
+    const x = sample.timestamp.getTime() - t0
+    const y = sample.heapUsed
+    const yPred = slope * x + intercept
+    ssRes += (y - yPred) ** 2
+    ssTot += (y - meanY) ** 2
+  }
+
+  const rSquared = ssTot > 0 ? 1 - ssRes / ssTot : 0
+
+  return { slope, intercept, rSquared }
+}
+
+/**
+ * Apply EMA (Exponential Moving Average) update.
+ * @param current - Current EMA value
+ * @param newValue - New sample value
+ * @param alpha - Smoothing factor (0-1)
+ */
+function updateEMA(current: number, newValue: number, alpha: number = EMA_SMOOTHING_FACTOR): number {
+  return alpha * newValue + (1 - alpha) * current
+}
+
+/**
+ * Ring buffer for efficient fixed-size history storage.
+ * Avoids shift() operations which are O(n) on arrays.
+ */
+class RingBuffer<T> {
+  private readonly buffer: (T | undefined)[]
+  private readonly capacity: number
+  private head = 0
+  private _size = 0
+
+  constructor(capacity: number) {
+    this.capacity = capacity
+    this.buffer = new Array(capacity)
+  }
+
+  push(item: T): void {
+    this.buffer[this.head] = item
+    this.head = (this.head + 1) % this.capacity
+    if (this._size < this.capacity) this._size++
+  }
+
+  get size(): number {
+    return this._size
+  }
+
+  /** Get item at logical index (0 = oldest, size-1 = newest) */
+  get(index: number): T | undefined {
+    if (index < 0 || index >= this._size) return undefined
+    const bufferIndex = (this.head - this._size + index + this.capacity) % this.capacity
+    return this.buffer[bufferIndex]
+  }
+
+  /** Get the oldest item */
+  first(): T | undefined {
+    return this._size > 0 ? this.get(0) : undefined
+  }
+
+  /** Get the newest item */
+  last(): T | undefined {
+    return this._size > 0 ? this.get(this._size - 1) : undefined
+  }
+
+  /** Convert to array (oldest to newest) */
+  toArray(): T[] {
+    const result: T[] = []
+    for (let i = 0; i < this._size; i++) {
+      const item = this.get(i)
+      if (item !== undefined) result.push(item)
+    }
+    return result
+  }
+
+  clear(): void {
+    this.head = 0
+    this._size = 0
+    // Don't clear buffer - items will be overwritten
+  }
+}
+
+// =============================================================================
+// Memory Pressure Manager
+// =============================================================================
+
+/**
+ * Memory Pressure Manager for PostgresDO
+ *
+ * Monitors memory usage and takes protective actions to prevent OOM crashes
+ * in Cloudflare Workers. Provides configurable thresholds, automatic actions,
+ * and detailed metrics for observability.
+ *
+ * @example
+ * ```typescript
+ * const manager = new MemoryPressureManager({
+ *   warningThresholdPercent: 70,
+ *   criticalThresholdPercent: 85,
+ *   onGCHint: (level, { aggressive }) => {
+ *     if (aggressive) globalThis.gc?.()
+ *   },
+ * })
+ *
+ * manager.onPressureChange((event) => {
+ *   console.log(`Pressure: ${event.currentLevel}`)
+ * })
+ *
+ * manager.startMonitoring()
+ * ```
+ */
+export class MemoryPressureManager {
+  // === Configuration ===
+  private readonly config: Required<MemoryPressureConfig>
+  private readonly extendedConfig: ExtendedMemoryPressureConfig
+  private readonly metricsHistorySize: number
+
+  // === External Dependencies ===
+  private pglite: {
+    query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[]; fields: unknown[] }>
+  } | null = null
+  private wasmModule: { HEAPU8?: Uint8Array } | null = null
+  private cacheManager: CacheManager | null = null
+
+  // === State Tracking ===
+  private lastPressureLevel: MemoryPressureLevel = 'normal'
+  private pressureLevelStartTime: number = Date.now()
+  private pressureDurations: PressureDurations = { normal: 0, warning: 0, critical: 0, oom: 0 }
+  private sustainedPressureAlerted = false
+
+  // === Recovery State ===
+  private inRecoveryMode = false
+  private recoveryProgress = 1.0
+  private recoveryStartTime: number | null = null
+  private recoveryPaused = false
+  private recoveryStepsExecuted: string[] = []
+
+  // === Feature Management ===
+  private readonly enabledFeatures: Set<string>
+  private readonly disabledFeatures = new Set<string>()
+  private unloadedExtensions = new Set<string>()
+
+  // === Query Management ===
+  private readonly pausedQueries = new Map<Promise<unknown>, PausedOperation>()
+  private readonly inFlightQueries = new Map<Promise<unknown>, { startTime: number; cancel?: () => void }>()
+
+  // === Metrics & History (using ring buffers for efficiency) ===
+  private metricsHistory!: RingBuffer<MetricsSample>
+  private lastHeapSample = 0
+  private gcMetrics!: { hints: number; bytesFreed: RingBuffer<number>; durations: RingBuffer<number> }
+  private lastGCHintTime = 0
+
+  // === Listeners ===
+  private listeners: MemoryPressureListener[] = []
+  private memorySpikeListeners: Array<(spike: MemorySpikeEvent) => void> = []
+  private recoveryListeners: Array<(event: RecoveryEvent) => void> = []
+  private pressureDemotionListeners: Array<(event: PressureDemotionEvent) => void> = []
+
+  // === Tiered Storage Integration ===
+  private tieredStorageOrchestrator: TieredStorageOrchestrator | null = null
+  private demotionMetrics: DemotionMetrics = {
+    pressureTriggeredDemotions: 0,
+    demotionsByPressureLevel: { normal: 0, warning: 0, critical: 0, oom: 0 },
+    failedDemotions: 0,
+    bytesFreedByDemotion: 0,
+    lastDemotionTimestamp: null,
+  }
+  private lastPressureDemotionTime = 0
+
+  // === Intervals ===
+  private checkInterval: ReturnType<typeof setInterval> | null = null
+  private sustainedPressureCheckInterval: ReturnType<typeof setInterval> | null = null
+  private gradualRecoveryInterval: ReturnType<typeof setInterval> | null = null
+
+  // === Smoothed Pressure State (for EMA-based detection) ===
+  private smoothedState: SmoothedPressureState = {
+    emaHeapUsage: 0,
+    emaPressureLevel: 0,
+    recentVariance: 0,
+    trend: 'stable',
+    lastRawHeapUsage: 0,
+  }
+  private smoothedStateInitialized = false
+
+  // === Testing Support ===
+  private simulatedHeapBytes = 0
+  private forcedHeapUsage: number | null = null
+
+  constructor(config: ExtendedMemoryPressureConfig = {}) {
+    this.extendedConfig = config
+    this.config = {
+      enabled: config.enabled ?? true,
+      memoryLimitBytes: config.memoryLimitBytes ?? DEFAULT_MEMORY_LIMIT_BYTES,
+      warningThresholdPercent: config.warningThresholdPercent ?? DEFAULT_WARNING_THRESHOLD,
+      criticalThresholdPercent: config.criticalThresholdPercent ?? DEFAULT_CRITICAL_THRESHOLD,
+      oomThresholdPercent: config.oomThresholdPercent ?? DEFAULT_OOM_THRESHOLD,
+      checkIntervalMs: config.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS,
+      autoUnloadExtensions: config.autoUnloadExtensions ?? true,
+      extensionUnloadPriority: config.extensionUnloadPriority ?? DEFAULT_EXTENSION_UNLOAD_PRIORITY,
+      maxListeners: config.maxListeners ?? DEFAULT_MAX_LISTENERS,
+    }
+    this.metricsHistorySize = config.metricsHistorySize ?? DEFAULT_METRICS_HISTORY_SIZE
+    this.enabledFeatures = new Set(config.featuresToDisable ?? DEFAULT_FEATURES_TO_DISABLE)
+
+    // Initialize ring buffers for efficient history storage
+    this.metricsHistory = new RingBuffer<MetricsSample>(this.metricsHistorySize)
+    this.gcMetrics = {
+      hints: 0,
+      bytesFreed: new RingBuffer<number>(50), // Keep last 50 GC results
+      durations: new RingBuffer<number>(50),
+    }
+  }
+
+  // ===========================================================================
+  // Configuration & Setup
+  // ===========================================================================
+
+  /**
+   * Set the PGlite instance for extension unloading operations.
+   *
+   * @param pglite - PGLite instance with query method
+   */
+  setPGlite(pglite: MemoryPressureManager['pglite']): void {
+    this.pglite = pglite
+  }
+
+  /**
+   * Set the WASM module for real-time heap tracking.
+   *
+   * When set, heap usage is calculated by sampling the HEAPU8 array
+   * instead of using estimates.
+   *
+   * @param module - Emscripten module with HEAPU8 property
+   */
+  setWasmHeapSource(module: { HEAPU8?: Uint8Array }): void {
+    this.wasmModule = module
+  }
+
+  /**
+   * Set the cache manager for eviction operations.
+   *
+   * @param manager - Cache manager with eviction methods
+   */
+  setCacheManager(manager: CacheManager): void {
+    this.cacheManager = manager
+  }
+
+  /**
+   * Get the current configuration.
+   *
+   * @returns Copy of the current configuration
+   */
+  getConfig(): Required<MemoryPressureConfig> {
+    return { ...this.config }
+  }
+
+  /**
+   * Update configuration at runtime.
+   *
+   * If checkIntervalMs is changed and monitoring is active, it will be restarted.
+   *
+   * @param config - Partial configuration to merge
+   */
+  setConfig(config: Partial<MemoryPressureConfig>): void {
+    Object.assign(this.config, config)
+
+    // Restart monitoring if interval changed
+    if (config.checkIntervalMs !== undefined && this.checkInterval) {
+      this.stopMonitoring()
+      this.startMonitoring()
+    }
+  }
+
+  // ===========================================================================
+  // Tiered Storage Orchestrator Integration
+  // ===========================================================================
+
+  /**
+   * Connect a TieredStorageOrchestrator for pressure-triggered demotions.
+   *
+   * When connected, the manager will automatically trigger demotions
+   * when memory pressure rises above warning level.
+   *
+   * @param orchestrator - TieredStorageOrchestrator instance or null to disconnect
+   */
+  setTieredStorageOrchestrator(orchestrator: TieredStorageOrchestrator | null): void {
+    this.tieredStorageOrchestrator = orchestrator
+  }
+
+  /**
+   * Check if a TieredStorageOrchestrator is connected.
+   *
+   * @returns True if an orchestrator is connected
+   */
+  hasTieredStorageOrchestrator(): boolean {
+    return this.tieredStorageOrchestrator !== null
+  }
+
+  /**
+   * Get demotion metrics for pressure-triggered demotions.
+   *
+   * @returns Demotion metrics
+   */
+  getDemotionMetrics(): DemotionMetrics {
+    return { ...this.demotionMetrics }
+  }
+
+  /**
+   * Add a listener for pressure-triggered demotion events.
+   *
+   * @param listener - Callback for demotion events
+   * @returns Unsubscribe function
+   */
+  onPressureDemotion(listener: (event: PressureDemotionEvent) => void): () => void {
+    this.pressureDemotionListeners.push(listener)
+    return () => {
+      const index = this.pressureDemotionListeners.indexOf(listener)
+      if (index >= 0) this.pressureDemotionListeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Manually trigger demotions.
+   *
+   * @param options - Demotion options specifying counts
+   * @returns Result of the demotion operation
+   */
+  async triggerDemotion(options: TriggerDemotionOptions): Promise<TriggerDemotionResult> {
+    if (!this.tieredStorageOrchestrator) {
+      return { success: false, demotedCount: 0, error: 'Tiered storage orchestrator not connected' }
+    }
+
+    try {
+      let totalDemoted = 0
+
+      // Evict from hot tier
+      if (options.hotEvictCount > 0) {
+        const hotEvents = await this.tieredStorageOrchestrator.evictLRUFromHot(options.hotEvictCount)
+        totalDemoted += hotEvents.filter((e) => e.success).length
+      }
+
+      // Demote from warm tier
+      if (options.warmDemoteCount > 0) {
+        const warmEvents = await this.tieredStorageOrchestrator.runDemotionCycle(options.warmDemoteCount)
+        totalDemoted += warmEvents.filter((e) => e.success).length
+      }
+
+      return { success: true, demotedCount: totalDemoted }
+    } catch (error) {
+      return {
+        success: false,
+        demotedCount: 0,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  /**
+   * Handle pressure-triggered demotion based on the current level.
+   *
+   * This is called automatically when pressure changes if autoDemoteOnPressure is enabled.
+   *
+   * @param level - Current pressure level
+   * @param forceBypassRateLimit - If true, bypass rate limiting (used when pressure escalates)
+   */
+  private async handlePressureDemotion(level: MemoryPressureLevel, forceBypassRateLimit = false): Promise<void> {
+    // Skip if auto-demotion is disabled
+    if (this.extendedConfig.autoDemoteOnPressure === false) return
+
+    // Skip if no orchestrator connected
+    if (!this.tieredStorageOrchestrator) return
+
+    // Skip for normal pressure
+    if (level === 'normal') return
+
+    // Check rate limiting (can be bypassed for escalation)
+    const now = Date.now()
+    const minInterval = this.extendedConfig.demotionMinIntervalMs ?? DEFAULT_DEMOTION_MIN_INTERVAL_MS
+    if (!forceBypassRateLimit && now - this.lastPressureDemotionTime < minInterval) return
+
+    // Get demotion config for this level
+    const demotionConfig = this.extendedConfig.demotionConfig ?? DEFAULT_DEMOTION_CONFIG
+    const levelConfig = demotionConfig[level]
+    if (!levelConfig || (levelConfig.hotEvictCount === 0 && levelConfig.warmDemoteCount === 0)) return
+
+    // Optionally trigger GC before demotion
+    if (this.extendedConfig.gcBeforeDemotion && this.extendedConfig.onGCHint) {
+      this.extendedConfig.onGCHint(level, { aggressive: level === 'critical' || level === 'oom' })
+    }
+
+    this.lastPressureDemotionTime = now
+
+    try {
+      const allDemotions: TierMigrationEvent[] = []
+      let bytesFreed = 0
+
+      // Evict from hot tier
+      if (levelConfig.hotEvictCount > 0) {
+        const hotEvents = await this.tieredStorageOrchestrator.evictLRUFromHot(levelConfig.hotEvictCount)
+        allDemotions.push(...hotEvents)
+
+        // Track bytes freed
+        for (const event of hotEvents) {
+          if (event.success) {
+            const entry = this.tieredStorageOrchestrator.getIndexEntry(event.key)
+            if (entry) bytesFreed += entry.size
+          }
+        }
+      }
+
+      // Demote from warm tier if critical or oom
+      if (levelConfig.warmDemoteCount > 0 && (level === 'critical' || level === 'oom')) {
+        const warmEvents = await this.tieredStorageOrchestrator.runDemotionCycle(levelConfig.warmDemoteCount)
+        allDemotions.push(...warmEvents)
+      }
+
+      // Update metrics
+      const successCount = allDemotions.filter((e) => e.success).length
+      const failCount = allDemotions.filter((e) => !e.success).length
+
+      this.demotionMetrics.pressureTriggeredDemotions += successCount
+      this.demotionMetrics.demotionsByPressureLevel[level] += successCount
+      this.demotionMetrics.failedDemotions += failCount
+      this.demotionMetrics.bytesFreedByDemotion += bytesFreed
+      this.demotionMetrics.lastDemotionTimestamp = now
+
+      // Emit demotion event
+      if (allDemotions.length > 0) {
+        const event: PressureDemotionEvent = {
+          pressureLevel: level,
+          demotions: allDemotions,
+          totalDemoted: successCount,
+          timestamp: new Date(),
+        }
+
+        for (const listener of this.pressureDemotionListeners) {
+          try {
+            listener(event)
+          } catch {
+            // Ignore listener errors
+          }
+        }
+      }
+    } catch (error) {
+      this.demotionMetrics.failedDemotions++
+      console.error('Pressure-triggered demotion failed:', error)
+    }
+  }
+
+  // ===========================================================================
+  // Monitoring Control
+  // ===========================================================================
+
+  /**
+   * Start periodic memory monitoring.
+   *
+   * Checks memory pressure at the configured interval and takes
+   * automatic actions when thresholds are crossed.
+   */
+  startMonitoring(): void {
+    if (!this.config.enabled || this.checkInterval) return
+
+    this.checkInterval = setInterval(() => {
+      this.checkMemoryPressure()
+    }, this.config.checkIntervalMs)
+  }
+
+  /**
+   * Stop periodic memory monitoring.
+   */
+  stopMonitoring(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval)
+      this.checkInterval = null
+    }
+  }
+
+  // ===========================================================================
+  // Memory Stats & Pressure Detection
+  // ===========================================================================
+
+  /**
+   * Get current memory statistics.
+   *
+   * @returns Current memory stats including pressure level
+   */
+  getMemoryStats(): MemoryStats {
+    const heapUsed = this.getCurrentHeapUsage()
+    const heapLimit = this.config.memoryLimitBytes
+    const usagePercent = (heapUsed / heapLimit) * 100
+    const pressureLevel = getPressureLevelFromPercent(usagePercent, this.config)
+
+    return {
+      heapUsed,
+      heapLimit,
+      usagePercent,
+      pressureLevel,
+      timestamp: new Date(),
+    }
+  }
+
+  /**
+   * Get current memory pressure level.
+   *
+   * This calculates the level based on current heap usage,
+   * not the cached lastPressureLevel.
+   *
+   * @returns Current pressure level
+   */
+  getPressureLevel(): MemoryPressureLevel {
+    return this.getMemoryStats().pressureLevel
+  }
+
+  /**
+   * Check if current pressure is at or above a threshold.
+   *
+   * Uses the cached lastPressureLevel for efficiency.
+   *
+   * @param level - Level to compare against
+   * @returns True if current pressure >= level
+   */
+  isPressureAtOrAbove(level: MemoryPressureLevel): boolean {
+    return getPressureLevelIndex(this.lastPressureLevel) >= getPressureLevelIndex(level)
+  }
+
+  /**
+   * Get current heap usage from the best available source.
+   *
+   * Priority:
+   * 1. Forced heap usage (for testing)
+   * 2. Simulated heap (for testing)
+   * 3. WASM module HEAPU8 (sampled)
+   * 4. Estimation fallback
+   */
+  private getCurrentHeapUsage(): number {
+    // Testing overrides
+    if (this.forcedHeapUsage !== null) return this.forcedHeapUsage
+    if (this.simulatedHeapBytes > 0) return this.simulatedHeapBytes
+
+    // Real WASM heap measurement via sampling
+    if (this.wasmModule?.HEAPU8) {
+      return this.sampleHeapUsage(this.wasmModule.HEAPU8)
+    }
+
+    // Fallback estimation
+    return estimateHeapUsage()
+  }
+
+  /**
+   * Sample WASM heap to estimate used bytes.
+   *
+   * Optimized: Uses bit-shift for stride calculation (avoiding division),
+   * reduced sample size for lower overhead, and unrolled loop for better
+   * CPU branch prediction.
+   */
+  private sampleHeapUsage(heap: Uint8Array): number {
+    const len = heap.length
+    if (len === 0) return 0
+
+    // Use bit shift for fast stride calculation (4KB stride = 2^12)
+    // This gives us len >> 12 samples, capped at HEAP_SAMPLE_SIZE
+    const stride = Math.max(1, len >> 8) // ~256 samples for typical heaps
+    let nonZeroCount = 0
+    let sampledCount = 0
+
+    // Unrolled loop: check 4 positions per iteration when possible
+    const end = len - (stride * 3)
+    let i = 0
+    for (; i < end; i += stride * 4) {
+      if (heap[i] !== 0) nonZeroCount++
+      if (heap[i + stride] !== 0) nonZeroCount++
+      if (heap[i + stride * 2] !== 0) nonZeroCount++
+      if (heap[i + stride * 3] !== 0) nonZeroCount++
+      sampledCount += 4
+    }
+
+    // Handle remaining samples
+    for (; i < len; i += stride) {
+      if (heap[i] !== 0) nonZeroCount++
+      sampledCount++
+    }
+
+    if (sampledCount === 0) return 0
+
+    // Use integer math where possible
+    return ((len * nonZeroCount) / sampledCount) | 0
+  }
+
+  // ===========================================================================
+  // Pressure Check & Response
+  // ===========================================================================
+
+  /**
+   * Check current memory pressure and take appropriate actions.
+   *
+   * This is called periodically by startMonitoring() and can also
+   * be called manually before expensive operations.
+   *
+   * @returns Pressure event if level changed, null otherwise
+   */
+  async checkMemoryPressure(): Promise<MemoryPressureEvent | null> {
+    if (!this.config.enabled) return null
+
+    const stats = this.getMemoryStats()
+    const previousLevel = this.lastPressureLevel
+    const currentLevel = stats.pressureLevel
+    const now = Date.now()
+
+    // Always record metrics
+    this.recordMetricSample()
+
+    // No change - handle sustained pressure check
+    if (previousLevel === currentLevel) {
+      this.handleSustainedPressure(currentLevel, now)
+      return null
+    }
+
+    // Level changed - update tracking
+    this.updatePressureDuration(previousLevel, now)
+    this.lastPressureLevel = currentLevel
+    this.sustainedPressureAlerted = false
+
+    // Handle transitions
+    const previousIndex = getPressureLevelIndex(previousLevel)
+    const currentIndex = getPressureLevelIndex(currentLevel)
+
+    const actionsTaken: MemoryPressureAction[] = []
+
+    if (currentIndex < previousIndex) {
+      // Pressure dropped - handle recovery
+      this.handleRecovery(previousLevel, currentLevel, now)
+    } else {
+      // Pressure rose - exit recovery mode
+      this.exitRecoveryMode()
+    }
+
+    // Take actions based on new pressure level
+    if (currentLevel !== 'normal') {
+      actionsTaken.push(...(await this.handleElevatedPressure(currentLevel, now)))
+    }
+
+    // Emit event
+    const event: MemoryPressureEvent = {
+      previousLevel,
+      currentLevel,
+      stats,
+      actionsTaken,
+      timestamp: new Date(),
+    }
+
+    this.emitPressureEvent(event)
+    return event
+  }
+
+  /**
+   * Handle sustained pressure alerts.
+   */
+  private handleSustainedPressure(level: MemoryPressureLevel, now: number): void {
+    if (level === 'normal' || this.sustainedPressureAlerted) return
+
+    const threshold = this.extendedConfig.sustainedPressureThresholdMs ?? DEFAULT_SUSTAINED_PRESSURE_THRESHOLD_MS
+    const elapsed = now - this.pressureLevelStartTime
+
+    if (elapsed >= threshold && this.extendedConfig.onSustainedPressure) {
+      this.extendedConfig.onSustainedPressure(level, elapsed)
+      this.sustainedPressureAlerted = true
+    }
+  }
+
+  /**
+   * Handle recovery from elevated pressure.
+   */
+  private handleRecovery(fromLevel: MemoryPressureLevel, toLevel: MemoryPressureLevel, now: number): void {
+    this.inRecoveryMode = true
+    this.recoveryStartTime = now
+    this.recoveryProgress = 0
+
+    if (toLevel === 'normal') {
+      this.resumePausedOperations()
+
+      if (this.extendedConfig.autoDisableFeatures) {
+        this.enableFeaturesAfterRecovery()
+      }
+
+      const elapsed = now - this.pressureLevelStartTime
+      const recoveryEvent: RecoveryEvent = {
+        fromLevel,
+        toLevel,
+        recoveryDurationMs: elapsed,
+      }
+
+      this.extendedConfig.onRecovery?.(recoveryEvent)
+      this.recoveryListeners.forEach((listener) => listener(recoveryEvent))
+    }
+  }
+
+  /**
+   * Exit recovery mode when pressure rises.
+   */
+  private exitRecoveryMode(): void {
+    this.inRecoveryMode = false
+    this.recoveryProgress = 0
+    this.recoveryStartTime = null
+    this.pauseGradualRecovery()
+  }
+
+  /**
+   * Handle actions for elevated pressure levels.
+   * Optimized: Uses adaptive GC timing based on pressure level and memory growth rate.
+   */
+  private async handleElevatedPressure(level: MemoryPressureLevel, now: number): Promise<MemoryPressureAction[]> {
+    const actionsTaken: MemoryPressureAction[] = []
+
+    // GC hint with adaptive timing based on pressure level
+    if (this.extendedConfig.onGCHint) {
+      const minInterval = this.getAdaptiveGCInterval(level, now)
+      if (now - this.lastGCHintTime >= minInterval) {
+        this.lastGCHintTime = now
+        const aggressive = level === 'critical' || level === 'oom'
+        this.extendedConfig.onGCHint(level, { aggressive })
+        actionsTaken.push('gc_triggered')
+      }
+    }
+
+    // Cache eviction
+    if (this.extendedConfig.autoCacheEviction && this.cacheManager) {
+      const evicted = this.evictCache(level)
+      if (evicted) actionsTaken.push('cache_cleared')
+    }
+
+    // Feature disabling
+    if ((level === 'critical' || level === 'oom') && this.extendedConfig.autoDisableFeatures) {
+      this.disableFeaturesUnderPressure()
+    }
+
+    // Extension unloading
+    if ((level === 'critical' || level === 'oom') && this.config.autoUnloadExtensions && this.pglite) {
+      const result = await this.unloadLeastImportantExtension()
+      if (result.success) actionsTaken.push('extension_unloaded')
+      actionsTaken.push('warning_emitted')
+    }
+
+    return actionsTaken
+  }
+
+  /**
+   * Calculate adaptive GC interval based on pressure level and memory growth rate.
+   *
+   * - At OOM: Minimal delay (500ms) to maximize chances of freeing memory
+   * - At critical: Reduced delay (2s) with faster triggering if memory is growing rapidly
+   * - At warning: Standard delay (5s) unless memory is growing rapidly
+   *
+   * @param level - Current pressure level
+   * @param now - Current timestamp
+   * @returns Minimum interval in milliseconds before next GC hint
+   */
+  private getAdaptiveGCInterval(level: MemoryPressureLevel, _now: number): number {
+    const baseInterval = this.extendedConfig.gcHintMinIntervalMs ?? DEFAULT_GC_HINT_MIN_INTERVAL_MS
+
+    // At OOM, be very aggressive
+    if (level === 'oom') {
+      return Math.min(500, baseInterval)
+    }
+
+    // At critical, reduce interval and consider growth rate
+    if (level === 'critical') {
+      const growthRate = this.getMemoryGrowthRate()
+      // If memory is growing rapidly (>5MB/s), be more aggressive
+      if (growthRate.bytesPerSecond > 5 * 1024 * 1024) {
+        return Math.min(1000, baseInterval / 2)
+      }
+      return Math.min(2000, baseInterval)
+    }
+
+    // At warning level, check if we should trigger earlier based on OOM prediction
+    if (level === 'warning') {
+      const prediction = this.predictTimeToOOM()
+      // If OOM predicted within 30 seconds with high confidence, reduce interval
+      if (prediction.willOOM && prediction.estimatedMs < 30000 && prediction.confidence > 0.7) {
+        return Math.min(2000, baseInterval / 2)
+      }
+    }
+
+    return baseInterval
+  }
+
+  /**
+   * Evict cache entries based on pressure level.
+   */
+  private evictCache(level: MemoryPressureLevel): boolean {
+    if (!this.cacheManager) return false
+
+    const evictionTargets = this.extendedConfig.evictionTargetPercent ?? DEFAULT_EVICTION_TARGET_PERCENT
+    const targetPercent = evictionTargets[level] ?? 0
+    if (targetPercent <= 0) return false
+
+    const totalCacheSize = this.cacheManager.getTotalSize()
+    const targetBytes = Math.floor(totalCacheSize * (targetPercent / 100))
+
+    if (level === 'oom' && this.cacheManager.clear) {
+      this.cacheManager.clear()
+      return true
+    }
+
+    if (this.cacheManager.evictLRU) {
+      this.cacheManager.evictLRU(targetBytes)
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Update pressure duration tracking.
+   */
+  private updatePressureDuration(level: MemoryPressureLevel, now: number): void {
+    const elapsed = now - this.pressureLevelStartTime
+    this.pressureDurations[level] += elapsed
+    this.pressureLevelStartTime = now
+  }
+
+  // ===========================================================================
+  // Extension Management
+  // ===========================================================================
+
+  /**
+   * Unload the least important extension to free memory.
+   *
+   * Uses the extensionUnloadPriority list to determine which extension
+   * to drop first.
+   *
+   * @returns Result of the unload operation
+   */
+  async unloadLeastImportantExtension(): Promise<MemoryPressureActionResult> {
+    if (!this.pglite) {
+      return { action: 'extension_unloaded', success: false, error: 'PGlite not available' }
+    }
+
+    // Get installed extensions
+    let installedExtensions: Set<string>
+    try {
+      const result = await this.pglite.query(`SELECT extname FROM pg_extension WHERE extname != 'plpgsql'`)
+      installedExtensions = new Set(
+        (result.rows as { extname: string }[])
+          .map((r) => r.extname)
+          .filter((name) => !this.unloadedExtensions.has(name))
+      )
+    } catch (error) {
+      return {
+        action: 'extension_unloaded',
+        success: false,
+        error: `Failed to get extensions: ${error instanceof Error ? error.message : 'Unknown'}`,
+      }
+    }
+
+    // Find and unload the least important
+    for (const extName of this.config.extensionUnloadPriority) {
+      if (installedExtensions.has(extName)) {
+        try {
+          await this.pglite.query(`DROP EXTENSION IF EXISTS "${extName}" CASCADE`)
+          this.unloadedExtensions.add(extName)
+          return { action: 'extension_unloaded', success: true, extensionName: extName }
+        } catch (error) {
+          return {
+            action: 'extension_unloaded',
+            success: false,
+            extensionName: extName,
+            error: `Failed to unload: ${error instanceof Error ? error.message : 'Unknown'}`,
+          }
+        }
+      }
+    }
+
+    return { action: 'extension_unloaded', success: false, error: 'No extensions available to unload' }
+  }
+
+  /**
+   * Get list of extensions unloaded due to memory pressure.
+   */
+  getUnloadedExtensions(): string[] {
+    return Array.from(this.unloadedExtensions)
+  }
+
+  /**
+   * Check if an extension was unloaded due to memory pressure.
+   */
+  wasExtensionUnloaded(extensionName: string): boolean {
+    return this.unloadedExtensions.has(extensionName)
+  }
+
+  /**
+   * Clear the list of unloaded extensions.
+   */
+  clearUnloadedExtensions(): void {
+    this.unloadedExtensions.clear()
+  }
+
+  // ===========================================================================
+  // GC Hints
+  // ===========================================================================
+
+  /**
+   * Request a garbage collection hint.
+   *
+   * Attempts to trigger GC if available and tracks effectiveness.
+   * Optimized: Uses performance.now() for higher precision timing.
+   *
+   * @returns Result including bytes freed estimate
+   */
+  async requestGC(): Promise<GCResult> {
+    const startTime = performance.now()
+    const heapBefore = this.getCurrentHeapUsage()
+    let triggered = false
+
+    // Try to trigger GC if available
+    const gc = (globalThis as { gc?: () => void }).gc
+    if (typeof gc === 'function') {
+      try {
+        gc()
+        triggered = true
+      } catch {
+        // GC not available or failed
+      }
+    }
+
+    const durationMs = performance.now() - startTime
+    const heapAfter = this.getCurrentHeapUsage()
+    const bytesFreedEstimate = Math.max(0, heapBefore - heapAfter)
+
+    // Track metrics using ring buffers
+    this.gcMetrics.hints++
+    this.gcMetrics.bytesFreed.push(bytesFreedEstimate)
+    this.gcMetrics.durations.push(durationMs)
+
+    return { triggered, bytesFreedEstimate, durationMs }
+  }
+
+  /**
+   * Get aggregated GC metrics.
+   * Optimized: Uses ring buffer's toArray() for efficient conversion.
+   */
+  getGCMetrics(): GCMetrics {
+    const { hints, bytesFreed, durations } = this.gcMetrics
+    const bytesFreedArray = bytesFreed.toArray()
+    const durationsArray = durations.toArray()
+
+    // Count successful GC hints (where memory was actually freed)
+    let successCount = 0
+    for (let i = 0; i < bytesFreedArray.length; i++) {
+      if ((bytesFreedArray[i] ?? 0) > 0) successCount++
+    }
+
+    return {
+      totalHints: hints,
+      avgBytesFreed: average(bytesFreedArray),
+      avgDurationMs: average(durationsArray),
+      successRate: hints > 0 ? successCount / Math.min(hints, bytesFreedArray.length) : 0,
+    }
+  }
+
+  // ===========================================================================
+  // Metrics & History
+  // ===========================================================================
+
+  /**
+   * Record a metric sample for history tracking.
+   *
+   * Also detects memory spikes, updates EMA state, and emits events.
+   * Optimized: Uses ring buffer (no shift operations).
+   */
+  recordMetricSample(): void {
+    const stats = this.getMemoryStats()
+    const sample: MetricsSample = {
+      timestamp: new Date(),
+      heapUsed: stats.heapUsed,
+      pressureLevel: stats.pressureLevel,
+    }
+
+    // Add to ring buffer (automatically handles size limit)
+    this.metricsHistory.push(sample)
+
+    // Update smoothed state for EMA-based detection
+    this.updateSmoothedState(stats.heapUsed, PRESSURE_LEVEL_INDEX[stats.pressureLevel])
+
+    // Spike detection
+    if (this.lastHeapSample > 0 && stats.heapUsed - this.lastHeapSample >= SPIKE_DETECTION_THRESHOLD_BYTES) {
+      const spike: MemorySpikeEvent = {
+        deltaBytes: stats.heapUsed - this.lastHeapSample,
+        previousBytes: this.lastHeapSample,
+        currentBytes: stats.heapUsed,
+        timestamp: new Date(),
+      }
+      // Use for loop instead of forEach for better performance
+      const listeners = this.memorySpikeListeners
+      for (let i = 0; i < listeners.length; i++) {
+        const listener = listeners[i]
+        if (listener) listener(spike)
+      }
+    }
+
+    this.lastHeapSample = stats.heapUsed
+  }
+
+  /**
+   * Update smoothed pressure state using EMA.
+   * This provides noise-resistant pressure tracking.
+   */
+  private updateSmoothedState(rawHeapUsage: number, rawPressureLevel: number): void {
+    if (!this.smoothedStateInitialized) {
+      // Initialize with first sample
+      this.smoothedState = {
+        emaHeapUsage: rawHeapUsage,
+        emaPressureLevel: rawPressureLevel,
+        recentVariance: 0,
+        trend: 'stable',
+        lastRawHeapUsage: rawHeapUsage,
+      }
+      this.smoothedStateInitialized = true
+      return
+    }
+
+    // Update EMAs
+    this.smoothedState.emaHeapUsage = updateEMA(
+      this.smoothedState.emaHeapUsage,
+      rawHeapUsage
+    )
+    this.smoothedState.emaPressureLevel = updateEMA(
+      this.smoothedState.emaPressureLevel,
+      rawPressureLevel
+    )
+
+    // Calculate variance from recent samples
+    if (this.metricsHistory.size >= 3) {
+      const recentSamples = this.metricsHistory.toArray().slice(-10)
+      const heapValues = recentSamples.map((s) => s.heapUsed)
+      this.smoothedState.recentVariance = variance(heapValues)
+    }
+
+    // Determine trend from delta
+    const delta = rawHeapUsage - this.smoothedState.lastRawHeapUsage
+    if (delta > STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC) {
+      this.smoothedState.trend = 'rising'
+    } else if (delta < -STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC) {
+      this.smoothedState.trend = 'falling'
+    } else {
+      this.smoothedState.trend = 'stable'
+    }
+
+    this.smoothedState.lastRawHeapUsage = rawHeapUsage
+  }
+
+  /**
+   * Get the smoothed pressure state.
+   * Useful for observability and debugging.
+   */
+  getSmoothedPressureState(): SmoothedPressureState {
+    return { ...this.smoothedState }
+  }
+
+  /**
+   * Get the smoothed pressure level (EMA-based).
+   * This is less sensitive to momentary spikes than raw pressure level.
+   */
+  getSmoothedPressureLevel(): MemoryPressureLevel {
+    const levelIndex = Math.round(this.smoothedState.emaPressureLevel)
+    const levels: MemoryPressureLevel[] = ['normal', 'warning', 'critical', 'oom']
+    return levels[Math.max(0, Math.min(3, levelIndex))] ?? 'normal'
+  }
+
+  /**
+   * Check if pressure is volatile (high variance in recent samples).
+   * Useful for deciding whether to take aggressive action.
+   */
+  isPressureVolatile(): boolean {
+    const stats = this.getMemoryStats()
+    // Coefficient of variation > 10% indicates volatility
+    const cv = stats.heapUsed > 0
+      ? Math.sqrt(this.smoothedState.recentVariance) / stats.heapUsed
+      : 0
+    return cv > 0.1
+  }
+
+  /**
+   * Get adaptive thresholds based on current memory behavior.
+   *
+   * Adjusts thresholds based on:
+   * 1. Memory growth rate - faster growth = lower thresholds
+   * 2. Volatility - high volatility = higher thresholds (less sensitive)
+   * 3. OOM prediction - imminent OOM = lower thresholds
+   */
+  getAdaptiveThresholds(): {
+    warningThresholdPercent: number
+    criticalThresholdPercent: number
+    oomThresholdPercent: number
+  } {
+    const baseConfig = this.config
+
+    // Return base thresholds if insufficient data
+    if (this.metricsHistory.size < MIN_SAMPLES_FOR_TREND) {
+      return {
+        warningThresholdPercent: baseConfig.warningThresholdPercent,
+        criticalThresholdPercent: baseConfig.criticalThresholdPercent,
+        oomThresholdPercent: baseConfig.oomThresholdPercent,
+      }
+    }
+
+    const growthRate = this.getMemoryGrowthRate()
+    const oomPrediction = this.predictTimeToOOM()
+
+    let warningAdjustment = 0
+    let criticalAdjustment = 0
+
+    // Adjust for growth rate
+    if (growthRate.bytesPerSecond > RAPID_GROWTH_THRESHOLD_BYTES_PER_SEC) {
+      // Rapid growth - lower thresholds by up to 10%
+      warningAdjustment -= 10
+      criticalAdjustment -= 5
+    } else if (growthRate.trend === 'increasing') {
+      // Moderate growth - lower thresholds by up to 5%
+      warningAdjustment -= 5
+      criticalAdjustment -= 3
+    }
+
+    // Adjust for volatility (increase thresholds if volatile to reduce false alarms)
+    if (this.isPressureVolatile()) {
+      warningAdjustment += 3
+      criticalAdjustment += 2
+    }
+
+    // Adjust for imminent OOM prediction
+    if (oomPrediction.willOOM && (oomPrediction.rSquared ?? 0) > 0.5) {
+      warningAdjustment -= 5
+      criticalAdjustment -= 3
+    }
+
+    // Apply adjustments with clamping
+    const warningThresholdPercent = Math.max(50, Math.min(80,
+      baseConfig.warningThresholdPercent + warningAdjustment
+    ))
+    const criticalThresholdPercent = Math.max(
+      warningThresholdPercent + 5,
+      Math.min(90, baseConfig.criticalThresholdPercent + criticalAdjustment)
+    )
+    const oomThresholdPercent = Math.max(
+      criticalThresholdPercent + 5,
+      baseConfig.oomThresholdPercent
+    )
+
+    return { warningThresholdPercent, criticalThresholdPercent, oomThresholdPercent }
+  }
+
+  /**
+   * Get pressure level using adaptive thresholds.
+   * This provides more intelligent pressure detection based on memory behavior.
+   */
+  getAdaptivePressureLevel(): MemoryPressureLevel {
+    const stats = this.getMemoryStats()
+    const adaptiveThresholds = this.getAdaptiveThresholds()
+    return getPressureLevelFromPercent(stats.usagePercent, adaptiveThresholds)
+  }
+
+  /**
+   * Get metrics history.
+   * Returns a copy of the samples array.
+   */
+  getMetricsHistory(): MetricsHistory {
+    return { samples: this.metricsHistory.toArray() }
+  }
+
+  /**
+   * Calculate memory growth rate using linear regression.
+   *
+   * Optimized improvements over simple first/last calculation:
+   * 1. Uses all samples via linear regression for more accurate trend
+   * 2. Filters out noise using configurable threshold
+   * 3. Provides confidence via R-squared value
+   *
+   * Falls back to simple calculation if insufficient samples.
+   */
+  getMemoryGrowthRate(): MemoryGrowthRate {
+    const historySize = this.metricsHistory.size
+
+    if (historySize < 2) {
+      return { bytesPerSecond: 0, trend: 'stable' }
+    }
+
+    // For small sample counts, use simple first/last calculation
+    if (historySize < MIN_SAMPLES_FOR_TREND) {
+      const first = this.metricsHistory.first()
+      const last = this.metricsHistory.last()
+
+      if (!first || !last) return { bytesPerSecond: 0, trend: 'stable' }
+
+      const timeDeltaMs = last.timestamp.getTime() - first.timestamp.getTime()
+      if (timeDeltaMs <= 0) return { bytesPerSecond: 0, trend: 'stable' }
+
+      const bytesDelta = last.heapUsed - first.heapUsed
+      const bytesPerSecond = (bytesDelta / timeDeltaMs) * 1000
+
+      return {
+        bytesPerSecond,
+        trend: this.classifyGrowthTrend(bytesPerSecond),
+      }
+    }
+
+    // Use linear regression for more accurate trend analysis
+    const samples = this.metricsHistory.toArray()
+    const { slope, rSquared } = linearRegression(samples)
+
+    // slope is in bytes/ms, convert to bytes/second
+    const bytesPerSecond = slope * 1000
+
+    // If regression fit is poor (R² < 0.5), the trend is likely noisy/unstable
+    // Use a higher threshold for stable classification
+    const effectiveThreshold = rSquared < 0.5
+      ? STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC * 2
+      : STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC
+
+    return {
+      bytesPerSecond,
+      trend: this.classifyGrowthTrend(bytesPerSecond, effectiveThreshold),
+    }
+  }
+
+  /**
+   * Classify growth trend based on bytes per second.
+   */
+  private classifyGrowthTrend(
+    bytesPerSecond: number,
+    threshold: number = STABLE_GROWTH_THRESHOLD_BYTES_PER_SEC
+  ): 'increasing' | 'stable' | 'decreasing' {
+    if (bytesPerSecond > threshold) return 'increasing'
+    if (bytesPerSecond < -threshold) return 'decreasing'
+    return 'stable'
+  }
+
+  /**
+   * Predict time to OOM using linear regression and statistical analysis.
+   *
+   * Improved prediction algorithm:
+   * 1. Uses linear regression for trend-based prediction
+   * 2. Includes R-squared for confidence estimation
+   * 3. Accounts for variance in samples (high variance = lower confidence)
+   * 4. Predicts usage at OOM horizon for early warning
+   */
+  predictTimeToOOM(): OOMPrediction {
+    const stats = this.getMemoryStats()
+    const historySize = this.metricsHistory.size
+
+    // Default return for insufficient data
+    const defaultPrediction: OOMPrediction = {
+      estimatedMs: Infinity,
+      confidence: 0,
+      willOOM: false,
+      rSquared: 0,
+      predictedUsageAtHorizon: stats.heapUsed,
+    }
+
+    if (historySize < 2) {
+      return defaultPrediction
+    }
+
+    const samples = this.metricsHistory.toArray()
+    const { slope, intercept, rSquared } = linearRegression(samples)
+
+    // slope is bytes/ms
+    // If not growing (slope <= 0), no OOM predicted
+    if (slope <= 0) {
+      return {
+        ...defaultPrediction,
+        rSquared,
+        predictedUsageAtHorizon: Math.max(0, stats.heapUsed + slope * OOM_PREDICTION_HORIZON_MS),
+      }
+    }
+
+    // Calculate time to reach OOM threshold
+    const oomThresholdBytes = (stats.heapLimit * this.config.oomThresholdPercent) / 100
+    const bytesRemaining = oomThresholdBytes - stats.heapUsed
+
+    if (bytesRemaining <= 0) {
+      // Already at or above OOM threshold
+      return {
+        estimatedMs: 0,
+        confidence: 1.0,
+        willOOM: true,
+        rSquared,
+        predictedUsageAtHorizon: stats.heapUsed,
+      }
+    }
+
+    // Time to OOM in milliseconds: (oomThreshold - currentUsage) / slope
+    const estimatedMs = bytesRemaining / slope
+
+    // Calculate confidence based on multiple factors:
+    // 1. Sample count (more samples = more confidence)
+    // 2. R-squared (better fit = more confidence)
+    // 3. Variance consistency (less variance = more confidence)
+    const sampleConfidence = Math.min(1.0, historySize / MIN_SAMPLES_FOR_OOM_PREDICTION)
+    const fitConfidence = Math.max(0, rSquared) // R² is already 0-1
+
+    // Calculate variance confidence
+    const heapValues = samples.map((s) => s.heapUsed)
+    const sampleVariance = variance(heapValues)
+    const meanHeap = average(heapValues)
+    // Coefficient of variation - lower is more consistent
+    const cv = meanHeap > 0 ? Math.sqrt(sampleVariance) / meanHeap : 0
+    const varianceConfidence = Math.max(0, 1 - cv * 10) // Scale CV to 0-1 range
+
+    // Combined confidence (weighted average)
+    const confidence = Math.min(1.0,
+      sampleConfidence * 0.3 +
+      fitConfidence * 0.5 +
+      varianceConfidence * 0.2
+    )
+
+    // Predict usage at the OOM horizon
+    const now = Date.now()
+    const horizonTime = now + OOM_PREDICTION_HORIZON_MS
+    const t0 = samples[0]?.timestamp.getTime() ?? now
+    const predictedUsageAtHorizon = Math.max(0, slope * (horizonTime - t0) + intercept)
+
+    return {
+      estimatedMs: Math.max(0, estimatedMs),
+      confidence,
+      willOOM: estimatedMs < OOM_PREDICTION_HORIZON_MS && confidence > 0.5,
+      rSquared,
+      predictedUsageAtHorizon,
+    }
+  }
+
+  /**
+   * Get time spent at each pressure level.
+   */
+  getPressureDurations(): PressureDurations {
+    const now = Date.now()
+    const currentElapsed = now - this.pressureLevelStartTime
+    const durations = { ...this.pressureDurations }
+    durations[this.lastPressureLevel] += currentElapsed
+    return durations
+  }
+
+  /**
+   * Export metrics in Prometheus format.
+   * Enhanced: Includes heuristics metrics for better observability.
+   */
+  exportPrometheusMetrics(): string {
+    const stats = this.getMemoryStats()
+    const gcMetrics = this.getGCMetrics()
+    const demotionMetrics = this.getDemotionMetrics()
+    const growthRate = this.getMemoryGrowthRate()
+    const oomPrediction = this.predictTimeToOOM()
+    const smoothedState = this.getSmoothedPressureState()
+    const adaptiveThresholds = this.getAdaptiveThresholds()
+
+    const levels: Record<MemoryPressureLevel, number> = { normal: 0, warning: 1, critical: 2, oom: 3 }
+    const trends: Record<string, number> = { decreasing: -1, stable: 0, increasing: 1 }
+
+    return [
+      // Core metrics
+      `# HELP postgres_memory_heap_bytes Current WASM heap usage in bytes`,
+      `# TYPE postgres_memory_heap_bytes gauge`,
+      `postgres_memory_heap_bytes ${stats.heapUsed}`,
+      `# HELP postgres_memory_pressure_level Current memory pressure level (0=normal, 1=warning, 2=critical, 3=oom)`,
+      `# TYPE postgres_memory_pressure_level gauge`,
+      `postgres_memory_pressure_level ${levels[stats.pressureLevel]}`,
+      `# HELP postgres_memory_gc_count Total number of GC hints triggered`,
+      `# TYPE postgres_memory_gc_count counter`,
+      `postgres_memory_gc_count ${gcMetrics.totalHints}`,
+      `# HELP postgres_memory_pressure_demotions_total Total number of pressure-triggered demotions`,
+      `# TYPE postgres_memory_pressure_demotions_total counter`,
+      `postgres_memory_pressure_demotions_total ${demotionMetrics.pressureTriggeredDemotions}`,
+      `# HELP postgres_memory_pressure_demotions_failed Total number of failed pressure-triggered demotions`,
+      `# TYPE postgres_memory_pressure_demotions_failed counter`,
+      `postgres_memory_pressure_demotions_failed ${demotionMetrics.failedDemotions}`,
+
+      // Heuristics metrics
+      `# HELP postgres_memory_heap_ema_bytes Exponential moving average of heap usage`,
+      `# TYPE postgres_memory_heap_ema_bytes gauge`,
+      `postgres_memory_heap_ema_bytes ${Math.round(smoothedState.emaHeapUsage)}`,
+      `# HELP postgres_memory_growth_rate_bytes_per_sec Memory growth rate in bytes per second`,
+      `# TYPE postgres_memory_growth_rate_bytes_per_sec gauge`,
+      `postgres_memory_growth_rate_bytes_per_sec ${Math.round(growthRate.bytesPerSecond)}`,
+      `# HELP postgres_memory_growth_trend Memory growth trend (-1=decreasing, 0=stable, 1=increasing)`,
+      `# TYPE postgres_memory_growth_trend gauge`,
+      `postgres_memory_growth_trend ${trends[growthRate.trend] ?? 0}`,
+      `# HELP postgres_memory_oom_prediction_ms Predicted time to OOM in milliseconds (-1 if not growing)`,
+      `# TYPE postgres_memory_oom_prediction_ms gauge`,
+      `postgres_memory_oom_prediction_ms ${oomPrediction.estimatedMs === Infinity ? -1 : Math.round(oomPrediction.estimatedMs)}`,
+      `# HELP postgres_memory_oom_prediction_confidence Confidence in OOM prediction (0-1)`,
+      `# TYPE postgres_memory_oom_prediction_confidence gauge`,
+      `postgres_memory_oom_prediction_confidence ${oomPrediction.confidence.toFixed(3)}`,
+      `# HELP postgres_memory_pressure_volatile Whether pressure readings are currently volatile (0=stable, 1=volatile)`,
+      `# TYPE postgres_memory_pressure_volatile gauge`,
+      `postgres_memory_pressure_volatile ${this.isPressureVolatile() ? 1 : 0}`,
+      `# HELP postgres_memory_adaptive_warning_threshold Current adaptive warning threshold percentage`,
+      `# TYPE postgres_memory_adaptive_warning_threshold gauge`,
+      `postgres_memory_adaptive_warning_threshold ${adaptiveThresholds.warningThresholdPercent}`,
+      `# HELP postgres_memory_adaptive_critical_threshold Current adaptive critical threshold percentage`,
+      `# TYPE postgres_memory_adaptive_critical_threshold gauge`,
+      `postgres_memory_adaptive_critical_threshold ${adaptiveThresholds.criticalThresholdPercent}`,
+    ].join('\n')
+  }
+
+  /**
+   * Export metrics in JSON format.
+   * Optimized: Calculates aggregates in a single pass.
+   * Enhanced: Includes heuristics data for observability.
+   */
+  exportJSONMetrics(): JSONMetricsExport {
+    const current = this.getMemoryStats()
+    const history = this.getMetricsHistory()
+    const gcMetrics = this.getGCMetrics()
+
+    // Single-pass calculation of avg and peak
+    const samples = history.samples
+    let sum = 0
+    let peak = current.heapUsed
+
+    if (samples.length > 0) {
+      for (let i = 0; i < samples.length; i++) {
+        const sample = samples[i]
+        if (sample) {
+          const heapUsed = sample.heapUsed
+          sum += heapUsed
+          if (heapUsed > peak) peak = heapUsed
+        }
+      }
+    }
+
+    const avgHeapUsed = samples.length > 0 ? sum / samples.length : current.heapUsed
+    const demotionMetrics = this.getDemotionMetrics()
+
+    return {
+      current,
+      history,
+      aggregates: {
+        avgHeapUsed,
+        peakHeapUsed: peak,
+        totalGCCount: gcMetrics.totalHints,
+        pressureTriggeredDemotions: demotionMetrics.pressureTriggeredDemotions,
+        failedDemotions: demotionMetrics.failedDemotions,
+        bytesFreedByDemotion: demotionMetrics.bytesFreedByDemotion,
+      },
+      heuristics: {
+        smoothedState: this.getSmoothedPressureState(),
+        adaptiveThresholds: this.getAdaptiveThresholds(),
+        oomPrediction: this.predictTimeToOOM(),
+        growthRate: this.getMemoryGrowthRate(),
+        isVolatile: this.isPressureVolatile(),
+      },
+    }
+  }
+
+  // ===========================================================================
+  // Query Management
+  // ===========================================================================
+
+  /**
+   * Execute a query with memory pressure guards.
+   *
+   * - Pauses at critical pressure (with timeout)
+   * - Rejects at OOM pressure
+   * - Enforces hard limits if configured
+   */
+  async guardedQuery<T>(
+    sql: string,
+    params: unknown[],
+    options?: { estimatedResultBytes?: number }
+  ): Promise<{ rows: T[]; fields: unknown[] }> {
+    const stats = this.getMemoryStats()
+
+    // Hard limit enforcement
+    if (this.extendedConfig.hardLimitEnforcement && this.forcedHeapUsage !== null) {
+      const estimatedUsage = options?.estimatedResultBytes ?? 0
+      if (this.forcedHeapUsage + estimatedUsage > this.config.memoryLimitBytes) {
+        throw new MemoryPressureError('Would exceed Worker memory limit', stats)
+      }
+    }
+
+    // OOM rejection
+    if (this.extendedConfig.queryRejectionEnabled && this.lastPressureLevel === 'oom') {
+      throw new MemoryPressureError('Memory pressure too high', stats)
+    }
+
+    // Critical pausing
+    if (this.extendedConfig.queryPausingEnabled && this.lastPressureLevel === 'critical') {
+      await this.waitForPressureRelief()
+    }
+
+    // Execute query
+    if (this.pglite) {
+      const result = await this.pglite.query(sql, params)
+      return result as { rows: T[]; fields: unknown[] }
+    }
+
+    return { rows: [], fields: [] }
+  }
+
+  /**
+   * Wait for pressure to drop with timeout.
+   */
+  private async waitForPressureRelief(): Promise<void> {
+    const timeoutMs = this.extendedConfig.queryPauseTimeoutMs ?? DEFAULT_QUERY_PAUSE_TIMEOUT_MS
+    const operation = this.pauseOperation(`query-${Date.now()}`)
+
+    // Track the operation so it can be resumed when pressure drops
+    const dummyPromise = Promise.resolve() as Promise<unknown>
+    this.pausedQueries.set(dummyPromise, operation)
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        operation.status = 'cancelled'
+        this.pausedQueries.delete(dummyPromise)
+        reject(new Error('Query paused due to memory pressure and timed out'))
+      }, timeoutMs)
+    })
+
+    try {
+      await Promise.race([operation.resumePromise, timeoutPromise])
+    } finally {
+      this.pausedQueries.delete(dummyPromise)
+    }
+  }
+
+  /**
+   * Get status of a query promise.
+   */
+  getQueryStatus(queryPromise: Promise<unknown>): 'paused' | 'executing' | 'completed' | 'unknown' {
+    const operation = this.pausedQueries.get(queryPromise)
+    if (operation) {
+      return operation.status === 'paused' ? 'paused' : 'executing'
+    }
+    return 'unknown'
+  }
+
+  /**
+   * Pause an operation and return a handle.
+   */
+  pauseOperation(id: string): PausedOperation {
+    let resolveFunc: () => void = () => {}
+    let rejectFunc: (error: Error) => void = () => {}
+
+    const resumePromise = new Promise<void>((resolve, reject) => {
+      resolveFunc = resolve
+      rejectFunc = reject
+    })
+
+    return {
+      id,
+      status: 'paused',
+      pausedAt: new Date(),
+      resumePromise,
+      resolve: resolveFunc,
+      reject: rejectFunc,
+    }
+  }
+
+  /**
+   * Resume all paused operations.
+   */
+  resumePausedOperations(): void {
+    for (const [, operation] of this.pausedQueries) {
+      if (operation.status === 'paused') {
+        operation.status = 'resumed'
+        operation.resolve()
+      }
+    }
+    this.pausedQueries.clear()
+  }
+
+  /**
+   * Enforce a hard allocation limit.
+   *
+   * Throws if the allocation would exceed the memory limit.
+   */
+  async guardedAllocation(bytes: number): Promise<{ allowed: boolean }> {
+    const currentUsage = this.forcedHeapUsage ?? this.getCurrentHeapUsage()
+    const totalAfter = currentUsage + bytes
+
+    if (this.extendedConfig.hardLimitEnforcement && totalAfter > this.config.memoryLimitBytes) {
+      throw new MemoryPressureError('Would exceed Worker memory limit', this.getMemoryStats())
+    }
+
+    return { allowed: true }
+  }
+
+  // ===========================================================================
+  // Feature Management
+  // ===========================================================================
+
+  /**
+   * Check if a feature is currently enabled.
+   */
+  isFeatureEnabled(feature: string): boolean {
+    return this.enabledFeatures.has(feature) && !this.disabledFeatures.has(feature)
+  }
+
+  /**
+   * Get count of enabled features.
+   */
+  getEnabledFeatureCount(): number {
+    let count = 0
+    for (const feature of this.enabledFeatures) {
+      if (!this.disabledFeatures.has(feature)) count++
+    }
+    return count
+  }
+
+  /**
+   * Disable features under pressure.
+   */
+  private disableFeaturesUnderPressure(): void {
+    if (!this.extendedConfig.autoDisableFeatures) return
+
+    const features = this.extendedConfig.featuresToDisable ?? DEFAULT_FEATURES_TO_DISABLE
+    for (const feature of features) {
+      this.disabledFeatures.add(feature)
+    }
+  }
+
+  /**
+   * Re-enable features after recovery.
+   */
+  private enableFeaturesAfterRecovery(): void {
+    if (!this.extendedConfig.autoDisableFeatures) return
+    this.disabledFeatures.clear()
+  }
+
+  // ===========================================================================
+  // Recovery Management
+  // ===========================================================================
+
+  /**
+   * Check if manager is in recovery mode.
+   */
+  isInRecoveryMode(): boolean {
+    return this.inRecoveryMode
+  }
+
+  /**
+   * Get recovery progress (0.0 to 1.0).
+   */
+  getRecoveryProgress(): number {
+    if (!this.inRecoveryMode) {
+      return this.lastPressureLevel === 'normal' ? 1.0 : 0.0
+    }
+
+    const hysteresisMs = this.extendedConfig.recoveryHysteresisMs ?? DEFAULT_RECOVERY_HYSTERESIS_MS
+    if (this.recoveryStartTime && hysteresisMs > 0) {
+      const elapsed = Date.now() - this.recoveryStartTime
+      this.recoveryProgress = Math.min(1.0, elapsed / hysteresisMs)
+
+      if (this.recoveryProgress >= 1.0 && this.lastPressureLevel === 'normal') {
+        this.inRecoveryMode = false
+      }
+    }
+
+    return this.recoveryProgress
+  }
+
+  /**
+   * Start gradual recovery of features.
+   */
+  async startGradualRecovery(): Promise<void> {
+    if (!this.extendedConfig.gradualRecovery) return
+
+    this.recoveryPaused = false
+    const intervalMs = this.extendedConfig.recoveryStepIntervalMs ?? DEFAULT_RECOVERY_STEP_INTERVAL_MS
+    const features = this.extendedConfig.featuresToDisable ?? DEFAULT_FEATURES_TO_DISABLE
+    let featureIndex = 0
+
+    this.gradualRecoveryInterval = setInterval(() => {
+      if (this.recoveryPaused || featureIndex >= features.length) {
+        if (this.gradualRecoveryInterval) {
+          clearInterval(this.gradualRecoveryInterval)
+          this.gradualRecoveryInterval = null
+        }
+        return
+      }
+
+      const feature = features[featureIndex]
+      if (feature) {
+        this.disabledFeatures.delete(feature)
+        this.recoveryStepsExecuted.push(feature)
+        this.extendedConfig.onRecoveryStep?.(feature)
+      }
+      featureIndex++
+    }, intervalMs)
+  }
+
+  /**
+   * Pause gradual recovery.
+   */
+  pauseGradualRecovery(): void {
+    this.recoveryPaused = true
+    if (this.gradualRecoveryInterval) {
+      clearInterval(this.gradualRecoveryInterval)
+      this.gradualRecoveryInterval = null
+    }
+  }
+
+  /**
+   * Check if recovery is paused.
+   */
+  isRecoveryPaused(): boolean {
+    return this.recoveryPaused
+  }
+
+  // ===========================================================================
+  // Event Listeners
+  // ===========================================================================
+
+  /**
+   * Add a memory pressure event listener.
+   *
+   * @param listener - Callback for pressure events
+   * @returns Unsubscribe function
+   */
+  onPressureChange(listener: MemoryPressureListener): () => void {
+    // Warn when approaching limit
+    const warningThreshold = Math.floor(this.config.maxListeners * 0.8)
+    if (this.listeners.length >= warningThreshold && this.listeners.length < this.config.maxListeners) {
+      console.warn(`Approaching memory pressure listener limit: ${this.listeners.length}/${this.config.maxListeners}`)
+    }
+
+    // Cap at max listeners (drop oldest)
+    if (this.listeners.length >= this.config.maxListeners) {
+      console.warn(`Memory pressure listener limit (${this.config.maxListeners}) reached. Dropping oldest listener.`)
+      this.listeners.shift()
+    }
+
+    this.listeners.push(listener)
+
+    return () => {
+      const index = this.listeners.indexOf(listener)
+      if (index >= 0) this.listeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Get current listener count.
+   */
+  getListenerCount(): number {
+    return this.listeners.length
+  }
+
+  /**
+   * Add a memory spike listener.
+   *
+   * @param listener - Callback for spike events
+   * @returns Unsubscribe function
+   */
+  onMemorySpike(listener: (spike: MemorySpikeEvent) => void): () => void {
+    this.memorySpikeListeners.push(listener)
+    return () => {
+      const index = this.memorySpikeListeners.indexOf(listener)
+      if (index >= 0) this.memorySpikeListeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Add a recovery event listener.
+   *
+   * @param listener - Callback for recovery events
+   * @returns Unsubscribe function
+   */
+  onRecovery(listener: (event: RecoveryEvent) => void): () => void {
+    this.recoveryListeners.push(listener)
+    return () => {
+      const index = this.recoveryListeners.indexOf(listener)
+      if (index >= 0) this.recoveryListeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Emit a pressure event to all listeners.
+   */
+  private emitPressureEvent(event: MemoryPressureEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch (error) {
+        console.error('Memory pressure listener error:', error)
+      }
+    }
+  }
+
+  // ===========================================================================
+  // Testing Support
+  // ===========================================================================
+
+  /**
+   * Simulate heap growth for testing.
+   * @internal
+   */
+  _simulateHeapGrowth(bytes: number): void {
+    this.simulatedHeapBytes += bytes
+  }
+
+  /**
+   * Set current heap usage for testing.
+   * @internal
+   */
+  _setCurrentHeapUsage(bytes: number): void {
+    this.forcedHeapUsage = bytes
+  }
+
+  /**
+   * Force a memory pressure level for testing.
+   *
+   * This updates the internal state and emits events as if the pressure
+   * had actually changed. Useful for testing pressure handling without
+   * actually consuming memory.
+   *
+   * @internal
+   */
+  _forceMemoryPressure(level: MemoryPressureLevel): MemoryPressureEvent | null {
+    const previousLevel = this.lastPressureLevel
+    if (previousLevel === level) return null
+
+    const now = Date.now()
+    this.updatePressureDuration(previousLevel, now)
+
+    // Handle recovery/escalation transitions
+    const previousIndex = getPressureLevelIndex(previousLevel)
+    const newIndex = getPressureLevelIndex(level)
+
+    if (previousIndex > 0 && newIndex < previousIndex) {
+      // Pressure dropped
+      this.handleRecovery(previousLevel, level, now)
+    } else if (newIndex > 0 && newIndex >= previousIndex) {
+      // Pressure rose
+      this.exitRecoveryMode()
+    }
+
+    this.lastPressureLevel = level
+
+    // Create synthetic stats
+    const usagePercent = level === 'oom' ? 96 : level === 'critical' ? 88 : level === 'warning' ? 75 : 50
+    const stats: MemoryStats = {
+      heapUsed: this.config.memoryLimitBytes * (usagePercent / 100),
+      heapLimit: this.config.memoryLimitBytes,
+      usagePercent,
+      pressureLevel: level,
+      timestamp: new Date(),
+    }
+
+    const event: MemoryPressureEvent = {
+      previousLevel,
+      currentLevel: level,
+      stats,
+      actionsTaken: [],
+      timestamp: new Date(),
+    }
+
+    this.emitPressureEvent(event)
+
+    // Trigger pressure-triggered demotion if pressure rose
+    if (newIndex > previousIndex && level !== 'normal') {
+      // Fire and forget - don't await to avoid blocking test
+      // Pass true to bypass rate limiting since this is a pressure escalation
+      this.handlePressureDemotion(level, true).catch(() => {})
+    }
+
+    return event
+  }
+
+  // ===========================================================================
+  // Cleanup
+  // ===========================================================================
+
+  /**
+   * Dispose of the manager and clean up all resources.
+   *
+   * This stops all intervals, clears all listeners, and releases references.
+   * Always call this when the manager is no longer needed.
+   */
+  dispose(): void {
+    // Stop all intervals
+    this.stopMonitoring()
+    this.pauseGradualRecovery()
+
+    if (this.sustainedPressureCheckInterval) {
+      clearInterval(this.sustainedPressureCheckInterval)
+      this.sustainedPressureCheckInterval = null
+    }
+
+    // Clear all listeners (set to empty arrays to avoid memory leaks)
+    this.listeners.length = 0
+    this.memorySpikeListeners.length = 0
+    this.recoveryListeners.length = 0
+    this.pressureDemotionListeners.length = 0
+
+    // Release external references
+    this.pglite = null
+    this.wasmModule = null
+    this.cacheManager = null
+    this.tieredStorageOrchestrator = null
+
+    // Clear state
+    this.unloadedExtensions.clear()
+    this.pausedQueries.clear()
+    this.inFlightQueries.clear()
+    this.metricsHistory.clear()
+    this.gcMetrics.bytesFreed.clear()
+    this.gcMetrics.durations.clear()
+    this.disabledFeatures.clear()
+    this.recoveryStepsExecuted.length = 0
+
+    // Reset testing state
+    this.simulatedHeapBytes = 0
+    this.forcedHeapUsage = null
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a memory pressure manager with default configuration.
+ *
+ * @param config - Optional configuration overrides
+ * @returns Configured MemoryPressureManager instance
+ */
+export function createMemoryPressureManager(config?: ExtendedMemoryPressureConfig): MemoryPressureManager {
+  return new MemoryPressureManager(config)
+}