@dotdo/postgres 0.1.0

package/src/pglite/cold-start-optimizer.ts

@@ -0,0 +1,1895 @@
+/**
+ * Cold Start Optimizer for PGLite in Cloudflare Workers
+ *
+ * This module provides optimized initialization strategies for PGLite instances
+ * running in Cloudflare Workers' Durable Objects environment, where cold starts
+ * can significantly impact user experience.
+ *
+ * ## Overview
+ *
+ * Cloudflare Workers have ephemeral execution contexts that can be evicted at any
+ * time. When a new request arrives after eviction, a "cold start" occurs requiring
+ * full re-initialization of PGLite. This module implements several strategies to
+ * minimize cold start latency:
+ *
+ * ### Optimization Strategies
+ *
+ * 1. **WASM Caching** - Module-level singleton caching allows warm starts within
+ *    the same isolate by reusing already-initialized PGLite instances.
+ *
+ * 2. **Parallel Data Fetching** - While WASM prepares (near-instant for pre-compiled
+ *    modules), data is fetched from storage tiers in parallel:
+ *    - HOT tier: Synchronous DO SQLite (fastest)
+ *    - WARM tier: Cloudflare Cache API (FREE!)
+ *    - COLD tier: R2 object storage (durable)
+ *
+ * 3. **Lazy Initialization** - PGLite initialization is deferred until the first
+ *    query, allowing the DO to respond quickly to health checks and metadata requests.
+ *
+ * 4. **Memory Optimization** - Buffer pooling reduces allocation overhead and helps
+ *    stay within Workers' 128MB memory limit.
+ *
+ * 5. **Pre-warming** - After initialization, common queries are executed to warm
+ *    PostgreSQL's query planner cache.
+ *
+ * ## Performance Targets
+ *
+ * | Metric | p50 Target | p95 Target | Notes |
+ * |--------|------------|------------|-------|
+ * | WASM module loading | < 300ms | < 500ms | Near-zero for pre-compiled static imports |
+ * | PGLite initialization | < 500ms | < 800ms | Includes filesystem setup |
+ * | First query latency | < 20ms | < 50ms | After prewarm queries |
+ * | **Total cold start** | **< 800ms** | **< 1500ms** | End-to-end including prewarm |
+ *
+ * ## Architecture
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                    Cold Start Optimizer                         │
+ * ├─────────────────────────────────────────────────────────────────┤
+ * │                                                                 │
+ * │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+ * │  │ WASM Cache  │    │ Parallel    │    │ Lazy Init   │         │
+ * │  │ (Isolate)   │────│ Data Fetch  │────│ Pattern     │         │
+ * │  └─────────────┘    └─────────────┘    └─────────────┘         │
+ * │         │                  │                  │                 │
+ * │         ▼                  ▼                  ▼                 │
+ * │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+ * │  │ Warm Start  │    │ HOT/WARM/   │    │ First Query │         │
+ * │  │ Detection   │    │ COLD Tiers  │    │ Trigger     │         │
+ * │  └─────────────┘    └─────────────┘    └─────────────┘         │
+ * │                                                                 │
+ * │                    ┌─────────────┐                              │
+ * │                    │ Buffer Pool │                              │
+ * │                    │ (Memory)    │                              │
+ * │                    └─────────────┘                              │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import pgliteWasm from './pglite.wasm'
+ * import { createColdStartOptimizer } from '@dotdo/postgres/pglite'
+ *
+ * // Create optimizer with tiered storage
+ * const optimizer = createColdStartOptimizer({
+ *   wasmModule: pgliteWasm,
+ *   cacheLayer: myCacheLayer,
+ *   warmCacheKey: `db:${databaseId}`,
+ *   r2Layer: myR2Layer,
+ *   coldStorageKey: `databases/${databaseId}/data.tar`,
+ *   lazy: true,
+ *   prewarm: true,
+ * })
+ *
+ * // First query triggers initialization
+ * const result = await optimizer.query('SELECT * FROM users')
+ *
+ * // Check performance metrics
+ * const metrics = optimizer.getMetrics()
+ * console.log(`Cold start: ${metrics?.totalMs}ms from ${metrics?.dataSource}`)
+ * ```
+ *
+ * @module pglite/cold-start-optimizer
+ * @see {@link ColdStartManager} for DO lifecycle integration
+ * @see {@link TieredVFS} for the underlying storage system
+ * @issue postgres-w6l6
+ */
+
+import type { PGlite, PGliteOptions } from '@dotdo/pglite'
+import type { CacheLayer } from './cache-layer'
+import type { R2StorageLayer } from './r2-layer'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Cold start initialization phases
+ *
+ * The optimizer progresses through these phases during initialization:
+ *
+ * ```
+ * not_started → wasm_loading → parallel_loading → pglite_init → ready
+ *                                                      ↓
+ *                                                    error
+ * ```
+ *
+ * - `not_started`: Initial state, no initialization attempted
+ * - `wasm_loading`: Preparing WASM module (near-instant for pre-compiled)
+ * - `data_fetching`: Fetching data from a single tier (deprecated, use parallel_loading)
+ * - `parallel_loading`: Fetching data from HOT/WARM/COLD tiers in parallel
+ * - `pglite_init`: Creating PGLite instance and running prewarm queries
+ * - `ready`: Initialization complete, ready for queries
+ * - `error`: Initialization failed
+ *
+ * @example
+ * ```typescript
+ * optimizer.onPhaseChange((phase, metrics) => {
+ *   console.log(`Phase: ${phase}, elapsed: ${metrics.totalMs}ms`)
+ * })
+ * ```
+ */
+export type ColdStartPhase =
+  | 'not_started'
+  | 'wasm_loading'
+  | 'data_fetching'
+  | 'parallel_loading'
+  | 'pglite_init'
+  | 'ready'
+  | 'error'
+
+/**
+ * Detailed phase timing breakdown for profiling
+ */
+export interface PhaseTimingBreakdown {
+  /** Phase name */
+  phase: ColdStartPhase
+  /** Start timestamp (high-resolution) */
+  startTime: number
+  /** End timestamp (high-resolution) */
+  endTime: number
+  /** Duration in milliseconds */
+  durationMs: number
+  /** Any sub-phase timings */
+  subPhases?: Array<{
+    name: string
+    startTime: number
+    endTime: number
+    durationMs: number
+  }>
+}
+
+/**
+ * WASM loading strategy comparison metrics
+ */
+export interface WasmStrategyMetrics {
+  /** Strategy name */
+  strategy: 'static_import' | 'dynamic_import' | 'streaming' | 'cached'
+  /** Time to obtain the WASM module */
+  moduleLoadMs: number
+  /** Time to instantiate the module */
+  instantiateMs: number
+  /** Total WASM preparation time */
+  totalMs: number
+  /** Whether the module was from cache */
+  fromCache: boolean
+  /** Module size in bytes (if known) */
+  moduleSizeBytes?: number
+}
+
+/**
+ * Detailed timing metrics for cold start optimization
+ *
+ * These metrics provide comprehensive visibility into cold start performance,
+ * enabling identification of bottlenecks and performance regression detection.
+ *
+ * ## Key Metrics
+ *
+ * | Metric | Description | Target |
+ * |--------|-------------|--------|
+ * | `totalMs` | End-to-end cold start time | < 1500ms (p95) |
+ * | `wasmPrepMs` | WASM module preparation | < 10ms (pre-compiled) |
+ * | `dataFetchMs` | Data fetch from storage tier | < 500ms (p95) |
+ * | `pgliteInitMs` | PGLite instance creation | < 800ms (p95) |
+ * | `firstQueryMs` | Prewarm query execution | < 50ms (p95) |
+ *
+ * ## Interpreting Results
+ *
+ * - High `dataFetchMs` → Consider promoting data to a faster tier
+ * - High `pgliteInitMs` → Consider using the tiny PGLite variant
+ * - `isWarmStart: true` → Instance was reused from cache (best case)
+ *
+ * @example
+ * ```typescript
+ * const metrics = optimizer.getMetrics()
+ * if (metrics) {
+ *   console.log(`Total: ${metrics.totalMs}ms`)
+ *   console.log(`Source: ${metrics.dataSource}`)
+ *   console.log(`Warm start: ${metrics.isWarmStart}`)
+ *   console.log(`Data size: ${metrics.dataSizeBytes} bytes`)
+ * }
+ * ```
+ */
+export interface ColdStartMetrics {
+  /** Total cold start time in milliseconds */
+  totalMs: number
+  /** WASM module preparation time (usually near-zero for pre-compiled) */
+  wasmPrepMs: number
+  /** Data fetch time from storage tier */
+  dataFetchMs: number
+  /** Overlap time saved by parallel loading */
+  parallelSavingsMs: number
+  /** PGLite instance creation time */
+  pgliteInitMs: number
+  /** First query time (query planner warmup) */
+  firstQueryMs: number
+  /** Data source that provided the filesystem bundle */
+  dataSource: 'hot' | 'warm' | 'cold' | 'empty'
+  /** Size of data loaded in bytes */
+  dataSizeBytes: number
+  /** Whether this was a warm start (cached instance) */
+  isWarmStart: boolean
+  /** Current phase */
+  phase: ColdStartPhase
+  /** Timestamp when cold start began */
+  startedAt: number
+  /** Timestamp when cold start completed */
+  completedAt: number
+  /** Memory usage at completion (if available) */
+  memoryUsedMB?: number
+  /** Detailed phase timing breakdown for profiling */
+  phaseBreakdown?: PhaseTimingBreakdown[]
+  /** WASM strategy metrics (for comparison) */
+  wasmStrategy?: WasmStrategyMetrics
+  /** Individual tier fetch timings */
+  tierFetchTimings?: {
+    hot?: { attempted: boolean; durationMs: number; success: boolean }
+    warm?: { attempted: boolean; durationMs: number; success: boolean }
+    cold?: { attempted: boolean; durationMs: number; success: boolean }
+  }
+  /** Dynamic import time for @dotdo/pglite module */
+  pgliteImportMs?: number
+  /** Prewarm query individual timings */
+  prewarmTimings?: Array<{ query: string; durationMs: number }>
+}
+
+/**
+ * Configuration for cold start optimization
+ *
+ * This configuration controls how the optimizer initializes PGLite and
+ * fetches data from tiered storage.
+ *
+ * ## Required Configuration
+ *
+ * - `wasmModule`: Pre-compiled WASM module (must be statically imported)
+ *
+ * ## Storage Tiers (in priority order)
+ *
+ * 1. **HOT tier** (`hotData`): Data already in memory from DO SQLite.
+ *    Synchronous access, fastest possible. If provided, skips all other tiers.
+ *
+ * 2. **WARM tier** (`cacheLayer` + `warmCacheKey`): Cloudflare Cache API.
+ *    FREE and fast (~10-50ms). Data is cached at edge locations.
+ *
+ * 3. **COLD tier** (`r2Layer`/`r2Bucket` + `coldStorageKey`): R2 storage.
+ *    Durable but slower (~100-500ms). Used for persistence and recovery.
+ *
+ * ## Initialization Behavior
+ *
+ * - `lazy: true` (default): Defer initialization until first query
+ * - `lazy: false`: Initialize immediately when optimizer is created
+ * - `prewarm: true` (default): Run warmup queries after initialization
+ *
+ * @example
+ * ```typescript
+ * // Minimal configuration (empty database)
+ * const config: ColdStartConfig = {
+ *   wasmModule: pgliteWasm,
+ * }
+ *
+ * // Full tiered storage configuration
+ * const config: ColdStartConfig = {
+ *   wasmModule: pgliteWasm,
+ *   cacheLayer: myCacheLayer,
+ *   warmCacheKey: `db:${databaseId}`,
+ *   r2Bucket: env.R2_BUCKET,
+ *   coldStorageKey: `databases/${databaseId}/data.tar`,
+ *   lazy: true,
+ *   prewarm: true,
+ *   debug: true,
+ *   onReady: (metrics) => {
+ *     console.log(`Initialized in ${metrics.totalMs}ms`)
+ *   },
+ * }
+ * ```
+ */
+export interface ColdStartConfig {
+  /**
+   * Pre-compiled WASM module
+   * MUST be statically imported: import pgliteWasm from './pglite.wasm'
+   */
+  wasmModule: WebAssembly.Module
+
+  /**
+   * HOT tier: Data from DO SQLite (synchronous)
+   * Highest priority - if provided, skips all other tiers
+   */
+  hotData?: ArrayBuffer | Uint8Array
+
+  /**
+   * WARM tier: Cache layer for Cloudflare Cache API
+   */
+  cacheLayer?: CacheLayer
+
+  /**
+   * Key for warm cache lookup
+   */
+  warmCacheKey?: string
+
+  /**
+   * COLD tier: R2 storage layer
+   */
+  r2Layer?: R2StorageLayer
+
+  /**
+   * COLD tier: Raw R2 bucket (alternative to r2Layer)
+   */
+  r2Bucket?: R2Bucket
+
+  /**
+   * Key for cold storage lookup
+   */
+  coldStorageKey?: string
+
+  /**
+   * Enable lazy initialization (default: true)
+   * When true, PGLite initializes on first query, not construction
+   */
+  lazy?: boolean
+
+  /**
+   * Enable pre-warming queries after initialization (default: true)
+   * Runs simple queries to warm up the query planner
+   */
+  prewarm?: boolean
+
+  /**
+   * Custom pre-warm queries to run after initialization
+   */
+  prewarmQueries?: string[]
+
+  /**
+   * Timeout for cold fetch in milliseconds (default: 5000)
+   */
+  coldFetchTimeoutMs?: number
+
+  /**
+   * Database name for PGLite (default: 'postgres')
+   */
+  database?: string
+
+  /**
+   * Additional PGLite options
+   */
+  pgliteOptions?: Partial<PGliteOptions>
+
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean
+
+  /**
+   * Callback when initialization phase changes
+   */
+  onPhaseChange?: (phase: ColdStartPhase, metrics: Partial<ColdStartMetrics>) => void
+
+  /**
+   * Callback when initialization completes
+   */
+  onReady?: (metrics: ColdStartMetrics) => void
+
+  /**
+   * Callback when an error occurs
+   */
+  onError?: (error: Error, phase: ColdStartPhase) => void
+}
+
+/**
+ * Result from cold start optimization
+ */
+export interface ColdStartResult {
+  /** The initialized PGLite instance */
+  pglite: PGlite
+  /** Detailed metrics from initialization */
+  metrics: ColdStartMetrics
+}
+
+/**
+ * Cold start optimizer interface
+ *
+ * This interface provides methods for managing PGLite lifecycle with
+ * optimized cold start handling. The optimizer handles:
+ *
+ * - Lazy initialization (deferred until first query)
+ * - WASM instance caching for warm starts
+ * - Parallel data fetching from tiered storage
+ * - Pre-warming queries for query planner cache
+ *
+ * ## Lifecycle Methods
+ *
+ * | Method | Description |
+ * |--------|-------------|
+ * | `getInstance()` | Get PGLite instance, initializing if needed |
+ * | `initialize()` | Force initialization (useful for pre-warming) |
+ * | `query()` | Execute query, auto-initializing if lazy |
+ * | `close()` | Release resources and remove from cache |
+ *
+ * ## Status Methods
+ *
+ * | Method | Description |
+ * |--------|-------------|
+ * | `isReady()` | Check if initialization is complete |
+ * | `isInitializing()` | Check if initialization is in progress |
+ * | `getPhase()` | Get current initialization phase |
+ * | `getMetrics()` | Get detailed timing metrics |
+ *
+ * @example
+ * ```typescript
+ * const optimizer = createColdStartOptimizer(config)
+ *
+ * // Lazy initialization - first query triggers init
+ * const result = await optimizer.query('SELECT 1')
+ *
+ * // Check status
+ * console.log(`Ready: ${optimizer.isReady()}`)
+ * console.log(`Phase: ${optimizer.getPhase()}`)
+ *
+ * // Get metrics after initialization
+ * const metrics = optimizer.getMetrics()
+ * if (metrics) {
+ *   console.log(`Cold start: ${metrics.totalMs}ms`)
+ *   console.log(`Data source: ${metrics.dataSource}`)
+ * }
+ *
+ * // Clean up when done
+ * await optimizer.close()
+ * ```
+ */
+export interface ColdStartOptimizer {
+  /**
+   * Get the PGLite instance
+   *
+   * If lazy initialization is enabled (default), this triggers initialization
+   * on first call. Subsequent calls return the cached instance.
+   *
+   * @returns The initialized PGLite instance
+   * @throws Error if the optimizer is closed or initialization failed
+   */
+  getInstance(): Promise<PGlite>
+
+  /**
+   * Check if PGLite is ready for queries
+   *
+   * @returns true if initialization is complete and queries can be executed
+   */
+  isReady(): boolean
+
+  /**
+   * Check if initialization is currently in progress
+   *
+   * @returns true if initialization has started but not completed
+   */
+  isInitializing(): boolean
+
+  /**
+   * Get the current initialization phase
+   *
+   * @returns The current phase of the cold start process
+   */
+  getPhase(): ColdStartPhase
+
+  /**
+   * Get detailed timing metrics from initialization
+   *
+   * Returns null if initialization has not completed.
+   *
+   * @returns Detailed metrics or null if not yet initialized
+   */
+  getMetrics(): ColdStartMetrics | null
+
+  /**
+   * Force initialization
+   *
+   * Use this to pre-warm the optimizer before the first query.
+   * Has no effect if already initialized.
+   *
+   * @example
+   * ```typescript
+   * // Pre-warm in DO constructor
+   * this.pgliteInitPromise = optimizer.initialize()
+   *
+   * // Later in fetch handler
+   * await this.pgliteInitPromise
+   * const result = await optimizer.query('SELECT 1')
+   * ```
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Execute a SQL query
+   *
+   * Auto-initializes if lazy mode is enabled and not yet initialized.
+   *
+   * @param sql - The SQL query to execute
+   * @param params - Optional query parameters
+   * @returns Query result with rows
+   * @throws Error if the optimizer is closed or query fails
+   */
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<{ rows: T[] }>
+
+  /**
+   * Close the optimizer and release resources
+   *
+   * Removes the PGLite instance from the warm start cache and closes
+   * the underlying database connection.
+   */
+  close(): Promise<void>
+}
+
+// ============================================================================
+// WASM Caching Strategy
+// ============================================================================
+
+/**
+ * Module-level cache for WASM initialization state
+ *
+ * In Cloudflare Workers, isolates persist across requests within the same
+ * execution context. This cache enables "warm starts" by reusing already-
+ * initialized PGLite instances instead of performing a full cold start.
+ *
+ * ## How Warm Starts Work
+ *
+ * 1. First request to a DO performs cold start (full initialization)
+ * 2. Initialized PGLite is cached with database-specific key
+ * 3. Subsequent requests find cached instance and reuse it
+ * 4. Cache is cleared when `close()` is called or isolate is evicted
+ *
+ * ## Cache Key Generation
+ *
+ * Keys are generated from: `${database}:${warmCacheKey}:${coldStorageKey}`
+ * This ensures different databases don't share instances.
+ *
+ * ## Memory Considerations
+ *
+ * Each cached instance uses ~64MB. With Workers' 128MB limit:
+ * - Only one instance can be effectively cached per isolate
+ * - Multiple databases should use ColdStartManager for lifecycle
+ *
+ * @internal
+ */
+interface WasmCacheEntry {
+  /** The initialized PGLite instance */
+  pglite: PGlite
+  /** When this entry was created */
+  createdAt: number
+  /** Metrics from initial cold start */
+  metrics: ColdStartMetrics
+  /** Number of times this cached instance was reused */
+  reuseCount: number
+}
+
+/**
+ * Isolate-level WASM cache
+ *
+ * This Map persists across requests within the same Worker isolate.
+ * When the isolate is evicted, the cache is cleared automatically.
+ *
+ * @internal
+ */
+const wasmCache = new Map<string, WasmCacheEntry>()
+
+/**
+ * Generate a cache key for WASM instance caching
+ *
+ * The key should uniquely identify the WASM module and configuration.
+ */
+function generateCacheKey(config: ColdStartConfig): string {
+  // Use database name as primary key differentiator
+  const dbName = config.database ?? 'postgres'
+  // Include warm/cold keys to differentiate data sources
+  const warmKey = config.warmCacheKey ?? ''
+  const coldKey = config.coldStorageKey ?? ''
+  return `${dbName}:${warmKey}:${coldKey}`
+}
+
+/**
+ * Get cached WASM instance if available
+ */
+function getCachedInstance(cacheKey: string): WasmCacheEntry | null {
+  const entry = wasmCache.get(cacheKey)
+  if (entry) {
+    entry.reuseCount++
+    return entry
+  }
+  return null
+}
+
+/**
+ * Cache a WASM instance for warm starts
+ */
+function cacheInstance(cacheKey: string, entry: WasmCacheEntry): void {
+  wasmCache.set(cacheKey, entry)
+}
+
+/**
+ * Clear all cached WASM instances
+ *
+ * Use this function to:
+ * - Reset state between tests
+ * - Force cold starts for benchmarking
+ * - Clear memory when switching databases
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * beforeEach(() => {
+ *   clearWasmCache()
+ * })
+ *
+ * // Force cold start for benchmarking
+ * clearWasmCache()
+ * const start = performance.now()
+ * await optimizer.initialize()
+ * const coldStartMs = performance.now() - start
+ * ```
+ */
+export function clearWasmCache(): void {
+  wasmCache.clear()
+}
+
+/**
+ * Get WASM cache statistics
+ *
+ * Returns information about cached PGLite instances for monitoring
+ * and debugging purposes.
+ *
+ * @returns Object containing:
+ *   - `size`: Number of cached instances
+ *   - `entries`: Array of cache entries with reuse count and age
+ *
+ * @example
+ * ```typescript
+ * const stats = getWasmCacheStats()
+ * console.log(`Cached instances: ${stats.size}`)
+ *
+ * for (const entry of stats.entries) {
+ *   console.log(`${entry.key}: ${entry.reuseCount} reuses, ${entry.ageMs}ms old`)
+ * }
+ * ```
+ */
+export function getWasmCacheStats(): {
+  size: number
+  entries: Array<{ key: string; reuseCount: number; ageMs: number }>
+} {
+  const now = Date.now()
+  const entries: Array<{ key: string; reuseCount: number; ageMs: number }> = []
+
+  for (const [key, entry] of wasmCache.entries()) {
+    entries.push({
+      key,
+      reuseCount: entry.reuseCount,
+      ageMs: now - entry.createdAt,
+    })
+  }
+
+  return { size: wasmCache.size, entries }
+}
+
+// ============================================================================
+// Parallel Loading Strategy
+// ============================================================================
+
+/**
+ * Result from parallel data fetch
+ */
+interface ParallelFetchResult {
+  data: Uint8Array | null
+  source: 'hot' | 'warm' | 'cold' | 'empty'
+  fetchTimeMs: number
+  /** Individual tier timing details */
+  tierTimings?: {
+    hot?: { attempted: boolean; durationMs: number; success: boolean }
+    warm?: { attempted: boolean; durationMs: number; success: boolean }
+    cold?: { attempted: boolean; durationMs: number; success: boolean }
+  }
+}
+
+/**
+ * Fetch data from tiered storage in parallel with WASM preparation
+ *
+ * This function implements the parallel loading pattern:
+ * - WASM module is already pre-compiled (zero prep time)
+ * - Data fetch from warm/cold tiers happens during that "zero time"
+ * - We race warm and cold fetches to get data ASAP
+ */
+async function parallelFetchData(
+  config: ColdStartConfig,
+  debug: (msg: string) => void
+): Promise<ParallelFetchResult> {
+  const startTime = performance.now()
+  const tierTimings: ParallelFetchResult['tierTimings'] = {}
+
+  // Priority 1: Hot data (synchronous, already in memory)
+  if (config.hotData) {
+    const hotStart = performance.now()
+    debug('Using hot data from DO SQLite')
+    const data =
+      config.hotData instanceof Uint8Array
+        ? config.hotData
+        : new Uint8Array(config.hotData)
+    const hotDuration = performance.now() - hotStart
+    tierTimings.hot = { attempted: true, durationMs: hotDuration, success: true }
+    return {
+      data,
+      source: 'hot',
+      fetchTimeMs: performance.now() - startTime,
+      tierTimings,
+    }
+  }
+
+  // Set up parallel fetches for warm and cold tiers
+  interface TierFetchResult extends ParallelFetchResult {
+    tierType: 'warm' | 'cold'
+  }
+  const fetchPromises: Promise<TierFetchResult>[] = []
+
+  // Warm tier fetch (Cloudflare Cache - FREE!)
+  if (config.cacheLayer && config.warmCacheKey) {
+    const warmPromise = (async (): Promise<TierFetchResult> => {
+      const warmStart = performance.now()
+      try {
+        const data = await config.cacheLayer!.get(config.warmCacheKey!)
+        const durationMs = performance.now() - warmStart
+        if (data) {
+          debug(`Warm cache hit: ${data.length} bytes in ${durationMs.toFixed(2)}ms`)
+          return {
+            data,
+            source: 'warm',
+            fetchTimeMs: durationMs,
+            tierType: 'warm',
+            tierTimings: { warm: { attempted: true, durationMs, success: true } },
+          }
+        }
+        return {
+          data: null,
+          source: 'warm',
+          fetchTimeMs: durationMs,
+          tierType: 'warm',
+          tierTimings: { warm: { attempted: true, durationMs, success: false } },
+        }
+      } catch (err) {
+        const durationMs = performance.now() - warmStart
+        debug(`Warm cache error after ${durationMs.toFixed(2)}ms: ${err}`)
+        return {
+          data: null,
+          source: 'warm',
+          fetchTimeMs: durationMs,
+          tierType: 'warm',
+          tierTimings: { warm: { attempted: true, durationMs, success: false } },
+        }
+      }
+    })()
+    fetchPromises.push(warmPromise)
+  }
+
+  // Cold tier fetch (R2 - durable storage)
+  if ((config.r2Layer || config.r2Bucket) && config.coldStorageKey) {
+    const coldPromise = (async (): Promise<TierFetchResult> => {
+      const coldStart = performance.now()
+      const timeout = config.coldFetchTimeoutMs ?? 5000
+
+      try {
+        let data: Uint8Array | null = null
+
+        if (config.r2Layer) {
+          // Use R2StorageLayer with timeout
+          data = await Promise.race([
+            config.r2Layer.get(config.coldStorageKey!),
+            new Promise<null>((_, reject) =>
+              setTimeout(() => reject(new Error('Cold fetch timeout')), timeout)
+            ),
+          ])
+        } else if (config.r2Bucket) {
+          // Use raw R2Bucket with timeout
+          const obj = await Promise.race([
+            config.r2Bucket.get(config.coldStorageKey!),
+            new Promise<null>((_, reject) =>
+              setTimeout(() => reject(new Error('Cold fetch timeout')), timeout)
+            ),
+          ])
+          if (obj) {
+            data = new Uint8Array(await obj.arrayBuffer())
+          }
+        }
+
+        const durationMs = performance.now() - coldStart
+        if (data) {
+          debug(`Cold storage hit: ${data.length} bytes in ${durationMs.toFixed(2)}ms`)
+          return {
+            data,
+            source: 'cold',
+            fetchTimeMs: durationMs,
+            tierType: 'cold',
+            tierTimings: { cold: { attempted: true, durationMs, success: true } },
+          }
+        }
+        return {
+          data: null,
+          source: 'cold',
+          fetchTimeMs: durationMs,
+          tierType: 'cold',
+          tierTimings: { cold: { attempted: true, durationMs, success: false } },
+        }
+      } catch (err) {
+        const durationMs = performance.now() - coldStart
+        debug(`Cold storage error after ${durationMs.toFixed(2)}ms: ${err}`)
+        return {
+          data: null,
+          source: 'cold',
+          fetchTimeMs: durationMs,
+          tierType: 'cold',
+          tierTimings: { cold: { attempted: true, durationMs, success: false } },
+        }
+      }
+    })()
+    fetchPromises.push(coldPromise)
+  }
+
+  // Execute fetches in parallel, return first successful result
+  if (fetchPromises.length > 0) {
+    debug(`Starting ${fetchPromises.length} parallel fetches`)
+
+    // Use Promise.all to get all results, then pick the best one
+    // (We want metrics from all attempts, not just the winner)
+    const results = await Promise.all(fetchPromises)
+
+    // Merge all tier timings
+    for (const result of results) {
+      if (result.tierTimings) {
+        Object.assign(tierTimings, result.tierTimings)
+      }
+    }
+
+    // Prefer warm over cold (warm is faster and FREE)
+    const warmResult = results.find((r) => r.source === 'warm' && r.data)
+    if (warmResult?.data) {
+      return { ...warmResult, tierTimings }
+    }
+
+    const coldResult = results.find((r) => r.source === 'cold' && r.data)
+    if (coldResult?.data) {
+      return { ...coldResult, tierTimings }
+    }
+  }
+
+  // No data found anywhere
+  debug('No data found, returning empty')
+  return {
+    data: null,
+    source: 'empty',
+    fetchTimeMs: performance.now() - startTime,
+    tierTimings,
+  }
+}
+
+// ============================================================================
+// Lazy Initialization Pattern
+// ============================================================================
+
+/**
+ * Default pre-warm queries to run after initialization
+ *
+ * These queries warm up:
+ * - Query planner cache
+ * - System catalog cache
+ * - Connection state
+ */
+const DEFAULT_PREWARM_QUERIES = [
+  'SELECT 1', // Basic connectivity
+  'SELECT current_database()', // Database state
+  'SELECT version()', // System catalog access
+]
+
+/**
+ * Run pre-warm queries to optimize subsequent query latency
+ */
+async function runPrewarmQueries(
+  pglite: PGlite,
+  queries: string[],
+  debug: (msg: string) => void
+): Promise<number> {
+  const startTime = performance.now()
+
+  for (const sql of queries) {
+    try {
+      await pglite.query(sql)
+    } catch {
+      // Ignore errors in pre-warm queries (table might not exist, etc.)
+      debug(`Prewarm query failed (ignored): ${sql}`)
+    }
+  }
+
+  const durationMs = performance.now() - startTime
+  debug(`Prewarm completed: ${queries.length} queries in ${durationMs.toFixed(2)}ms`)
+  return durationMs
+}
+
+/**
+ * Run pre-warm queries with individual timing tracking
+ */
+async function runPrewarmQueriesWithTimings(
+  pglite: PGlite,
+  queries: string[],
+  debug: (msg: string) => void
+): Promise<Array<{ query: string; durationMs: number }>> {
+  const timings: Array<{ query: string; durationMs: number }> = []
+
+  for (const sql of queries) {
+    const queryStart = performance.now()
+    try {
+      await pglite.query(sql)
+    } catch {
+      // Ignore errors in pre-warm queries (table might not exist, etc.)
+      debug(`Prewarm query failed (ignored): ${sql}`)
+    }
+    const queryEnd = performance.now()
+    timings.push({ query: sql, durationMs: queryEnd - queryStart })
+  }
+
+  const totalMs = timings.reduce((sum, t) => sum + t.durationMs, 0)
+  debug(`Prewarm completed: ${queries.length} queries in ${totalMs.toFixed(2)}ms`)
+  return timings
+}
+
+// ============================================================================
+// Memory Allocation Optimization
+// ============================================================================
+
+/**
+ * Buffer pool for reducing memory allocation overhead
+ *
+ * ## Memory Constraints
+ *
+ * Cloudflare Workers have a 128MB memory limit. PGLite uses approximately:
+ * - ~15MB for WASM + data + JS runtime
+ * - ~16MB for shared_buffers
+ * - ~16MB for WAL + buffers
+ * - ~10MB for PostgreSQL catalog/metadata
+ *
+ * This leaves ~71MB for queries, results, and runtime operations.
+ *
+ * ## Buffer Pool Strategy
+ *
+ * Pre-allocated buffers reduce allocation overhead during query execution:
+ *
+ * | Size | Bytes | Use Case |
+ * |------|-------|----------|
+ * | small | 4KB | Small operations, metadata |
+ * | medium | 64KB | Typical query results |
+ * | large | 1MB | Large result sets, bulk operations |
+ *
+ * ## Usage Pattern
+ *
+ * ```typescript
+ * const buffer = getPooledBuffer('medium')
+ * try {
+ *   // Use buffer for operation
+ *   const view = new Uint8Array(buffer)
+ *   // ... process data
+ * } finally {
+ *   returnPooledBuffer(buffer, 'medium')
+ * }
+ * ```
+ *
+ * @internal
+ */
+interface BufferPool {
+  small: ArrayBuffer | null // 4KB for small operations
+  medium: ArrayBuffer | null // 64KB for typical queries
+  large: ArrayBuffer | null // 1MB for large result sets
+}
+
+/**
+ * Buffer pool for reducing allocation overhead
+ * @internal
+ */
+const bufferPool: BufferPool = {
+  small: null,
+  medium: null,
+  large: null,
+}
+
+/**
+ * Get a buffer from the pool or allocate a new one
+ *
+ * Buffers are returned from the pool if available, otherwise a new
+ * buffer is allocated. This reduces allocation overhead for repeated
+ * operations of similar size.
+ *
+ * @param size - Buffer size category: 'small' (4KB), 'medium' (64KB), or 'large' (1MB)
+ * @returns ArrayBuffer of the specified size
+ *
+ * @example
+ * ```typescript
+ * const buffer = getPooledBuffer('medium') // 64KB
+ * const view = new Uint8Array(buffer)
+ * // Use the buffer...
+ * returnPooledBuffer(buffer, 'medium')
+ * ```
+ */
+export function getPooledBuffer(
+  size: 'small' | 'medium' | 'large'
+): ArrayBuffer {
+  const sizes = { small: 4096, medium: 65536, large: 1048576 }
+
+  if (bufferPool[size]) {
+    const buffer = bufferPool[size]!
+    bufferPool[size] = null
+    return buffer
+  }
+
+  return new ArrayBuffer(sizes[size])
+}
+
+/**
+ * Return a buffer to the pool for reuse
+ *
+ * Only returns the buffer if it hasn't been detached (transferred).
+ * Detached buffers have byteLength of 0.
+ *
+ * @param buffer - The buffer to return
+ * @param size - The size category of the buffer
+ *
+ * @example
+ * ```typescript
+ * const buffer = getPooledBuffer('small')
+ * // Use buffer...
+ * returnPooledBuffer(buffer, 'small')
+ * ```
+ */
+export function returnPooledBuffer(
+  buffer: ArrayBuffer,
+  size: 'small' | 'medium' | 'large'
+): void {
+  // Only pool if the buffer hasn't been transferred
+  if (buffer.byteLength > 0) {
+    bufferPool[size] = buffer
+  }
+}
+
+/**
+ * Clear the buffer pool
+ *
+ * Use this to:
+ * - Reset state between tests
+ * - Free memory when it's no longer needed
+ * - Prepare for a clean shutdown
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * afterEach(() => {
+ *   clearBufferPool()
+ * })
+ * ```
+ */
+export function clearBufferPool(): void {
+  bufferPool.small = null
+  bufferPool.medium = null
+  bufferPool.large = null
+}
+
+// ============================================================================
+// Cold Start Optimizer Implementation
+// ============================================================================
+
+/**
+ * Create a cold start optimized PGLite instance
+ *
+ * This is the main entry point for optimized PGLite initialization in Workers.
+ *
+ * @example
+ * ```typescript
+ * import pgliteWasm from './pglite.wasm'
+ *
+ * const optimizer = createColdStartOptimizer({
+ *   wasmModule: pgliteWasm,
+ *   cacheLayer: myCacheLayer,
+ *   warmCacheKey: `db:${databaseId}`,
+ *   r2Layer: myR2Layer,
+ *   coldStorageKey: `databases/${databaseId}/data.tar`,
+ *   lazy: true,
+ *   prewarm: true,
+ * })
+ *
+ * // First query triggers initialization
+ * const result = await optimizer.query('SELECT * FROM users')
+ *
+ * // Check metrics
+ * const metrics = optimizer.getMetrics()
+ * console.log(`Cold start: ${metrics?.totalMs}ms from ${metrics?.dataSource}`)
+ * ```
+ */
+export function createColdStartOptimizer(
+  config: ColdStartConfig
+): ColdStartOptimizer {
+  const {
+    lazy = true,
+    prewarm = true,
+    prewarmQueries = DEFAULT_PREWARM_QUERIES,
+    debug: enableDebug = false,
+    onPhaseChange,
+    onReady,
+    onError,
+  } = config
+
+  // State
+  let pglite: PGlite | null = null
+  let initPromise: Promise<void> | null = null
+  let phase: ColdStartPhase = 'not_started'
+  let metrics: ColdStartMetrics | null = null
+  let closed = false
+
+  // Debug logging
+  const debug = enableDebug ? console.log.bind(console, '[ColdStartOptimizer]') : () => {}
+
+  // Generate cache key for WASM caching
+  const cacheKey = generateCacheKey(config)
+
+  /**
+   * Update phase and notify callback
+   */
+  function setPhase(newPhase: ColdStartPhase): void {
+    phase = newPhase
+    debug(`Phase: ${newPhase}`)
+    onPhaseChange?.(newPhase, metrics ?? {})
+  }
+
+  /**
+   * Perform the actual initialization
+   */
+  async function doInitialize(): Promise<void> {
+    const startTime = performance.now()
+    const startedAt = Date.now()
+    const phaseBreakdown: PhaseTimingBreakdown[] = []
+
+    // Initialize metrics
+    const initMetrics: ColdStartMetrics = {
+      totalMs: 0,
+      wasmPrepMs: 0,
+      dataFetchMs: 0,
+      parallelSavingsMs: 0,
+      pgliteInitMs: 0,
+      firstQueryMs: 0,
+      dataSource: 'empty',
+      dataSizeBytes: 0,
+      isWarmStart: false,
+      phase: 'not_started',
+      startedAt,
+      completedAt: 0,
+      phaseBreakdown: [],
+      prewarmTimings: [],
+    }
+
+    try {
+      // Check WASM cache first (warm start)
+      const cached = getCachedInstance(cacheKey)
+      if (cached) {
+        debug('Warm start: using cached PGLite instance')
+        pglite = cached.pglite
+        initMetrics.isWarmStart = true
+        initMetrics.totalMs = performance.now() - startTime
+        initMetrics.completedAt = Date.now()
+        initMetrics.phase = 'ready'
+        initMetrics.wasmStrategy = {
+          strategy: 'cached',
+          moduleLoadMs: 0,
+          instantiateMs: 0,
+          totalMs: 0,
+          fromCache: true,
+        }
+        metrics = initMetrics
+        setPhase('ready')
+        onReady?.(initMetrics)
+        return
+      }
+
+      // Cold start: full initialization
+      debug('Cold start: initializing new PGLite instance')
+
+      // Phase 1: WASM preparation (usually instant for pre-compiled modules)
+      setPhase('wasm_loading')
+      const wasmPhaseStart = performance.now()
+      // WASM module is pre-compiled via static import, nothing to do here
+      // But we track it for comparison with other strategies
+      const wasmPhaseEnd = performance.now()
+      initMetrics.wasmPrepMs = wasmPhaseEnd - wasmPhaseStart
+
+      // Estimate WASM module size based on variant
+      // Tiny variant: ~4.8MB (target: under 5MB), Full variant: ~13MB
+      const variant = (config.pgliteOptions as { variant?: 'tiny' | 'full' } | undefined)?.variant
+      const estimatedModuleSizeBytes = variant === 'tiny' ? 4.8 * 1024 * 1024 : 13 * 1024 * 1024
+
+      initMetrics.wasmStrategy = {
+        strategy: 'static_import',
+        moduleLoadMs: 0, // Pre-compiled at build time
+        instantiateMs: initMetrics.wasmPrepMs,
+        totalMs: initMetrics.wasmPrepMs,
+        fromCache: false,
+        moduleSizeBytes: estimatedModuleSizeBytes,
+      }
+      phaseBreakdown.push({
+        phase: 'wasm_loading',
+        startTime: wasmPhaseStart,
+        endTime: wasmPhaseEnd,
+        durationMs: initMetrics.wasmPrepMs,
+      })
+
+      // Phase 2: Parallel data fetch
+      // This happens "in parallel" with the zero-time WASM prep
+      // The real savings come from starting this early
+      setPhase('parallel_loading')
+      const dataFetchStart = performance.now()
+      const fetchResult = await parallelFetchData(config, debug)
+      const dataFetchEnd = performance.now()
+      initMetrics.dataFetchMs = fetchResult.fetchTimeMs
+      initMetrics.dataSource = fetchResult.source
+      initMetrics.dataSizeBytes = fetchResult.data?.length ?? 0
+      initMetrics.tierFetchTimings = fetchResult.tierTimings
+
+      phaseBreakdown.push({
+        phase: 'parallel_loading',
+        startTime: dataFetchStart,
+        endTime: dataFetchEnd,
+        durationMs: dataFetchEnd - dataFetchStart,
+        subPhases: Object.entries(fetchResult.tierTimings || {}).map(([tier, timing]) => ({
+          name: `${tier}_fetch`,
+          startTime: dataFetchStart,
+          endTime: dataFetchStart + timing.durationMs,
+          durationMs: timing.durationMs,
+        })),
+      })
+
+      // Calculate parallel savings (would have been sequential without this)
+      // Since WASM prep is ~0ms, parallel savings = max(0, wasmPrepMs)
+      initMetrics.parallelSavingsMs = Math.max(
+        0,
+        initMetrics.wasmPrepMs - initMetrics.dataFetchMs
+      )
+
+      // Phase 3: PGLite initialization
+      setPhase('pglite_init')
+      const pglitePhaseStart = performance.now()
+
+      // Track dynamic import time separately
+      const importStart = performance.now()
+      const { PGlite } = await import('@dotdo/pglite')
+      const importEnd = performance.now()
+      initMetrics.pgliteImportMs = importEnd - importStart
+
+      // Build PGLite configuration
+      const pgliteConfig: PGliteOptions = {
+        ...config.pgliteOptions,
+        wasmModule: config.wasmModule,
+        database: config.database ?? 'postgres',
+      }
+
+      // Add filesystem bundle if data was fetched
+      if (fetchResult.data) {
+        pgliteConfig.fsBundle = new Blob([fetchResult.data])
+      }
+
+      // Create PGLite instance
+      const createStart = performance.now()
+      pglite = await PGlite.create(pgliteConfig)
+      const createEnd = performance.now()
+
+      const pglitePhaseEnd = performance.now()
+      initMetrics.pgliteInitMs = pglitePhaseEnd - pglitePhaseStart
+
+      phaseBreakdown.push({
+        phase: 'pglite_init',
+        startTime: pglitePhaseStart,
+        endTime: pglitePhaseEnd,
+        durationMs: initMetrics.pgliteInitMs,
+        subPhases: [
+          {
+            name: 'dynamic_import',
+            startTime: importStart,
+            endTime: importEnd,
+            durationMs: initMetrics.pgliteImportMs,
+          },
+          {
+            name: 'pglite_create',
+            startTime: createStart,
+            endTime: createEnd,
+            durationMs: createEnd - createStart,
+          },
+        ],
+      })
+
+      // Phase 4: Pre-warming (optional but recommended)
+      if (prewarm && prewarmQueries.length > 0) {
+        const prewarmStart = performance.now()
+        const prewarmTimings = await runPrewarmQueriesWithTimings(pglite, prewarmQueries, debug)
+        const prewarmEnd = performance.now()
+        initMetrics.firstQueryMs = prewarmEnd - prewarmStart
+        initMetrics.prewarmTimings = prewarmTimings
+
+        phaseBreakdown.push({
+          phase: 'ready', // Prewarm is the final phase before ready
+          startTime: prewarmStart,
+          endTime: prewarmEnd,
+          durationMs: initMetrics.firstQueryMs,
+          subPhases: prewarmTimings.map((t, i) => ({
+            name: `prewarm_query_${i}`,
+            startTime: prewarmStart,
+            endTime: prewarmStart + t.durationMs,
+            durationMs: t.durationMs,
+          })),
+        })
+      }
+
+      // Complete initialization
+      initMetrics.totalMs = performance.now() - startTime
+      initMetrics.completedAt = Date.now()
+      initMetrics.phase = 'ready'
+      initMetrics.phaseBreakdown = phaseBreakdown
+
+      // Try to capture memory usage
+      if (typeof process !== 'undefined' && process.memoryUsage) {
+        initMetrics.memoryUsedMB = process.memoryUsage().heapUsed / (1024 * 1024)
+      }
+
+      metrics = initMetrics
+
+      // Cache for warm starts
+      cacheInstance(cacheKey, {
+        pglite,
+        createdAt: Date.now(),
+        metrics: initMetrics,
+        reuseCount: 0,
+      })
+
+      setPhase('ready')
+      onReady?.(initMetrics)
+
+      debug(
+        `Cold start complete: ${initMetrics.totalMs.toFixed(2)}ms ` +
+          `(data: ${initMetrics.dataFetchMs.toFixed(2)}ms from ${initMetrics.dataSource}, ` +
+          `pglite: ${initMetrics.pgliteInitMs.toFixed(2)}ms, ` +
+          `import: ${initMetrics.pgliteImportMs?.toFixed(2)}ms)`
+      )
+    } catch (error) {
+      setPhase('error')
+      onError?.(error as Error, phase)
+      throw error
+    }
+  }
+
+  /**
+   * Ensure PGLite is initialized
+   */
+  async function ensureInitialized(): Promise<void> {
+    if (pglite && phase === 'ready') return
+
+    if (closed) {
+      throw new Error('ColdStartOptimizer is closed')
+    }
+
+    if (phase === 'error') {
+      throw new Error('ColdStartOptimizer initialization failed')
+    }
+
+    if (!initPromise) {
+      initPromise = doInitialize()
+    }
+
+    await initPromise
+  }
+
+  // Start initialization immediately if not lazy
+  if (!lazy) {
+    initPromise = doInitialize()
+  }
+
+  return {
+    async getInstance(): Promise<PGlite> {
+      await ensureInitialized()
+      return pglite!
+    },
+
+    isReady(): boolean {
+      return phase === 'ready'
+    },
+
+    isInitializing(): boolean {
+      return (
+        phase !== 'not_started' &&
+        phase !== 'ready' &&
+        phase !== 'error'
+      )
+    },
+
+    getPhase(): ColdStartPhase {
+      return phase
+    },
+
+    getMetrics(): ColdStartMetrics | null {
+      return metrics
+    },
+
+    async initialize(): Promise<void> {
+      await ensureInitialized()
+    },
+
+    async query<T = unknown>(
+      sql: string,
+      params?: unknown[]
+    ): Promise<{ rows: T[] }> {
+      await ensureInitialized()
+      const result = await pglite!.query<T>(sql, params)
+      return { rows: result.rows }
+    },
+
+    async close(): Promise<void> {
+      closed = true
+
+      if (initPromise) {
+        try {
+          await initPromise
+        } catch {
+          // Ignore errors from pending initialization
+        }
+      }
+
+      if (pglite) {
+        // Remove from cache
+        wasmCache.delete(cacheKey)
+
+        try {
+          await pglite.close()
+        } catch {
+          // Ignore close errors
+        }
+        pglite = null
+      }
+
+      initPromise = null
+    },
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a cold start optimizer factory with pre-configured storage layers
+ *
+ * Use this in a Durable Object to create optimizer instances with consistent config.
+ *
+ * @example
+ * ```typescript
+ * // In DO constructor
+ * const createOptimizer = createColdStartOptimizerFactory({
+ *   cacheLayer: myCacheLayer,
+ *   r2Layer: myR2Layer,
+ * })
+ *
+ * // In DO fetch handler
+ * const optimizer = createOptimizer({
+ *   wasmModule: pgliteWasm,
+ *   warmCacheKey: `db:${this.id}`,
+ *   coldStorageKey: `databases/${this.id}/data.tar`,
+ * })
+ * ```
+ */
+export function createColdStartOptimizerFactory(
+  baseConfig: Partial<ColdStartConfig>
+): (instanceConfig: ColdStartConfig) => ColdStartOptimizer {
+  return (instanceConfig) => {
+    return createColdStartOptimizer({
+      ...baseConfig,
+      ...instanceConfig,
+    })
+  }
+}
+
+/**
+ * Create a cold start optimizer with automatic tier detection
+ *
+ * Simplifies configuration by automatically detecting available tiers.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = createAutoTieredOptimizer({
+ *   wasmModule: pgliteWasm,
+ *   env: {
+ *     R2_BUCKET: env.R2_BUCKET,
+ *   },
+ *   databaseId: 'my-database',
+ * })
+ * ```
+ */
+export function createAutoTieredOptimizer(options: {
+  wasmModule: WebAssembly.Module
+  databaseId: string
+  env?: {
+    R2_BUCKET?: R2Bucket
+  }
+  cacheLayer?: CacheLayer
+  r2Layer?: R2StorageLayer
+  hotData?: ArrayBuffer | Uint8Array
+  lazy?: boolean
+  debug?: boolean
+}): ColdStartOptimizer {
+  const {
+    wasmModule,
+    databaseId,
+    env,
+    cacheLayer,
+    r2Layer,
+    hotData,
+    lazy = true,
+    debug = false,
+  } = options
+
+  return createColdStartOptimizer({
+    wasmModule,
+    hotData,
+    cacheLayer,
+    warmCacheKey: cacheLayer ? `pglite:${databaseId}` : undefined,
+    r2Layer,
+    r2Bucket: env?.R2_BUCKET,
+    coldStorageKey:
+      r2Layer || env?.R2_BUCKET ? `databases/${databaseId}/data.tar` : undefined,
+    database: databaseId,
+    lazy,
+    debug,
+  })
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  createColdStartOptimizer as default,
+}
+
+// ============================================================================
+// WASM Strategy Comparison
+// ============================================================================
+
+/**
+ * WASM loading strategy types for benchmarking
+ *
+ * Different strategies have different performance characteristics:
+ *
+ * | Strategy | Description | Best For |
+ * |----------|-------------|----------|
+ * | `static_import` | Pre-compiled at build time | Production (Cloudflare Workers) |
+ * | `dynamic_import` | Compiled on demand | Development, testing |
+ * | `streaming` | Compile during download | Large modules, Node.js |
+ * | `cached` | Reused from isolate cache | Warm starts |
+ *
+ * In Cloudflare Workers, `static_import` is required because runtime
+ * WASM compilation is blocked for security reasons.
+ */
+export type WasmLoadingStrategy = 'static_import' | 'dynamic_import' | 'streaming' | 'cached'
+
+/**
+ * Results from comparing different WASM loading strategies
+ *
+ * Contains statistical analysis of multiple profiling runs for a single strategy.
+ * Used to compare performance across different loading approaches.
+ */
+export interface WasmStrategyComparisonResult {
+  strategy: WasmLoadingStrategy
+  samples: number
+  meanMs: number
+  medianMs: number
+  p95Ms: number
+  p99Ms: number
+  minMs: number
+  maxMs: number
+  stdDevMs: number
+  available: boolean
+  vsBaselinePercent?: number
+}
+
+/**
+ * Profile a WASM loading strategy by running multiple iterations
+ *
+ * Runs the provided loader function multiple times and calculates
+ * statistical metrics (mean, median, percentiles) for comparison.
+ *
+ * @param strategy - The strategy name for labeling results
+ * @param loader - Function that loads the WASM module
+ * @param iterations - Number of times to run the loader (default: 5)
+ * @returns Statistical analysis of loading times
+ *
+ * @example
+ * ```typescript
+ * const result = await profileWasmStrategy(
+ *   'static_import',
+ *   async () => {
+ *     // Load WASM module
+ *     return WebAssembly.compile(wasmBytes)
+ *   },
+ *   10 // Run 10 iterations
+ * )
+ *
+ * console.log(`Median: ${result.medianMs}ms`)
+ * console.log(`P95: ${result.p95Ms}ms`)
+ * ```
+ */
+export async function profileWasmStrategy(
+  strategy: WasmLoadingStrategy,
+  loader: () => Promise<WebAssembly.Module | void>,
+  iterations = 5
+): Promise<WasmStrategyComparisonResult> {
+  const samples: number[] = []
+
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now()
+    await loader()
+    const end = performance.now()
+    samples.push(end - start)
+  }
+
+  const sorted = [...samples].sort((a, b) => a - b)
+  const sum = sorted.reduce((a, b) => a + b, 0)
+  const mean = sum / sorted.length
+  const variance = sorted.reduce((a, b) => a + Math.pow(b - mean, 2), 0) / sorted.length
+
+  const percentile = (p: number): number => {
+    const index = Math.ceil((p / 100) * sorted.length) - 1
+    return sorted[Math.max(0, Math.min(index, sorted.length - 1))]
+  }
+
+  return {
+    strategy,
+    samples: iterations,
+    meanMs: mean,
+    medianMs: percentile(50),
+    p95Ms: percentile(95),
+    p99Ms: percentile(99),
+    minMs: sorted[0],
+    maxMs: sorted[sorted.length - 1],
+    stdDevMs: Math.sqrt(variance),
+    available: true,
+  }
+}
+
+/**
+ * Compare multiple WASM loading strategies
+ *
+ * Profiles multiple loading strategies and provides a recommendation
+ * based on median performance. Generates a human-readable analysis report.
+ *
+ * @param strategies - Map of strategy names to loader functions
+ * @param iterations - Number of iterations per strategy (default: 5)
+ * @returns Object containing:
+ *   - `results`: Statistical results for each strategy
+ *   - `recommendation`: The fastest strategy based on median time
+ *   - `analysis`: Human-readable performance report
+ *
+ * @example
+ * ```typescript
+ * const strategies = new Map([
+ *   ['static_import', async () => staticWasmModule],
+ *   ['dynamic_import', async () => {
+ *     const { PGlite } = await import('@dotdo/pglite')
+ *     return PGlite.wasmModule
+ *   }],
+ * ])
+ *
+ * const { results, recommendation, analysis } = await compareWasmStrategies(strategies, 5)
+ *
+ * console.log(analysis)
+ * // Output:
+ * // WASM Loading Strategy Analysis
+ * // ========================================
+ * // static_import:
+ * //   Median: 0.05ms
+ * //   P95: 0.10ms
+ * // dynamic_import:
+ * //   Median: 15.00ms
+ * //   P95: 20.00ms
+ * //   vs static_import: 29900% slower
+ * // ========================================
+ * // Recommendation: static_import
+ * ```
+ */
+export async function compareWasmStrategies(
+  strategies: Map<WasmLoadingStrategy, () => Promise<WebAssembly.Module | void>>,
+  iterations = 5
+): Promise<{
+  results: WasmStrategyComparisonResult[]
+  recommendation: WasmLoadingStrategy
+  analysis: string
+}> {
+  const results: WasmStrategyComparisonResult[] = []
+  let baselineMedian: number | null = null
+
+  for (const [strategy, loader] of strategies) {
+    try {
+      const result = await profileWasmStrategy(strategy, loader, iterations)
+      if (strategy === 'static_import') {
+        baselineMedian = result.medianMs
+      }
+      results.push(result)
+    } catch {
+      results.push({
+        strategy,
+        samples: 0,
+        meanMs: 0,
+        medianMs: 0,
+        p95Ms: 0,
+        p99Ms: 0,
+        minMs: 0,
+        maxMs: 0,
+        stdDevMs: 0,
+        available: false,
+      })
+    }
+  }
+
+  if (baselineMedian !== null) {
+    for (const result of results) {
+      if (result.available && result.strategy !== 'static_import') {
+        result.vsBaselinePercent = ((result.medianMs - baselineMedian) / baselineMedian) * 100
+      }
+    }
+  }
+
+  const availableResults = results.filter((r) => r.available)
+  const sortedByMedian = [...availableResults].sort((a, b) => a.medianMs - b.medianMs)
+  const recommendation = sortedByMedian[0]?.strategy ?? 'static_import'
+
+  const lines: string[] = ['WASM Loading Strategy Analysis', '='.repeat(40)]
+  for (const result of results) {
+    if (!result.available) {
+      lines.push('\n' + result.strategy + ': NOT AVAILABLE')
+      continue
+    }
+    lines.push('\n' + result.strategy + ':')
+    lines.push('  Median: ' + result.medianMs.toFixed(2) + 'ms')
+    lines.push('  P95: ' + result.p95Ms.toFixed(2) + 'ms')
+    lines.push('  StdDev: ' + result.stdDevMs.toFixed(2) + 'ms')
+    if (result.vsBaselinePercent !== undefined) {
+      const comparison = result.vsBaselinePercent > 0 ? 'slower' : 'faster'
+      lines.push('  vs static_import: ' + Math.abs(result.vsBaselinePercent).toFixed(1) + '% ' + comparison)
+    }
+  }
+  lines.push('\n' + '='.repeat(40))
+  lines.push('Recommendation: ' + recommendation)
+
+  return { results, recommendation, analysis: lines.join('\n') }
+}
+
+// ============================================================================
+// Cold Start Profiler
+// ============================================================================
+
+/**
+ * Profiling result from multiple cold start runs
+ *
+ * Contains comprehensive statistical analysis of cold start performance,
+ * including per-phase breakdown and data source distribution.
+ *
+ * ## Key Metrics
+ *
+ * - `totalMs`: Overall cold start time statistics
+ * - `phases`: Per-phase timing breakdown (WASM prep, data fetch, PGLite init, prewarm)
+ * - `dataSourceDistribution`: How often each storage tier was used
+ * - `memoryMB`: Memory usage statistics (if available)
+ *
+ * ## Usage in CI
+ *
+ * Use this for performance regression detection:
+ *
+ * ```typescript
+ * const result = await profileColdStarts(optimizer, 10)
+ *
+ * // Assert against performance budget
+ * expect(result.totalMs.p95).toBeLessThan(1500)
+ * expect(result.totalMs.median).toBeLessThan(800)
+ * ```
+ */
+export interface ColdStartProfilingResult {
+  samples: number
+  totalMs: {
+    mean: number
+    median: number
+    p95: number
+    p99: number
+    min: number
+    max: number
+    stdDev: number
+  }
+  phases: {
+    wasmPrep: { mean: number; median: number; p95: number }
+    dataFetch: { mean: number; median: number; p95: number }
+    pgliteInit: { mean: number; median: number; p95: number }
+    prewarm: { mean: number; median: number; p95: number }
+  }
+  dataSourceDistribution: Record<string, number>
+  memoryMB?: { mean: number; max: number }
+  rawMetrics: ColdStartMetrics[]
+}
+
+/**
+ * Format profiling results as human-readable string
+ *
+ * Generates a comprehensive text report suitable for logging, CI output,
+ * or documentation.
+ *
+ * @param result - Profiling results to format
+ * @returns Multi-line string with formatted statistics
+ *
+ * @example
+ * ```typescript
+ * const result = await profileColdStarts(optimizer, 10)
+ * const report = formatProfilingResult(result)
+ * console.log(report)
+ *
+ * // Output:
+ * // Cold Start Profiling Results
+ * // ========================================
+ * // Samples: 10
+ * //
+ * // Total Cold Start Time:
+ * //   Mean: 750.00ms
+ * //   Median (p50): 720.00ms
+ * //   P95: 1200.00ms
+ * //   ...
+ * ```
+ */
+export function formatProfilingResult(result: ColdStartProfilingResult): string {
+  const lines: string[] = [
+    'Cold Start Profiling Results',
+    '='.repeat(40),
+    'Samples: ' + result.samples,
+    '',
+    'Total Cold Start Time:',
+    '  Mean: ' + result.totalMs.mean.toFixed(2) + 'ms',
+    '  Median (p50): ' + result.totalMs.median.toFixed(2) + 'ms',
+    '  P95: ' + result.totalMs.p95.toFixed(2) + 'ms',
+    '  P99: ' + result.totalMs.p99.toFixed(2) + 'ms',
+    '  Min: ' + result.totalMs.min.toFixed(2) + 'ms',
+    '  Max: ' + result.totalMs.max.toFixed(2) + 'ms',
+    '  StdDev: ' + result.totalMs.stdDev.toFixed(2) + 'ms',
+    '',
+    'Phase Breakdown (median):',
+    '  WASM Prep: ' + result.phases.wasmPrep.median.toFixed(2) + 'ms',
+    '  Data Fetch: ' + result.phases.dataFetch.median.toFixed(2) + 'ms',
+    '  PGLite Init: ' + result.phases.pgliteInit.median.toFixed(2) + 'ms',
+    '  Prewarm: ' + result.phases.prewarm.median.toFixed(2) + 'ms',
+    '',
+    'Data Source Distribution:',
+    ...Object.entries(result.dataSourceDistribution).map(
+      ([source, count]) => '  ' + source + ': ' + count + ' (' + ((count / result.samples) * 100).toFixed(1) + '%)'
+    ),
+  ]
+
+  if (result.memoryMB) {
+    lines.push('', 'Memory Usage:', '  Mean: ' + result.memoryMB.mean.toFixed(2) + 'MB', '  Max: ' + result.memoryMB.max.toFixed(2) + 'MB')
+  }
+
+  return lines.join('\n')
+}