@dotdo/postgres 0.1.0

package/dist/worker/memory-pressure.d.ts

@@ -0,0 +1,892 @@
+/**
+ * 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, MemoryPressureActionResult, MemoryPressureConfig, MemoryPressureListener } from './types';
+import type { TieredStorageOrchestrator, TierMigrationEvent } from '../storage/tiered-orchestrator';
+/**
+ * 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 declare class MemoryPressureError extends Error {
+    readonly code: string;
+    readonly memoryStats: MemoryStats;
+    constructor(message: string, 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 {
+    /** 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;
+    /** 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;
+    /** 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;
+    /** Number of samples to keep in metrics history */
+    metricsHistorySize?: number;
+    /** 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;
+    /** Time at elevated pressure before alert */
+    sustainedPressureThresholdMs?: number;
+    /** Callback for sustained pressure alerts */
+    onSustainedPressure?: (level: MemoryPressureLevel, durationMs: number) => void;
+    /** Strictly enforce memory limit for guarded operations */
+    hardLimitEnforcement?: boolean;
+    /** 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;
+}
+/**
+ * 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 declare class MemoryPressureManager {
+    private readonly config;
+    private readonly extendedConfig;
+    private readonly metricsHistorySize;
+    private pglite;
+    private wasmModule;
+    private cacheManager;
+    private lastPressureLevel;
+    private pressureLevelStartTime;
+    private pressureDurations;
+    private sustainedPressureAlerted;
+    private inRecoveryMode;
+    private recoveryProgress;
+    private recoveryStartTime;
+    private recoveryPaused;
+    private recoveryStepsExecuted;
+    private readonly enabledFeatures;
+    private readonly disabledFeatures;
+    private unloadedExtensions;
+    private readonly pausedQueries;
+    private readonly inFlightQueries;
+    private metricsHistory;
+    private lastHeapSample;
+    private gcMetrics;
+    private lastGCHintTime;
+    private listeners;
+    private memorySpikeListeners;
+    private recoveryListeners;
+    private pressureDemotionListeners;
+    private tieredStorageOrchestrator;
+    private demotionMetrics;
+    private lastPressureDemotionTime;
+    private checkInterval;
+    private sustainedPressureCheckInterval;
+    private gradualRecoveryInterval;
+    private smoothedState;
+    private smoothedStateInitialized;
+    private simulatedHeapBytes;
+    private forcedHeapUsage;
+    constructor(config?: ExtendedMemoryPressureConfig);
+    /**
+     * Set the PGlite instance for extension unloading operations.
+     *
+     * @param pglite - PGLite instance with query method
+     */
+    setPGlite(pglite: MemoryPressureManager['pglite']): void;
+    /**
+     * 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;
+    /**
+     * Set the cache manager for eviction operations.
+     *
+     * @param manager - Cache manager with eviction methods
+     */
+    setCacheManager(manager: CacheManager): void;
+    /**
+     * Get the current configuration.
+     *
+     * @returns Copy of the current configuration
+     */
+    getConfig(): Required<MemoryPressureConfig>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Check if a TieredStorageOrchestrator is connected.
+     *
+     * @returns True if an orchestrator is connected
+     */
+    hasTieredStorageOrchestrator(): boolean;
+    /**
+     * Get demotion metrics for pressure-triggered demotions.
+     *
+     * @returns Demotion metrics
+     */
+    getDemotionMetrics(): DemotionMetrics;
+    /**
+     * Add a listener for pressure-triggered demotion events.
+     *
+     * @param listener - Callback for demotion events
+     * @returns Unsubscribe function
+     */
+    onPressureDemotion(listener: (event: PressureDemotionEvent) => void): () => void;
+    /**
+     * Manually trigger demotions.
+     *
+     * @param options - Demotion options specifying counts
+     * @returns Result of the demotion operation
+     */
+    triggerDemotion(options: TriggerDemotionOptions): Promise<TriggerDemotionResult>;
+    /**
+     * 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 handlePressureDemotion;
+    /**
+     * Start periodic memory monitoring.
+     *
+     * Checks memory pressure at the configured interval and takes
+     * automatic actions when thresholds are crossed.
+     */
+    startMonitoring(): void;
+    /**
+     * Stop periodic memory monitoring.
+     */
+    stopMonitoring(): void;
+    /**
+     * Get current memory statistics.
+     *
+     * @returns Current memory stats including pressure level
+     */
+    getMemoryStats(): MemoryStats;
+    /**
+     * Get current memory pressure level.
+     *
+     * This calculates the level based on current heap usage,
+     * not the cached lastPressureLevel.
+     *
+     * @returns Current pressure level
+     */
+    getPressureLevel(): MemoryPressureLevel;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    checkMemoryPressure(): Promise<MemoryPressureEvent | null>;
+    /**
+     * Handle sustained pressure alerts.
+     */
+    private handleSustainedPressure;
+    /**
+     * Handle recovery from elevated pressure.
+     */
+    private handleRecovery;
+    /**
+     * Exit recovery mode when pressure rises.
+     */
+    private exitRecoveryMode;
+    /**
+     * Handle actions for elevated pressure levels.
+     * Optimized: Uses adaptive GC timing based on pressure level and memory growth rate.
+     */
+    private handleElevatedPressure;
+    /**
+     * 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;
+    /**
+     * Evict cache entries based on pressure level.
+     */
+    private evictCache;
+    /**
+     * Update pressure duration tracking.
+     */
+    private updatePressureDuration;
+    /**
+     * 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
+     */
+    unloadLeastImportantExtension(): Promise<MemoryPressureActionResult>;
+    /**
+     * Get list of extensions unloaded due to memory pressure.
+     */
+    getUnloadedExtensions(): string[];
+    /**
+     * Check if an extension was unloaded due to memory pressure.
+     */
+    wasExtensionUnloaded(extensionName: string): boolean;
+    /**
+     * Clear the list of unloaded extensions.
+     */
+    clearUnloadedExtensions(): void;
+    /**
+     * 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
+     */
+    requestGC(): Promise<GCResult>;
+    /**
+     * Get aggregated GC metrics.
+     * Optimized: Uses ring buffer's toArray() for efficient conversion.
+     */
+    getGCMetrics(): GCMetrics;
+    /**
+     * 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;
+    /**
+     * Update smoothed pressure state using EMA.
+     * This provides noise-resistant pressure tracking.
+     */
+    private updateSmoothedState;
+    /**
+     * Get the smoothed pressure state.
+     * Useful for observability and debugging.
+     */
+    getSmoothedPressureState(): SmoothedPressureState;
+    /**
+     * Get the smoothed pressure level (EMA-based).
+     * This is less sensitive to momentary spikes than raw pressure level.
+     */
+    getSmoothedPressureLevel(): MemoryPressureLevel;
+    /**
+     * Check if pressure is volatile (high variance in recent samples).
+     * Useful for deciding whether to take aggressive action.
+     */
+    isPressureVolatile(): boolean;
+    /**
+     * 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;
+    };
+    /**
+     * Get pressure level using adaptive thresholds.
+     * This provides more intelligent pressure detection based on memory behavior.
+     */
+    getAdaptivePressureLevel(): MemoryPressureLevel;
+    /**
+     * Get metrics history.
+     * Returns a copy of the samples array.
+     */
+    getMetricsHistory(): MetricsHistory;
+    /**
+     * 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;
+    /**
+     * Classify growth trend based on bytes per second.
+     */
+    private classifyGrowthTrend;
+    /**
+     * 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;
+    /**
+     * Get time spent at each pressure level.
+     */
+    getPressureDurations(): PressureDurations;
+    /**
+     * Export metrics in Prometheus format.
+     * Enhanced: Includes heuristics metrics for better observability.
+     */
+    exportPrometheusMetrics(): string;
+    /**
+     * Export metrics in JSON format.
+     * Optimized: Calculates aggregates in a single pass.
+     * Enhanced: Includes heuristics data for observability.
+     */
+    exportJSONMetrics(): JSONMetricsExport;
+    /**
+     * Execute a query with memory pressure guards.
+     *
+     * - Pauses at critical pressure (with timeout)
+     * - Rejects at OOM pressure
+     * - Enforces hard limits if configured
+     */
+    guardedQuery<T>(sql: string, params: unknown[], options?: {
+        estimatedResultBytes?: number;
+    }): Promise<{
+        rows: T[];
+        fields: unknown[];
+    }>;
+    /**
+     * Wait for pressure to drop with timeout.
+     */
+    private waitForPressureRelief;
+    /**
+     * Get status of a query promise.
+     */
+    getQueryStatus(queryPromise: Promise<unknown>): 'paused' | 'executing' | 'completed' | 'unknown';
+    /**
+     * Pause an operation and return a handle.
+     */
+    pauseOperation(id: string): PausedOperation;
+    /**
+     * Resume all paused operations.
+     */
+    resumePausedOperations(): void;
+    /**
+     * Enforce a hard allocation limit.
+     *
+     * Throws if the allocation would exceed the memory limit.
+     */
+    guardedAllocation(bytes: number): Promise<{
+        allowed: boolean;
+    }>;
+    /**
+     * Check if a feature is currently enabled.
+     */
+    isFeatureEnabled(feature: string): boolean;
+    /**
+     * Get count of enabled features.
+     */
+    getEnabledFeatureCount(): number;
+    /**
+     * Disable features under pressure.
+     */
+    private disableFeaturesUnderPressure;
+    /**
+     * Re-enable features after recovery.
+     */
+    private enableFeaturesAfterRecovery;
+    /**
+     * Check if manager is in recovery mode.
+     */
+    isInRecoveryMode(): boolean;
+    /**
+     * Get recovery progress (0.0 to 1.0).
+     */
+    getRecoveryProgress(): number;
+    /**
+     * Start gradual recovery of features.
+     */
+    startGradualRecovery(): Promise<void>;
+    /**
+     * Pause gradual recovery.
+     */
+    pauseGradualRecovery(): void;
+    /**
+     * Check if recovery is paused.
+     */
+    isRecoveryPaused(): boolean;
+    /**
+     * Add a memory pressure event listener.
+     *
+     * @param listener - Callback for pressure events
+     * @returns Unsubscribe function
+     */
+    onPressureChange(listener: MemoryPressureListener): () => void;
+    /**
+     * Get current listener count.
+     */
+    getListenerCount(): number;
+    /**
+     * Add a memory spike listener.
+     *
+     * @param listener - Callback for spike events
+     * @returns Unsubscribe function
+     */
+    onMemorySpike(listener: (spike: MemorySpikeEvent) => void): () => void;
+    /**
+     * Add a recovery event listener.
+     *
+     * @param listener - Callback for recovery events
+     * @returns Unsubscribe function
+     */
+    onRecovery(listener: (event: RecoveryEvent) => void): () => void;
+    /**
+     * Emit a pressure event to all listeners.
+     */
+    private emitPressureEvent;
+    /**
+     * Simulate heap growth for testing.
+     * @internal
+     */
+    _simulateHeapGrowth(bytes: number): void;
+    /**
+     * Set current heap usage for testing.
+     * @internal
+     */
+    _setCurrentHeapUsage(bytes: number): void;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * Create a memory pressure manager with default configuration.
+ *
+ * @param config - Optional configuration overrides
+ * @returns Configured MemoryPressureManager instance
+ */
+export declare function createMemoryPressureManager(config?: ExtendedMemoryPressureConfig): MemoryPressureManager;
+//# sourceMappingURL=memory-pressure.d.ts.map