@dotdo/postgres 0.1.0

package/src/storage/tiered-vfs.ts

@@ -0,0 +1,1082 @@
+/**
+ * TieredVFS - Combine cache, DO, R2 layers for PGLite storage
+ * Task: postgres-xm8.9 - TieredVFS - combine cache, DO, R2 layers
+ * Consolidation: postgres-u2ut - Merged graceful degradation from pglite/tiered-vfs.ts
+ *
+ * Provides a unified virtual file system interface that:
+ * - Reads from Cache (hot) -> DO Storage (warm) -> R2 (cold)
+ * - Writes to DO Storage, promotes to Cache on access
+ * - Supports tier-aware operations for optimal performance
+ * - Gracefully degrades when storage tiers fail
+ *
+ * Tier Architecture:
+ * - Hot (Cache): Cloudflare Cache API - FREE, fastest, ephemeral, global edge
+ * - Warm (DO): Durable Object Storage - fast, persistent, limited (128KB-10MB)
+ * - Cold (R2): R2 Object Storage - durable, unlimited, slower, cheapest
+ *
+ * @module storage/tiered-vfs
+ */
+
+import type { CacheLayer, CacheLayerStats } from './cache-layer'
+import type { R2StorageLayer, R2StorageLayerStats } from './r2-layer'
+
+// Re-export for external use
+export type { CacheEntryMetadata } from './cache-layer'
+
+// =============================================================================
+// Configuration Constants
+// =============================================================================
+
+/**
+ * Default number of accesses before promoting data to a hotter tier.
+ * Prevents unnecessary promotion of rarely accessed data.
+ */
+const DEFAULT_PROMOTION_THRESHOLD = 3
+
+/**
+ * Default number of consecutive failures before marking a tier unavailable.
+ * Implements circuit breaker pattern to prevent cascading failures.
+ */
+const DEFAULT_FAILURE_THRESHOLD = 3
+
+/**
+ * Default time in milliseconds before attempting to use an unavailable tier again.
+ * Allows failing services time to recover before retrying.
+ */
+const DEFAULT_RECOVERY_TIME_MS = 30000
+
+/**
+ * Default maximum number of failure events to keep in history.
+ * Prevents unbounded memory growth from failure tracking.
+ */
+const DEFAULT_MAX_FAILURE_HISTORY = 100
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Storage tier identifiers
+ * - hot: Cloudflare Cache API (FREE, fastest, ephemeral)
+ * - warm: Durable Object Storage (fast, persistent, limited)
+ * - cold: R2 (durable, unlimited, slower)
+ */
+export type StorageTier = 'hot' | 'warm' | 'cold'
+
+/**
+ * Health status of a storage tier
+ * - healthy: Tier is operating normally
+ * - degraded: Tier has experienced recent failures but is still attempted
+ * - unavailable: Tier is skipped until recovery time passes
+ */
+export type TierHealth = 'healthy' | 'degraded' | 'unavailable'
+
+/**
+ * Information about a tier failure
+ */
+export interface TierFailure {
+  /** The tier that failed */
+  tier: StorageTier
+  /** Timestamp of the failure */
+  timestamp: number
+  /** Error message */
+  error: string
+  /** Type of operation that failed */
+  operation: 'read' | 'write' | 'delete' | 'check'
+  /** Key involved (if applicable) */
+  key?: string | undefined
+}
+
+/**
+ * Health status for all tiers
+ */
+export interface TierHealthStatus {
+  /** Health status of hot tier */
+  hot: TierHealth
+  /** Health status of warm tier */
+  warm: TierHealth
+  /** Health status of cold tier */
+  cold: TierHealth
+  /** Recent failure events */
+  recentFailures: TierFailure[]
+  /** Total failure counts per tier */
+  failureCounts: Record<StorageTier, number>
+}
+
+/**
+ * Callback for tier failure events
+ */
+export type TierFailureCallback = (failure: TierFailure) => void
+
+/**
+ * Result of locating a page across tiers
+ */
+export interface PageLocation {
+  /** The tier where the page was found */
+  tier?: StorageTier
+  /** Whether the page was found */
+  found: boolean
+  /** The page key */
+  key: string
+}
+
+/**
+ * Options for read operations
+ */
+export interface ReadOptions {
+  /** Whether to skip promotion after read */
+  skipPromotion?: boolean
+  /** Whether to track access for promotion/demotion decisions */
+  trackAccess?: boolean
+}
+
+/**
+ * Options for write operations
+ */
+export interface WriteOptions {
+  /** Target tier for the write */
+  tier?: StorageTier
+  /** Custom metadata to attach */
+  metadata?: Record<string, string>
+  /** Whether to also write to hotter tiers for immediate availability */
+  writeThrough?: boolean
+}
+
+/**
+ * Configuration for TieredVFS
+ */
+export interface TieredVFSConfig {
+  /** Cache layer for hot tier */
+  cacheLayer: CacheLayer
+  /** Durable Object storage for warm tier */
+  doStorage: DurableObjectStorage
+  /** R2 layer for cold tier */
+  r2Layer: R2StorageLayer
+  /** Page size in bytes (typically 8KB for PGLite) */
+  pageSize: number
+  /** Number of accesses before promoting to hotter tier */
+  promotionThreshold?: number
+  /** Whether to auto-promote on read from cold tiers */
+  autoPromote?: boolean
+  /** Number of consecutive failures before marking tier unavailable */
+  failureThreshold?: number
+  /** Time in ms before attempting unavailable tier again */
+  recoveryTimeMs?: number
+  /** Maximum number of failure events to keep in history */
+  maxFailureHistory?: number
+}
+
+/**
+ * Combined statistics from all tiers
+ */
+export interface TieredVFSStats {
+  /** Cache layer statistics */
+  cache: CacheLayerStats
+  /** R2 layer statistics */
+  r2: R2StorageLayerStats
+  /** DO storage statistics (tracked internally) */
+  do: {
+    reads: number
+    writes: number
+    deletes: number
+    bytesRead: number
+    bytesWritten: number
+  }
+  /** Promotion statistics */
+  promotions: {
+    coldToWarm: number
+    warmToHot: number
+  }
+  /** Demotion statistics */
+  demotions: {
+    hotToWarm: number
+    warmToCold: number
+  }
+  /** Current tier health status */
+  tierHealth: TierHealthStatus
+}
+
+/**
+ * Promotion event data
+ */
+export interface PromotionEvent {
+  key: string
+  fromTier: StorageTier
+  toTier: StorageTier
+  timestamp: number
+  success: boolean
+  error?: string
+}
+
+/**
+ * Callback for tier events
+ */
+export type TierEventCallback = (event: PromotionEvent) => void
+
+/**
+ * Result of delete operation
+ */
+export interface DeleteResult {
+  /** Whether delete succeeded on all tiers */
+  success: boolean
+  /** Tiers where delete failed */
+  failedTiers: StorageTier[]
+}
+
+/**
+ * TieredVFS combines Cache, DO Storage, and R2 into a unified storage layer.
+ *
+ * Read path: Cache (hot) -> DO (warm) -> R2 (cold)
+ * Write path: Configurable target tier, default to DO (warm)
+ *
+ * Features:
+ * - Automatic promotion based on access patterns
+ * - Graceful degradation when tiers fail
+ * - Circuit breaker pattern for unavailable tiers
+ * - Comprehensive statistics including tier health
+ *
+ * @example
+ * ```typescript
+ * const tieredVFS = createTieredVFS({
+ *   cacheLayer,
+ *   doStorage: ctx.storage,
+ *   r2Layer,
+ *   pageSize: 8192,
+ *   promotionThreshold: 3,
+ *   autoPromote: true,
+ *   failureThreshold: 3,
+ *   recoveryTimeMs: 30000,
+ * })
+ *
+ * // Read with automatic tiered lookup and graceful degradation
+ * const page = await tieredVFS.readPage('page-123')
+ *
+ * // Write to warm tier (default)
+ * await tieredVFS.writePage('page-456', data)
+ *
+ * // Check tier health
+ * const health = tieredVFS.getTierHealth()
+ * console.log('Hot tier status:', health.hot)
+ * ```
+ */
+export class TieredVFS {
+  private cacheLayer: CacheLayer
+  private doStorage: DurableObjectStorage
+  private r2Layer: R2StorageLayer
+  private pageSize: number
+  private promotionThreshold: number
+  private autoPromote: boolean
+  private failureThreshold: number
+  private recoveryTimeMs: number
+  private maxFailureHistory: number
+
+  private doStats: {
+    reads: number
+    writes: number
+    deletes: number
+    bytesRead: number
+    bytesWritten: number
+  }
+  private promotionStats: {
+    coldToWarm: number
+    warmToHot: number
+  }
+  private demotionStats: {
+    hotToWarm: number
+    warmToCold: number
+  }
+  private accessCounts: Map<string, number>
+  private onPromotionCallback?: TierEventCallback
+  private onDemotionCallback?: TierEventCallback
+
+  // Graceful degradation state
+  private tierHealth: Record<StorageTier, TierHealth>
+  private consecutiveFailures: Record<StorageTier, number>
+  private lastFailureTime: Record<StorageTier, number>
+  private failureCounts: Record<StorageTier, number>
+  private recentFailures: TierFailure[]
+  private failureCallbacks: TierFailureCallback[]
+
+  constructor(config: TieredVFSConfig) {
+    this.cacheLayer = config.cacheLayer
+    this.doStorage = config.doStorage
+    this.r2Layer = config.r2Layer
+    this.pageSize = config.pageSize
+    this.promotionThreshold = config.promotionThreshold ?? DEFAULT_PROMOTION_THRESHOLD
+    this.autoPromote = config.autoPromote ?? false
+    this.failureThreshold = config.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD
+    this.recoveryTimeMs = config.recoveryTimeMs ?? DEFAULT_RECOVERY_TIME_MS
+    this.maxFailureHistory = config.maxFailureHistory ?? DEFAULT_MAX_FAILURE_HISTORY
+
+    this.doStats = {
+      reads: 0,
+      writes: 0,
+      deletes: 0,
+      bytesRead: 0,
+      bytesWritten: 0,
+    }
+    this.promotionStats = {
+      coldToWarm: 0,
+      warmToHot: 0,
+    }
+    this.demotionStats = {
+      hotToWarm: 0,
+      warmToCold: 0,
+    }
+    this.accessCounts = new Map()
+
+    // Initialize graceful degradation state
+    this.tierHealth = { hot: 'healthy', warm: 'healthy', cold: 'healthy' }
+    this.consecutiveFailures = { hot: 0, warm: 0, cold: 0 }
+    this.lastFailureTime = { hot: 0, warm: 0, cold: 0 }
+    this.failureCounts = { hot: 0, warm: 0, cold: 0 }
+    this.recentFailures = []
+    this.failureCallbacks = []
+  }
+
+  /**
+   * Set callback for promotion events
+   */
+  onPromotion(callback: TierEventCallback): void {
+    this.onPromotionCallback = callback
+  }
+
+  /**
+   * Set callback for demotion events
+   */
+  onDemotion(callback: TierEventCallback): void {
+    this.onDemotionCallback = callback
+  }
+
+  /**
+   * Set callback for tier failure events
+   */
+  onTierFailure(callback: TierFailureCallback): void {
+    this.failureCallbacks.push(callback)
+  }
+
+  /**
+   * Record a failure for a tier (updates health tracking)
+   */
+  private recordFailure(tier: StorageTier, operation: TierFailure['operation'], error: unknown, key?: string): void {
+    const failure: TierFailure = {
+      tier,
+      timestamp: Date.now(),
+      error: error instanceof Error ? error.message : String(error),
+      operation,
+      key,
+    }
+
+    this.consecutiveFailures[tier]++
+    this.failureCounts[tier]++
+    this.lastFailureTime[tier] = failure.timestamp
+    this.recentFailures.push(failure)
+
+    // Trim failure history
+    if (this.recentFailures.length > this.maxFailureHistory) {
+      this.recentFailures.shift()
+    }
+
+    // Update health status
+    if (this.consecutiveFailures[tier] >= this.failureThreshold) {
+      this.tierHealth[tier] = 'unavailable'
+    } else {
+      this.tierHealth[tier] = 'degraded'
+    }
+
+    // Notify callbacks
+    for (const cb of this.failureCallbacks) {
+      try {
+        cb(failure)
+      } catch {
+        // Don't let callback errors break the flow
+      }
+    }
+  }
+
+  /**
+   * Record a success for a tier (resets consecutive failures)
+   */
+  private recordSuccess(tier: StorageTier): void {
+    this.consecutiveFailures[tier] = 0
+    this.tierHealth[tier] = 'healthy'
+  }
+
+  /**
+   * Check if a tier should be attempted (based on health)
+   */
+  private shouldAttemptTier(tier: StorageTier): boolean {
+    const health = this.tierHealth[tier]
+    if (health === 'healthy' || health === 'degraded') {
+      return true
+    }
+    // Tier is unavailable - check if recovery time has passed
+    return Date.now() - this.lastFailureTime[tier] >= this.recoveryTimeMs
+  }
+
+  /**
+   * Increment access count and check if promotion is needed
+   */
+  private trackAccess(key: string): number {
+    const count = (this.accessCounts.get(key) ?? 0) + 1
+    this.accessCounts.set(key, count)
+    return count
+  }
+
+  /**
+   * Reset access count for a key
+   */
+  private resetAccessCount(key: string): void {
+    this.accessCounts.delete(key)
+  }
+
+  /**
+   * Read a page from the tiered storage
+   *
+   * Checks tiers in order: hot (Cache) -> warm (DO) -> cold (R2)
+   * Gracefully degrades when tiers fail.
+   * Optionally promotes pages to hotter tiers based on access patterns.
+   *
+   * @param key - The page key
+   * @param options - Read options
+   * @returns The page data or null if not found
+   */
+  async readPage(key: string, options?: ReadOptions): Promise<Uint8Array | null> {
+    const trackAccess = options?.trackAccess ?? true
+    const skipPromotion = options?.skipPromotion ?? false
+
+    // Try hot tier (Cache) first
+    if (this.shouldAttemptTier('hot')) {
+      try {
+        const cached = await this.cacheLayer.get(key)
+        if (cached) {
+          this.recordSuccess('hot')
+          if (trackAccess) {
+            this.trackAccess(key)
+          }
+          return cached
+        }
+      } catch (error) {
+        this.recordFailure('hot', 'read', error, key)
+      }
+    }
+
+    // Try warm tier (DO Storage)
+    if (this.shouldAttemptTier('warm')) {
+      try {
+        const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+        if (doData) {
+          this.doStats.reads++
+          this.doStats.bytesRead += doData.length
+          this.recordSuccess('warm')
+
+          if (trackAccess) {
+            const accessCount = this.trackAccess(key)
+
+            // Check for promotion to hot tier
+            if (!skipPromotion && this.autoPromote && accessCount >= this.promotionThreshold) {
+              await this.promoteToHot(key, doData)
+            }
+          }
+
+          return doData
+        }
+      } catch (error) {
+        this.recordFailure('warm', 'read', error, key)
+      }
+    }
+
+    // Try cold tier (R2)
+    if (this.shouldAttemptTier('cold')) {
+      try {
+        const r2Data = await this.r2Layer.get(key)
+        if (r2Data) {
+          this.recordSuccess('cold')
+
+          if (trackAccess) {
+            const accessCount = this.trackAccess(key)
+
+            // Check for promotion to warm tier
+            if (!skipPromotion && this.autoPromote && accessCount >= this.promotionThreshold) {
+              await this.promoteToWarm(key, r2Data)
+            }
+          }
+
+          return r2Data
+        }
+      } catch (error) {
+        this.recordFailure('cold', 'read', error, key)
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Read a page and return which tier it was found in
+   *
+   * @param key - The page key
+   * @returns The page data and location, or null if not found
+   */
+  async readPageWithLocation(
+    key: string
+  ): Promise<{ data: Uint8Array; tier: StorageTier } | null> {
+    // Try hot tier (Cache) first
+    if (this.shouldAttemptTier('hot')) {
+      try {
+        const cached = await this.cacheLayer.get(key)
+        if (cached) {
+          this.recordSuccess('hot')
+          return { data: cached, tier: 'hot' }
+        }
+      } catch (error) {
+        this.recordFailure('hot', 'read', error, key)
+      }
+    }
+
+    // Try warm tier (DO Storage)
+    if (this.shouldAttemptTier('warm')) {
+      try {
+        const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+        if (doData) {
+          this.doStats.reads++
+          this.doStats.bytesRead += doData.length
+          this.recordSuccess('warm')
+          return { data: doData, tier: 'warm' }
+        }
+      } catch (error) {
+        this.recordFailure('warm', 'read', error, key)
+      }
+    }
+
+    // Try cold tier (R2)
+    if (this.shouldAttemptTier('cold')) {
+      try {
+        const r2Data = await this.r2Layer.get(key)
+        if (r2Data) {
+          this.recordSuccess('cold')
+          return { data: r2Data, tier: 'cold' }
+        }
+      } catch (error) {
+        this.recordFailure('cold', 'read', error, key)
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Write a page to the tiered storage
+   *
+   * By default writes to warm tier (DO Storage).
+   * Can optionally write to hot (Cache) or cold (R2) tiers.
+   * Supports graceful degradation with fallback to other tiers.
+   *
+   * @param key - The page key
+   * @param data - The page data
+   * @param options - Write options
+   */
+  async writePage(key: string, data: Uint8Array, options?: WriteOptions): Promise<void> {
+    const tier = options?.tier ?? 'warm'
+    const errors: Error[] = []
+
+    if (tier === 'hot') {
+      // Write to both DO (for persistence) and Cache (for speed)
+      let persistSuccess = false
+
+      if (this.shouldAttemptTier('warm')) {
+        try {
+          await this.doStorage.put(key, data)
+          this.doStats.writes++
+          this.doStats.bytesWritten += data.length
+          this.recordSuccess('warm')
+          persistSuccess = true
+        } catch (error) {
+          this.recordFailure('warm', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      if (this.shouldAttemptTier('hot')) {
+        try {
+          await this.cacheLayer.put(key, data, {
+            lastAccessed: Date.now(),
+            accessCount: 1,
+          })
+          this.recordSuccess('hot')
+        } catch (error) {
+          this.recordFailure('hot', 'write', error, key)
+        }
+      }
+
+      // Fallback to cold tier if warm failed
+      if (!persistSuccess && this.shouldAttemptTier('cold')) {
+        try {
+          await this.r2Layer.put(key, data, {
+            customMetadata: options?.metadata,
+          })
+          this.recordSuccess('cold')
+          return
+        } catch (error) {
+          this.recordFailure('cold', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      if (!persistSuccess && errors.length > 0) {
+        throw new Error('Failed to write to any tier: ' + errors.map(e => e.message).join('; '))
+      }
+
+      // Optionally write through to cold tier for durability
+      if (persistSuccess && options?.writeThrough) {
+        try {
+          await this.r2Layer.put(key, data, {
+            customMetadata: options?.metadata,
+          })
+        } catch {
+          // Don't fail on write-through errors
+        }
+      }
+    } else if (tier === 'warm') {
+      // Try warm tier first
+      if (this.shouldAttemptTier('warm')) {
+        try {
+          await this.doStorage.put(key, data)
+          this.doStats.writes++
+          this.doStats.bytesWritten += data.length
+          this.recordSuccess('warm')
+
+          // Optionally write through to cold tier for durability
+          if (options?.writeThrough) {
+            try {
+              await this.r2Layer.put(key, data, {
+                customMetadata: options?.metadata,
+              })
+            } catch {
+              // Don't fail on write-through errors
+            }
+          }
+          return
+        } catch (error) {
+          this.recordFailure('warm', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      // Fallback to cold tier
+      if (this.shouldAttemptTier('cold')) {
+        try {
+          await this.r2Layer.put(key, data, {
+            customMetadata: options?.metadata,
+          })
+          this.recordSuccess('cold')
+          return
+        } catch (error) {
+          this.recordFailure('cold', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      if (errors.length > 0) {
+        throw new Error('Failed to write to any tier: ' + errors.map(e => e.message).join('; '))
+      }
+    } else {
+      // Cold tier - try cold first
+      if (this.shouldAttemptTier('cold')) {
+        try {
+          await this.r2Layer.put(key, data, {
+            customMetadata: options?.metadata,
+          })
+          this.recordSuccess('cold')
+          return
+        } catch (error) {
+          this.recordFailure('cold', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      // Fallback to warm tier
+      if (this.shouldAttemptTier('warm')) {
+        try {
+          await this.doStorage.put(key, data)
+          this.doStats.writes++
+          this.doStats.bytesWritten += data.length
+          this.recordSuccess('warm')
+          return
+        } catch (error) {
+          this.recordFailure('warm', 'write', error, key)
+          errors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      if (errors.length > 0) {
+        throw new Error('Failed to write to any tier: ' + errors.map(e => e.message).join('; '))
+      }
+    }
+  }
+
+  /**
+   * Delete a page from all tiers
+   *
+   * @param key - The page key
+   * @returns Result indicating success and any failed tiers
+   */
+  async deletePage(key: string): Promise<DeleteResult> {
+    const failedTiers: StorageTier[] = []
+
+    // Delete from hot tier (Cache)
+    if (this.shouldAttemptTier('hot')) {
+      try {
+        await this.cacheLayer.delete(key)
+        this.recordSuccess('hot')
+      } catch (error) {
+        this.recordFailure('hot', 'delete', error, key)
+        failedTiers.push('hot')
+      }
+    }
+
+    // Delete from warm tier (DO)
+    if (this.shouldAttemptTier('warm')) {
+      try {
+        await this.doStorage.delete(key)
+        this.doStats.deletes++
+        this.recordSuccess('warm')
+      } catch (error) {
+        this.recordFailure('warm', 'delete', error, key)
+        failedTiers.push('warm')
+      }
+    }
+
+    // Delete from cold tier (R2)
+    if (this.shouldAttemptTier('cold')) {
+      try {
+        await this.r2Layer.delete(key)
+        this.recordSuccess('cold')
+      } catch (error) {
+        this.recordFailure('cold', 'delete', error, key)
+        failedTiers.push('cold')
+      }
+    }
+
+    // Clear access tracking
+    this.resetAccessCount(key)
+
+    return {
+      success: failedTiers.length === 0,
+      failedTiers,
+    }
+  }
+
+  /**
+   * Delete multiple pages from all tiers
+   *
+   * @param keys - The page keys to delete
+   * @returns Array of delete results
+   */
+  async deletePages(keys: string[]): Promise<DeleteResult[]> {
+    return Promise.all(keys.map((key) => this.deletePage(key)))
+  }
+
+  /**
+   * Locate which tier a page is stored in
+   *
+   * @param key - The page key
+   * @returns Location information
+   */
+  async locatePage(key: string): Promise<PageLocation> {
+    // Check hot tier
+    if (this.shouldAttemptTier('hot')) {
+      try {
+        const inCache = await this.cacheLayer.has(key)
+        if (inCache) {
+          this.recordSuccess('hot')
+          return { tier: 'hot', found: true, key }
+        }
+      } catch (error) {
+        this.recordFailure('hot', 'check', error, key)
+      }
+    }
+
+    // Check warm tier
+    if (this.shouldAttemptTier('warm')) {
+      try {
+        const doData = (await this.doStorage.get(key)) as Uint8Array | undefined
+        if (doData) {
+          this.recordSuccess('warm')
+          return { tier: 'warm', found: true, key }
+        }
+      } catch (error) {
+        this.recordFailure('warm', 'check', error, key)
+      }
+    }
+
+    // Check cold tier
+    if (this.shouldAttemptTier('cold')) {
+      try {
+        const inR2 = await this.r2Layer.has(key)
+        if (inR2) {
+          this.recordSuccess('cold')
+          return { tier: 'cold', found: true, key }
+        }
+      } catch (error) {
+        this.recordFailure('cold', 'check', error, key)
+      }
+    }
+
+    return { found: false, key }
+  }
+
+  /**
+   * Promote a page from cold (R2) to warm (DO) tier
+   *
+   * @param key - The page key
+   * @param data - The page data (optional, will be fetched if not provided)
+   */
+  async promoteToWarm(key: string, data?: Uint8Array): Promise<void> {
+    const pageData = data ?? (await this.r2Layer.get(key))
+    if (!pageData) {
+      return
+    }
+
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'cold',
+      toTier: 'warm',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      await this.doStorage.put(key, pageData)
+      this.doStats.writes++
+      this.doStats.bytesWritten += pageData.length
+      this.promotionStats.coldToWarm++
+      this.resetAccessCount(key)
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onPromotionCallback?.(event)
+  }
+
+  /**
+   * Promote a page from warm (DO) to hot (Cache) tier
+   *
+   * @param key - The page key
+   * @param data - The page data (optional, will be fetched if not provided)
+   */
+  async promoteToHot(key: string, data?: Uint8Array): Promise<void> {
+    const pageData = data ?? ((await this.doStorage.get(key)) as Uint8Array | undefined)
+    if (!pageData) {
+      return
+    }
+
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'warm',
+      toTier: 'hot',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      await this.cacheLayer.put(key, pageData, {
+        lastAccessed: Date.now(),
+        accessCount: this.accessCounts.get(key) ?? 1,
+      })
+      this.promotionStats.warmToHot++
+      this.resetAccessCount(key)
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onPromotionCallback?.(event)
+  }
+
+  /**
+   * Demote a page from hot (Cache) to warm (DO) tier
+   *
+   * @param key - The page key
+   */
+  async demoteFromHot(key: string): Promise<void> {
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'hot',
+      toTier: 'warm',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      // Just delete from cache - data should already be in DO
+      await this.cacheLayer.delete(key)
+      this.demotionStats.hotToWarm++
+      event.success = true
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onDemotionCallback?.(event)
+  }
+
+  /**
+   * Demote a page from warm (DO) to cold (R2) tier
+   *
+   * @param key - The page key
+   */
+  async demoteFromWarm(key: string): Promise<void> {
+    const event: PromotionEvent = {
+      key,
+      fromTier: 'warm',
+      toTier: 'cold',
+      timestamp: Date.now(),
+      success: false,
+    }
+
+    try {
+      // Copy to R2, then delete from DO
+      const data = (await this.doStorage.get(key)) as Uint8Array | undefined
+      if (data) {
+        await this.r2Layer.put(key, data, {
+          customMetadata: {
+            demotedAt: Date.now().toString(),
+          },
+        })
+        await this.doStorage.delete(key)
+        this.doStats.deletes++
+        this.demotionStats.warmToCold++
+        event.success = true
+      }
+    } catch (error) {
+      event.error = error instanceof Error ? error.message : 'Unknown error'
+    }
+
+    this.onDemotionCallback?.(event)
+  }
+
+  /**
+   * Get tier health status
+   *
+   * @returns Current health status for all tiers
+   */
+  getTierHealth(): TierHealthStatus {
+    return {
+      hot: this.tierHealth.hot,
+      warm: this.tierHealth.warm,
+      cold: this.tierHealth.cold,
+      recentFailures: [...this.recentFailures],
+      failureCounts: { ...this.failureCounts },
+    }
+  }
+
+  /**
+   * Reset health status for a specific tier
+   *
+   * @param tier - The tier to reset
+   */
+  resetTierHealth(tier: StorageTier): void {
+    this.consecutiveFailures[tier] = 0
+    this.tierHealth[tier] = 'healthy'
+    this.lastFailureTime[tier] = 0
+  }
+
+  /**
+   * Reset health status for all tiers
+   */
+  resetAllTierHealth(): void {
+    this.resetTierHealth('hot')
+    this.resetTierHealth('warm')
+    this.resetTierHealth('cold')
+  }
+
+  /**
+   * Clear failure history and failure counts
+   */
+  clearFailureHistory(): void {
+    this.recentFailures = []
+    this.failureCounts = { hot: 0, warm: 0, cold: 0 }
+  }
+
+  /**
+   * Get combined statistics from all tiers
+   */
+  getStats(): TieredVFSStats {
+    return {
+      cache: this.cacheLayer.getStats(),
+      r2: this.r2Layer.getStats(),
+      do: { ...this.doStats },
+      promotions: { ...this.promotionStats },
+      demotions: { ...this.demotionStats },
+      tierHealth: this.getTierHealth(),
+    }
+  }
+
+  /**
+   * Reset all statistics
+   */
+  resetStats(): void {
+    this.doStats = {
+      reads: 0,
+      writes: 0,
+      deletes: 0,
+      bytesRead: 0,
+      bytesWritten: 0,
+    }
+    this.promotionStats = {
+      coldToWarm: 0,
+      warmToHot: 0,
+    }
+    this.demotionStats = {
+      hotToWarm: 0,
+      warmToCold: 0,
+    }
+    this.accessCounts.clear()
+  }
+
+  /**
+   * Get the configured page size
+   */
+  getPageSize(): number {
+    return this.pageSize
+  }
+
+  /**
+   * Get the access count for a key
+   */
+  getAccessCount(key: string): number {
+    return this.accessCounts.get(key) ?? 0
+  }
+
+  /**
+   * Get the promotion threshold
+   */
+  getPromotionThreshold(): number {
+    return this.promotionThreshold
+  }
+
+  /**
+   * Set the promotion threshold
+   */
+  setPromotionThreshold(threshold: number): void {
+    this.promotionThreshold = threshold
+  }
+
+  /**
+   * Enable or disable auto-promotion
+   */
+  setAutoPromote(enabled: boolean): void {
+    this.autoPromote = enabled
+  }
+}
+
+/**
+ * Create a new TieredVFS instance
+ *
+ * @param config - Configuration for the tiered VFS
+ * @returns A configured TieredVFS instance
+ */
+export function createTieredVFS(config: TieredVFSConfig): TieredVFS {
+  return new TieredVFS(config)
+}