@dotdo/postgres 0.1.0

package/src/storage/tiered-orchestrator.ts

@@ -0,0 +1,2081 @@
+/**
+ * TieredStorageOrchestrator - Unified Tiering System
+ *
+ * Orchestrates the complete tiered storage system with:
+ * - HOT tier: Cloudflare Cache API (FREE, sync-fast)
+ * - WARM tier: Durable Object SQLite blobs (persistent, sync)
+ * - COLD tier: R2 object storage (cheap, async)
+ *
+ * ## Features
+ * - Unified read/write interface across all tiers
+ * - Automatic promotion based on access patterns
+ * - Automatic demotion based on TTL/LRU policies
+ * - Cost-optimized tier selection
+ * - Comprehensive statistics and monitoring
+ * - Storage index for fast tier location lookups
+ * - DO lifecycle hooks (hibernate/wake)
+ * - Circuit breaker pattern for tier failures
+ * - Integrated metrics aggregation
+ * - Bounded storage index with LRU/LFU eviction
+ * - Detailed performance metrics and memory tracking
+ *
+ * ## Performance Characteristics
+ *
+ * ### Storage Index Operations
+ *
+ * | Operation     | Time Complexity | Typical Latency |
+ * |---------------|-----------------|-----------------|
+ * | Lookup (get)  | O(1) average    | 50-100ns        |
+ * | Update (set)  | O(1) amortized  | 100-200ns       |
+ * | Delete        | O(1)            | 50-100ns        |
+ * | Eviction      | O(n*k)          | 1-10ms/batch    |
+ * | Maintenance   | O(n * storage)  | 100ms-10s       |
+ *
+ * Where:
+ * - n = total index entries
+ * - k = eviction batch size (typically 10-20)
+ *
+ * ### Memory Usage
+ *
+ * The storage index uses approximately:
+ * - 120 bytes per entry (base overhead)
+ * - 2 bytes per character in key (JS UTF-16 strings)
+ * - ~10% additional for Map internal structures
+ *
+ * **Example Memory Usage:**
+ * | Entries | Avg Key Length | Estimated Memory |
+ * |---------|----------------|------------------|
+ * | 1,000   | 20 chars       | ~160 KB          |
+ * | 10,000  | 20 chars       | ~1.6 MB          |
+ * | 100,000 | 20 chars       | ~16 MB           |
+ * | 10,000  | 100 chars      | ~3.2 MB          |
+ *
+ * ### Eviction Policies
+ *
+ * - **LRU (default)**: Evicts least recently accessed entries first.
+ *   Best for: Most workloads with temporal locality.
+ *
+ * - **LFU**: Evicts least frequently accessed entries first.
+ *   Best for: Workloads with stable hot sets.
+ *
+ * - **FIFO**: Evicts oldest entries by creation time.
+ *   Best for: Predictable eviction patterns, debugging.
+ *
+ * ### Hot Path Optimizations
+ *
+ * 1. **Single-entry lookup cache**: Avoids redundant Map lookups when
+ *    the same key is accessed multiple times in quick succession
+ *    (e.g., read -> check promotion -> update index).
+ *
+ * 2. **Partial selection for eviction**: Uses O(n*k) partial selection
+ *    instead of O(n log n) full sort when evicting k entries from n.
+ *
+ * 3. **Batch eviction**: Amortizes eviction overhead across multiple
+ *    entries (configurable via indexEvictionBatchSize).
+ *
+ * ### Configuration Guidelines
+ *
+ * For Cloudflare Workers (128MB limit):
+ * ```typescript
+ * const orchestrator = createTieredStorageOrchestrator({
+ *   // ... other config
+ *   maxIndexEntries: 50000,           // ~8MB for 20-char keys
+ *   maxIndexMemoryBytes: 8 * 1024 * 1024, // 8MB hard limit
+ *   indexEvictionPolicy: 'lru',
+ *   indexEvictionBatchSize: 100,      // Evict 100 at a time
+ *   indexMemoryWarningThreshold: 0.8, // Warn at 80%
+ * })
+ * ```
+ *
+ * @module storage/tiered-orchestrator
+ */
+
+import type { CacheLayer, CacheLayerStats } from './cache-layer'
+import type { R2StorageLayer, R2StorageLayerStats } from './r2-layer'
+import type { SWRCacheLayer, SWRCacheStats, ExecutionContext } from './swr-cache'
+
+// =============================================================================
+// Imported Configuration Constants (from centralized config)
+// =============================================================================
+
+import {
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_COLD_TO_WARM_THRESHOLD,
+  DEFAULT_WARM_TO_HOT_THRESHOLD,
+  DEFAULT_PROMOTION_WINDOW_MS,
+  DEFAULT_HOT_TTL_MS,
+  DEFAULT_WARM_TTL_MS,
+  DEFAULT_MAX_HOT_PAGES,
+  DEFAULT_DO_PREFIX,
+  DEFAULT_INDEX_EVICTION_BATCH_SIZE,
+  DEFAULT_CIRCUIT_BREAKER_FAILURE_THRESHOLD,
+  DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS,
+} from '../config/storage'
+
+import {
+  INDEX_ENTRY_MEMORY_OVERHEAD_BYTES,
+  MAP_OVERHEAD_ESTIMATE_PERCENT,
+  DEFAULT_INDEX_MEMORY_WARNING_THRESHOLD,
+  INDEX_MEMORY_EVICTION_TARGET,
+  DEFAULT_AVG_KEY_LENGTH_CHARS,
+} from '../config/memory'
+
+import { assertNever } from '../types/utilities'
+
+// =============================================================================
+// Local Constant Aliases (for internal use)
+// =============================================================================
+
+/** Estimated bytes per index entry */
+const ENTRY_MEMORY_OVERHEAD_BYTES = INDEX_ENTRY_MEMORY_OVERHEAD_BYTES
+
+// =============================================================================
+// Timing Constants (local)
+// =============================================================================
+
+/**
+ * Nanoseconds per millisecond for performance timing conversions.
+ */
+const NS_PER_MS = 1e6
+
+// =============================================================================
+// 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'
+
+/**
+ * Tier health status
+ */
+export type TierHealth = 'healthy' | 'degraded' | 'unavailable'
+
+/**
+ * Circuit breaker state
+ */
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open'
+
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+  enabled: boolean
+  failureThreshold: number
+  resetTimeoutMs?: number
+  fallbackEnabled?: boolean
+}
+
+/**
+ * Circuit breaker state info
+ */
+export interface CircuitBreakerStateInfo {
+  state: CircuitBreakerState
+  failures: number
+  lastFailure?: number
+  lastSuccess?: number
+  openedAt?: number
+}
+
+/**
+ * Entry in the storage index tracking data locations
+ */
+export interface StorageIndexEntry {
+  key: string
+  tier: StorageTier
+  size: number
+  lastAccess: number
+  accessCount: number
+  created: number
+  modified: number
+  dirty: boolean
+}
+
+/**
+ * Hibernate state for DO lifecycle
+ */
+export interface HibernateState {
+  hotKeys: string[]
+  indexSnapshot: Map<string, StorageIndexEntry>
+  timestamp: number
+}
+
+/**
+ * Result of hibernate operation
+ */
+export interface HibernateResult {
+  success: boolean
+  persistedCount: number
+  syncedToCold: number
+  hotKeys: string[]
+  indexSnapshot: Map<string, StorageIndexEntry>
+  timestamp: number
+}
+
+/**
+ * Options for wake operation
+ */
+export interface WakeOptions {
+  prefetchThreshold?: number
+  validateIndex?: boolean
+}
+
+/**
+ * Result of wake operation
+ */
+export interface WakeResult {
+  restoredCount: number
+  prefetchedCount: number
+  indexValidated: boolean
+  indexRepairs: number
+}
+
+/**
+ * Alarm task type
+ */
+export type AlarmType = 'demotion' | 'sync'
+
+/**
+ * Alarm configuration
+ */
+export interface AlarmConfig {
+  type: AlarmType
+  delayMs: number
+  skipIfExists?: boolean
+  rescheduleMs?: number
+}
+
+/**
+ * Result of alarm handling
+ */
+export interface AlarmResult {
+  demotionCount?: number
+  syncedCount?: number
+  nextAlarmMs?: number
+}
+
+/**
+ * Aggregated metrics from all components
+ */
+export interface AggregatedMetrics {
+  timestamp: number
+  period: string
+  tiers: {
+    hot: { reads: number; writes: number; hitRatio: number; bytesRead: number; bytesWritten: number }
+    warm: { reads: number; writes: number; bytesStored: number; bytesRead: number; bytesWritten: number }
+    cold: { reads: number; writes: number; bytesStored: number; bytesRead: number; bytesWritten: number }
+  }
+  migrations: { promotions: number; demotions: number; failures: number }
+  circuitBreakers: Record<StorageTier, CircuitBreakerStateInfo>
+  latency?: { p50: number; p95: number; p99: number }
+  estimatedCost?: { r2: number; do: number; cache: number; total: number }
+  errors: { totalErrors: number; byTier: Record<StorageTier, number> }
+}
+
+/**
+ * Auto-promoter configuration
+ */
+export interface AutoPromoterConfig {
+  coldToWarm: { accessThreshold: number; timeWindowMs?: number }
+  warmToHot: { accessThreshold: number; timeWindowMs?: number }
+}
+
+/**
+ * Auto-demoter configuration
+ */
+export interface AutoDemoterConfig {
+  hotToWarm: { ttlMs: number; maxEntries?: number }
+  warmToCold: { ttlMs: number; maxEntries?: number }
+}
+
+/**
+ * VFS interface for PGLite integration
+ */
+export interface VFSInterface {
+  readPage: (pageId: string) => Promise<Uint8Array | null>
+  writePage: (pageId: string, data: Uint8Array) => Promise<void>
+  deletePage: (pageId: string) => Promise<void>
+}
+
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+  trackLatency?: boolean
+  trackCost?: boolean
+  costConfig?: {
+    r2StoragePerGBMonth: number
+    r2ClassAOperations: number
+    r2ClassBOperations: number
+    doStoragePerGBMonth: number
+    cacheOperations: number
+  }
+}
+
+/**
+ * Observable error with context
+ */
+export interface ObservableError {
+  context: string
+  error: Error
+  tier?: StorageTier
+  key?: string
+  timestamp: number
+  retryCount?: number
+  correlationId?: string
+}
+
+/**
+ * Error observer callback type
+ */
+export type ErrorObserver = (error: ObservableError) => void
+
+/**
+ * Circuit breaker change event
+ */
+export interface CircuitBreakerChangeEvent {
+  tier: StorageTier
+  state: CircuitBreakerState
+  failures: number
+  error?: Error | undefined
+}
+
+/**
+ * Circuit breaker change observer callback type
+ */
+export type CircuitBreakerChangeObserver = (event: CircuitBreakerChangeEvent) => void
+
+/**
+ * Logger interface for debug logging
+ */
+export interface Logger {
+  debug: (msg: string) => void
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+/**
+ * Demotion strategy function
+ */
+export type DemotionStrategy = (entries: StorageIndexEntry[], count: number) => string[]
+
+/**
+ * Index eviction policy
+ */
+export type IndexEvictionPolicy = 'lru' | 'lfu' | 'fifo'
+
+/**
+ * Callback for index eviction events
+ */
+export type IndexEvictionCallback = (evictedKeys: string[]) => void
+
+/**
+ * Configuration for the TieredStorageOrchestrator
+ */
+export interface TieredOrchestratorConfig {
+  cacheLayer?: CacheLayer
+  swrCacheLayer?: SWRCacheLayer
+  doStorage: DurableObjectStorage
+  r2Layer: R2StorageLayer
+  pageSize?: number
+  coldToWarmThreshold?: number
+  warmToHotThreshold?: number
+  promotionWindowMs?: number
+  hotTtlMs?: number
+  warmTtlMs?: number
+  maxHotPages?: number
+  autoPromote?: boolean
+  autoDemote?: boolean
+  writeThrough?: boolean
+  doPrefix?: string
+  circuitBreaker?: CircuitBreakerConfig
+  metrics?: MetricsConfig
+  logger?: Logger
+  // Index bounds configuration
+  maxIndexEntries?: number
+  maxIndexMemoryBytes?: number
+  indexEvictionPolicy?: IndexEvictionPolicy
+  indexEvictionBatchSize?: number
+  indexMemoryWarningThreshold?: number
+  indexMaintenanceIntervalMs?: number
+  onIndexEviction?: IndexEvictionCallback
+}
+
+/**
+ * Options for read operations
+ */
+export interface ReadOptions {
+  skipPromotion?: boolean
+  skipTracking?: boolean
+  ctx?: ExecutionContext
+}
+
+/**
+ * Options for write operations
+ */
+export interface WriteOptions {
+  tier?: StorageTier
+  metadata?: Record<string, string>
+  writeThrough?: boolean
+  skipIndex?: boolean
+}
+
+/**
+ * Result of a read operation with tier information
+ */
+export interface ReadResult {
+  data: Uint8Array | null
+  tier?: StorageTier | undefined
+  stale?: boolean | undefined
+  revalidating?: boolean | undefined
+  fallback?: boolean | undefined
+}
+
+/**
+ * Promotion/demotion event
+ */
+export interface TierMigrationEvent {
+  key: string
+  fromTier: StorageTier
+  toTier: StorageTier
+  success: boolean
+  timestamp: number
+  error?: string
+  reason: 'access_pattern' | 'ttl_expired' | 'lru_eviction' | 'manual' | 'write_through'
+}
+
+export type TierMigrationCallback = (event: TierMigrationEvent) => void
+
+/**
+ * Performance metrics for index operations
+ *
+ * Tracks timing and operation counts for performance analysis:
+ * - lookupCount: Total number of index lookups (get operations)
+ * - updateCount: Total number of index updates (set/modify operations)
+ * - evictionCount: Total number of entries evicted
+ * - avgLookupTimeNs: Average lookup time in nanoseconds
+ * - avgUpdateTimeNs: Average update time in nanoseconds
+ * - evictionTimeNs: Total time spent on eviction in nanoseconds
+ * - maintenanceTimeNs: Total time spent on maintenance in nanoseconds
+ * - peakEntries: Peak number of entries observed
+ * - peakMemoryBytes: Peak memory usage observed
+ */
+export interface IndexPerformanceMetrics {
+  // Operation counts
+  lookupCount: number
+  updateCount: number
+  evictionCount: number
+  // Timing metrics (nanoseconds for precision)
+  totalLookupTimeNs: number
+  totalUpdateTimeNs: number
+  totalEvictionTimeNs: number
+  totalMaintenanceTimeNs: number
+  // Derived metrics (computed on request)
+  avgLookupTimeNs: number
+  avgUpdateTimeNs: number
+  // Peak tracking
+  peakEntries: number
+  peakMemoryBytes: number
+  // Efficiency metrics
+  evictionBatches: number
+  entriesPerEvictionBatch: number
+  // Hot path metrics
+  cacheHitCount: number
+  cacheMissCount: number
+}
+
+/**
+ * Statistics for the orchestrator
+ */
+export interface OrchestratorStats {
+  index: {
+    totalEntries: number
+    byTier: Record<StorageTier, number>
+    totalSize: number
+    dirtyEntries: number
+    memoryBytes: number
+    /** Performance metrics for index operations */
+    performance: IndexPerformanceMetrics
+  }
+  hot: CacheLayerStats | SWRCacheStats
+  warm: {
+    reads: number
+    writes: number
+    deletes: number
+    bytesRead: number
+    bytesWritten: number
+  }
+  cold: R2StorageLayerStats
+  promotions: {
+    coldToWarm: number
+    warmToHot: number
+    failed: number
+  }
+  demotions: {
+    hotToWarm: number
+    warmToCold: number
+    failed: number
+  }
+  health: Record<StorageTier, TierHealth>
+  errors: Record<StorageTier, number>
+}
+
+// Internal config type with all required fields
+interface InternalConfig {
+  pageSize: number
+  coldToWarmThreshold: number
+  warmToHotThreshold: number
+  promotionWindowMs: number
+  hotTtlMs: number
+  warmTtlMs: number
+  maxHotPages: number
+  autoPromote: boolean
+  autoDemote: boolean
+  writeThrough: boolean
+  doPrefix: string
+  circuitBreaker?: CircuitBreakerConfig | undefined
+  metrics?: MetricsConfig | undefined
+  logger?: Logger | undefined
+  maxIndexEntries?: number | undefined
+  maxIndexMemoryBytes?: number | undefined
+  indexEvictionPolicy: IndexEvictionPolicy
+  indexEvictionBatchSize: number
+  indexMemoryWarningThreshold: number
+  indexMaintenanceIntervalMs?: number | undefined
+  onIndexEviction?: IndexEvictionCallback | undefined
+}
+
+/**
+ * TieredStorageOrchestrator - Unified Tiering System
+ *
+ * ## Performance Characteristics
+ *
+ * ### Index Operations
+ * - **Lookup (get)**: O(1) average via Map, ~50-100ns typical
+ * - **Update (set/modify)**: O(1) average for existing keys, O(1) amortized for new keys
+ * - **Eviction**: O(n*k) where n=index size, k=batch size; optimized for k << n
+ *
+ * ### Memory Usage
+ * - **Per-entry overhead**: ~120 bytes base + 2 bytes per character in key
+ * - **Example**: 10,000 entries with 20-char keys = ~1.6MB
+ * - **Warning threshold**: Configurable, default 80% of maxIndexMemoryBytes
+ *
+ * ### Eviction Policies
+ * - **LRU (default)**: Evicts least recently accessed entries
+ * - **LFU**: Evicts least frequently accessed entries
+ * - **FIFO**: Evicts oldest entries by creation time
+ *
+ * ### Hot Path Optimizations
+ * - Index entry caching for repeated lookups within promotion checks
+ * - Batch eviction to amortize overhead across multiple entries
+ * - Partial selection algorithm for eviction (avoids full sort when k << n)
+ *
+ * @class TieredStorageOrchestrator
+ */
+export class TieredStorageOrchestrator {
+  private cacheLayer?: CacheLayer | undefined
+  private swrCacheLayer?: SWRCacheLayer | undefined
+  private doStorage: DurableObjectStorage
+  private r2Layer: R2StorageLayer
+  private config: InternalConfig
+
+  private storageIndex: Map<string, StorageIndexEntry> = new Map()
+  private indexMemoryBytes: number = 0
+  private maintenanceTimer?: ReturnType<typeof setInterval> | undefined
+  private memoryWarningEmitted: boolean = false
+
+  /**
+   * Estimated memory per index entry (key string avg ~20 chars + StorageIndexEntry object)
+   *
+   * Breakdown:
+   * - Map entry overhead: ~40 bytes (key reference + value reference + internal structure)
+   * - StorageIndexEntry object: ~80 bytes (8 bytes per field * 9 fields + object overhead)
+   * - Total base: ~120 bytes per entry
+   * - Key string: 2 bytes per character (JS strings are UTF-16)
+   */
+  private static readonly ENTRY_MEMORY_OVERHEAD = ENTRY_MEMORY_OVERHEAD_BYTES
+
+  // Performance metrics tracking
+  private performanceMetrics = {
+    lookupCount: 0,
+    updateCount: 0,
+    evictionCount: 0,
+    totalLookupTimeNs: 0,
+    totalUpdateTimeNs: 0,
+    totalEvictionTimeNs: 0,
+    totalMaintenanceTimeNs: 0,
+    peakEntries: 0,
+    peakMemoryBytes: 0,
+    evictionBatches: 0,
+    cacheHitCount: 0,
+    cacheMissCount: 0,
+  }
+
+  // Cache for hot path optimization - stores recently looked up entry for promotion check
+  private lastLookupKey: string | null = null
+  private lastLookupEntry: StorageIndexEntry | null = null
+
+  private warmStats = { reads: 0, writes: 0, deletes: 0, bytesRead: 0, bytesWritten: 0 }
+  private promotionStats = { coldToWarm: 0, warmToHot: 0, failed: 0 }
+  private demotionStats = { hotToWarm: 0, warmToCold: 0, failed: 0 }
+  private tierHealth: Record<StorageTier, TierHealth> = { hot: 'healthy', warm: 'healthy', cold: 'healthy' }
+
+  private circuitBreakers: Record<StorageTier, CircuitBreakerStateInfo> = {
+    hot: { state: 'closed', failures: 0 },
+    warm: { state: 'closed', failures: 0 },
+    cold: { state: 'closed', failures: 0 },
+  }
+
+  private latencyMeasurements: number[] = []
+  private demotionStrategies: Partial<Record<StorageTier, DemotionStrategy>> = {}
+  private autoPromoterConfig: AutoPromoterConfig = { coldToWarm: { accessThreshold: DEFAULT_COLD_TO_WARM_THRESHOLD }, warmToHot: { accessThreshold: DEFAULT_WARM_TO_HOT_THRESHOLD } }
+  private autoDemoterConfig: AutoDemoterConfig = { hotToWarm: { ttlMs: DEFAULT_HOT_TTL_MS }, warmToCold: { ttlMs: DEFAULT_WARM_TTL_MS } }
+  private migrationCallbacks: TierMigrationCallback[] = []
+  private errorObservers: ErrorObserver[] = []
+  private circuitBreakerObservers: CircuitBreakerChangeObserver[] = []
+  private errorCounts: Record<StorageTier, number> = { hot: 0, warm: 0, cold: 0 }
+  private keyRetryCounters: Map<string, number> = new Map()
+  private correlationCounter = 0
+  private eventSubscribers: Array<{ callback: TierMigrationCallback; filter?: { type?: 'promotion' | 'demotion' } | undefined }> = []
+  private entryPriorities: Map<string, 'low' | 'normal' | 'high'> = new Map()
+  private pinnedEntries: Set<string> = new Set()
+  private memoryLimits: Partial<Record<StorageTier, number>> = {}
+
+  constructor(config: TieredOrchestratorConfig) {
+    this.cacheLayer = config.cacheLayer
+    this.swrCacheLayer = config.swrCacheLayer
+    this.doStorage = config.doStorage
+    this.r2Layer = config.r2Layer
+    this.config = {
+      pageSize: config.pageSize ?? DEFAULT_PAGE_SIZE,
+      coldToWarmThreshold: config.coldToWarmThreshold ?? DEFAULT_COLD_TO_WARM_THRESHOLD,
+      warmToHotThreshold: config.warmToHotThreshold ?? DEFAULT_WARM_TO_HOT_THRESHOLD,
+      promotionWindowMs: config.promotionWindowMs ?? DEFAULT_PROMOTION_WINDOW_MS,
+      hotTtlMs: config.hotTtlMs ?? DEFAULT_HOT_TTL_MS,
+      warmTtlMs: config.warmTtlMs ?? DEFAULT_WARM_TTL_MS,
+      maxHotPages: config.maxHotPages ?? DEFAULT_MAX_HOT_PAGES,
+      autoPromote: config.autoPromote ?? true,
+      autoDemote: config.autoDemote ?? true,
+      writeThrough: config.writeThrough ?? false,
+      doPrefix: config.doPrefix ?? DEFAULT_DO_PREFIX,
+      circuitBreaker: config.circuitBreaker,
+      metrics: config.metrics,
+      logger: config.logger,
+      // Index bounds configuration
+      maxIndexEntries: config.maxIndexEntries,
+      maxIndexMemoryBytes: config.maxIndexMemoryBytes,
+      indexEvictionPolicy: config.indexEvictionPolicy ?? 'lru',
+      indexEvictionBatchSize: config.indexEvictionBatchSize ?? DEFAULT_INDEX_EVICTION_BATCH_SIZE,
+      indexMemoryWarningThreshold: config.indexMemoryWarningThreshold ?? DEFAULT_INDEX_MEMORY_WARNING_THRESHOLD,
+      indexMaintenanceIntervalMs: config.indexMaintenanceIntervalMs,
+      onIndexEviction: config.onIndexEviction,
+    }
+    this.autoPromoterConfig = {
+      coldToWarm: { accessThreshold: this.config.coldToWarmThreshold },
+      warmToHot: { accessThreshold: this.config.warmToHotThreshold, timeWindowMs: this.config.promotionWindowMs },
+    }
+    this.autoDemoterConfig = {
+      hotToWarm: { ttlMs: this.config.hotTtlMs },
+      warmToCold: { ttlMs: this.config.warmTtlMs },
+    }
+    // Start maintenance timer if configured
+    if (this.config.indexMaintenanceIntervalMs) {
+      this.startIndexMaintenance()
+    }
+  }
+
+  onMigration(callback: TierMigrationCallback): void { this.migrationCallbacks.push(callback) }
+  onError(callback: ErrorObserver): void { this.errorObservers.push(callback) }
+  onCircuitBreakerChange(callback: CircuitBreakerChangeObserver): void { this.circuitBreakerObservers.push(callback) }
+
+  private notifyError(error: ObservableError): void {
+    if (error.tier) this.errorCounts[error.tier]++
+    if (this.config.logger) {
+      if (error.context === 'tier_read_failure' && error.tier) {
+        this.config.logger.warn(`${error.tier} tier read failed: ${error.error.message}${error.key ? ` (key: ${error.key})` : ''}`)
+      } else {
+        this.config.logger.warn(`${error.context}: ${error.error.message}${error.key ? ` (key: ${error.key})` : ''}${error.tier ? ` (tier: ${error.tier})` : ''}`)
+      }
+    }
+    for (const callback of this.errorObservers) {
+      try { callback(error) } catch { /* ignore observer errors */ }
+    }
+  }
+
+  private notifyCircuitBreakerChange(event: CircuitBreakerChangeEvent): void {
+    this.config.logger?.warn(`Circuit breaker ${event.tier} changed to ${event.state} (failures: ${event.failures})`)
+    for (const callback of this.circuitBreakerObservers) {
+      try { callback(event) } catch { /* ignore observer errors */ }
+    }
+  }
+
+  private notifyMigration(event: TierMigrationEvent): void {
+    for (const callback of this.migrationCallbacks) {
+      try { callback(event) } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e))
+        this.notifyError({
+          context: 'migration_callback',
+          error,
+          key: event.key,
+          timestamp: Date.now(),
+        })
+      }
+    }
+    // Also notify event subscribers
+    if (this.eventSubscribers && this.eventSubscribers.length > 0) {
+      const isPromotion = event.toTier === 'hot' || (event.fromTier === 'cold' && event.toTier === 'warm')
+      for (const { callback, filter } of this.eventSubscribers) {
+        if (filter?.type === 'promotion' && !isPromotion) continue
+        if (filter?.type === 'demotion' && isPromotion) continue
+        try { callback(event) } catch { /* ignore */ }
+      }
+    }
+  }
+
+  private doKey(key: string): string { return `${this.config.doPrefix}${key}` }
+
+  /**
+   * High-resolution timer for performance measurement
+   * Uses performance.now() when available, falls back to Date.now() * 1e6
+   */
+  private getNowNs(): number {
+    if (typeof performance !== 'undefined' && performance.now) {
+      return performance.now() * NS_PER_MS // Convert ms to ns
+    }
+    return Date.now() * NS_PER_MS
+  }
+
+  /**
+   * Update the storage index with entry information
+   *
+   * Performance characteristics:
+   * - O(1) for existing keys (direct Map update)
+   * - O(1) amortized for new keys (may trigger eviction)
+   * - Tracks timing for performance metrics
+   *
+   * @param key - The storage key
+   * @param tier - The storage tier where data resides
+   * @param size - Size of the data in bytes
+   * @param dirty - Whether the entry has uncommitted changes
+   */
+  private updateIndex(key: string, tier: StorageTier, size: number, dirty = false): void {
+    const startNs = this.getNowNs()
+    this.performanceMetrics.updateCount++
+
+    const existing = this.storageIndex.get(key)
+    const now = Date.now()
+    if (existing) {
+      existing.tier = tier
+      existing.size = size
+      existing.lastAccess = now
+      existing.accessCount++
+      existing.modified = now
+      existing.dirty = dirty
+      // Invalidate lookup cache if this was the cached entry
+      if (this.lastLookupKey === key) {
+        this.lastLookupEntry = existing
+      }
+    } else {
+      // Check if we need to evict before adding
+      this.enforceIndexBounds()
+      const newEntry: StorageIndexEntry = { key, tier, size, lastAccess: now, accessCount: 1, created: now, modified: now, dirty }
+      this.storageIndex.set(key, newEntry)
+      // Update memory tracking
+      this.indexMemoryBytes += TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD + key.length * 2
+      // Track peak values
+      if (this.storageIndex.size > this.performanceMetrics.peakEntries) {
+        this.performanceMetrics.peakEntries = this.storageIndex.size
+      }
+      if (this.indexMemoryBytes > this.performanceMetrics.peakMemoryBytes) {
+        this.performanceMetrics.peakMemoryBytes = this.indexMemoryBytes
+      }
+      // Check memory warning threshold
+      this.checkMemoryWarning()
+    }
+
+    this.performanceMetrics.totalUpdateTimeNs += this.getNowNs() - startNs
+  }
+
+  /**
+   * Enforce index bounds by evicting entries if necessary
+   */
+  private enforceIndexBounds(): void {
+    // Check entry count limit
+    if (this.config.maxIndexEntries && this.storageIndex.size >= this.config.maxIndexEntries) {
+      this.evictIndexEntries(this.config.indexEvictionBatchSize)
+    }
+    // Check memory limit
+    if (this.config.maxIndexMemoryBytes && this.indexMemoryBytes >= this.config.maxIndexMemoryBytes) {
+      // Estimate how many entries to evict based on average entry size
+      const avgEntrySize = this.indexMemoryBytes / Math.max(1, this.storageIndex.size)
+      const targetBytes = this.config.maxIndexMemoryBytes * INDEX_MEMORY_EVICTION_TARGET // Target 80% of limit
+      const bytesToFree = this.indexMemoryBytes - targetBytes
+      const entriesToEvict = Math.max(1, Math.ceil(bytesToFree / avgEntrySize))
+      this.evictIndexEntries(entriesToEvict)
+    }
+  }
+
+  /**
+   * Select the k entries with the smallest scores (partial selection)
+   *
+   * Uses a simple O(n*k) algorithm which is efficient when k << n.
+   * For large k values, this degrades gracefully but still avoids
+   * the memory overhead of creating and sorting a full array copy.
+   */
+  private selectSmallestEntries(k: number, getScore: (entry: StorageIndexEntry) => number): StorageIndexEntry[] {
+    const result: StorageIndexEntry[] = []
+    const resultScores: number[] = []
+
+    for (const entry of this.storageIndex.values()) {
+      const score = getScore(entry)
+
+      if (result.length < k) {
+        // Still building up the result set
+        result.push(entry)
+        resultScores.push(score)
+      } else {
+        // Find the entry with the highest score in our result (the one to potentially replace)
+        let maxIdx = 0
+        let maxScore = resultScores[0] ?? 0
+        for (let i = 1; i < resultScores.length; i++) {
+          const currentScore = resultScores[i] ?? 0
+          if (currentScore > maxScore) {
+            maxIdx = i
+            maxScore = currentScore
+          }
+        }
+        // If this entry has a lower score, replace the max
+        if (score < maxScore) {
+          result[maxIdx] = entry
+          resultScores[maxIdx] = score
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Evict entries from the index based on configured policy
+   *
+   * ## Performance Characteristics
+   *
+   * **Time Complexity**: O(n*k) where n=index size, k=entries to evict
+   * - Uses partial selection instead of full sort O(n log n)
+   * - Efficient when k << n (typical case: k=10-20, n=10000+)
+   *
+   * **Space Complexity**: O(k) for the result buffer
+   * - Does not create intermediate arrays of size n
+   *
+   * **Memory optimization**: Uses partial selection instead of full sort.
+   * This is more efficient when evicting a small batch from a large index.
+   *
+   * @param count - Number of entries to evict
+   */
+  private evictIndexEntries(count: number): void {
+    if (this.storageIndex.size === 0 || count <= 0) return
+
+    const startNs = this.getNowNs()
+
+    // Select comparison function based on policy
+    let getScore: (entry: StorageIndexEntry) => number
+    switch (this.config.indexEvictionPolicy) {
+      case 'lfu':
+        // Least Frequently Used - lower accessCount = evict first
+        getScore = (e) => e.accessCount
+        break
+      case 'fifo':
+        // First In First Out - older created = evict first
+        getScore = (e) => e.created
+        break
+      case 'lru':
+      default:
+        // Least Recently Used - older lastAccess = evict first
+        getScore = (e) => e.lastAccess
+        break
+    }
+
+    // Use partial selection: find the k entries with smallest scores
+    // This avoids full sort when count << size
+    const toEvict = this.selectSmallestEntries(count, getScore)
+    const evictedKeys: string[] = []
+
+    for (const entry of toEvict) {
+      this.storageIndex.delete(entry.key)
+      this.indexMemoryBytes -= TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD + entry.key.length * 2
+      evictedKeys.push(entry.key)
+      // Invalidate lookup cache if evicted
+      if (this.lastLookupKey === entry.key) {
+        this.lastLookupKey = null
+        this.lastLookupEntry = null
+      }
+    }
+
+    // Update performance metrics
+    this.performanceMetrics.evictionCount += evictedKeys.length
+    this.performanceMetrics.evictionBatches++
+    this.performanceMetrics.totalEvictionTimeNs += this.getNowNs() - startNs
+
+    // Ensure memory tracking doesn't go negative
+    if (this.indexMemoryBytes < 0) this.indexMemoryBytes = 0
+
+    // Notify callback if configured
+    if (this.config.onIndexEviction && evictedKeys.length > 0) {
+      try {
+        this.config.onIndexEviction(evictedKeys)
+      } catch (e) {
+        // Ignore callback errors
+        this.config.logger?.warn(`Index eviction callback error: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
+  }
+
+  /**
+   * Check and emit memory warning if threshold exceeded
+   */
+  private checkMemoryWarning(): void {
+    if (!this.config.maxIndexMemoryBytes || this.memoryWarningEmitted) return
+
+    const threshold = this.config.maxIndexMemoryBytes * this.config.indexMemoryWarningThreshold
+    if (this.indexMemoryBytes >= threshold) {
+      this.memoryWarningEmitted = true
+      this.config.logger?.warn(`Index memory approaching limit: ${this.indexMemoryBytes} bytes (${Math.round(this.indexMemoryBytes / this.config.maxIndexMemoryBytes * 100)}% of ${this.config.maxIndexMemoryBytes} bytes)`)
+    }
+  }
+
+  /**
+   * Start periodic index maintenance
+   */
+  private startIndexMaintenance(): void {
+    if (this.maintenanceTimer) return
+    this.maintenanceTimer = setInterval(async () => {
+      try {
+        await this.runIndexMaintenance()
+      } catch (e) {
+        this.config.logger?.warn(`Index maintenance error: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }, this.config.indexMaintenanceIntervalMs!)
+  }
+
+  /**
+   * Stop periodic index maintenance
+   */
+  stopIndexMaintenance(): void {
+    if (this.maintenanceTimer) {
+      clearInterval(this.maintenanceTimer)
+      this.maintenanceTimer = undefined
+    }
+  }
+
+  /**
+   * Run index maintenance - clean up stale entries
+   *
+   * ## Performance Characteristics
+   *
+   * **Time Complexity**: O(n * storage_ops) where n = index entries
+   * - Each entry may require 1-2 storage lookups
+   * - Storage ops are async and may have network latency
+   *
+   * **When to Run**:
+   * - Periodically via indexMaintenanceIntervalMs config
+   * - After suspected data loss or corruption
+   * - During low-traffic periods to avoid impacting hot path
+   *
+   * @returns Object with count of removed stale entries and timing info
+   */
+  async runIndexMaintenance(): Promise<{ removed: number; durationMs: number }> {
+    const startNs = this.getNowNs()
+    let removed = 0
+    const keysToRemove: string[] = []
+
+    for (const [key, entry] of this.storageIndex) {
+      // Check if data still exists in the indicated tier
+      let exists = false
+
+      if (entry.tier === 'hot') {
+        // Hot tier - assume it might have been evicted, check warm/cold
+        const warmData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+        if (warmData) {
+          entry.tier = 'warm'
+          exists = true
+        } else {
+          const coldData = await this.r2Layer.get(key)
+          if (coldData) {
+            entry.tier = 'cold'
+            exists = true
+          }
+        }
+      } else if (entry.tier === 'warm') {
+        const warmData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+        if (warmData) {
+          exists = true
+        } else {
+          const coldData = await this.r2Layer.get(key)
+          if (coldData) {
+            entry.tier = 'cold'
+            exists = true
+          }
+        }
+      } else {
+        const coldData = await this.r2Layer.get(key)
+        exists = !!coldData
+      }
+
+      if (!exists) {
+        keysToRemove.push(key)
+      }
+    }
+
+    for (const key of keysToRemove) {
+      const entry = this.storageIndex.get(key)
+      if (entry) {
+        this.storageIndex.delete(key)
+        this.indexMemoryBytes -= TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD + key.length * 2
+        removed++
+        // Invalidate cache if needed
+        if (this.lastLookupKey === key) {
+          this.lastLookupKey = null
+          this.lastLookupEntry = null
+        }
+      }
+    }
+
+    if (this.indexMemoryBytes < 0) this.indexMemoryBytes = 0
+
+    const durationNs = this.getNowNs() - startNs
+    this.performanceMetrics.totalMaintenanceTimeNs += durationNs
+
+    return { removed, durationMs: durationNs / 1e6 }
+  }
+
+  /**
+   * Optimized index lookup with single-entry cache
+   *
+   * The hot path often involves looking up the same key multiple times
+   * in quick succession (read -> check promotion -> update index).
+   * This cache avoids redundant Map lookups.
+   *
+   * @param key - The key to look up
+   * @returns The index entry or undefined if not found
+   */
+  private getIndexEntryOptimized(key: string): StorageIndexEntry | undefined {
+    const startNs = this.getNowNs()
+    this.performanceMetrics.lookupCount++
+
+    // Check single-entry cache first (hot path optimization)
+    if (this.lastLookupKey === key && this.lastLookupEntry) {
+      this.performanceMetrics.cacheHitCount++
+      this.performanceMetrics.totalLookupTimeNs += this.getNowNs() - startNs
+      return this.lastLookupEntry
+    }
+
+    this.performanceMetrics.cacheMissCount++
+    const entry = this.storageIndex.get(key)
+
+    // Update cache
+    this.lastLookupKey = key
+    this.lastLookupEntry = entry ?? null
+
+    this.performanceMetrics.totalLookupTimeNs += this.getNowNs() - startNs
+    return entry
+  }
+
+  /**
+   * Check if a key should be promoted to a higher tier
+   *
+   * Uses optimized lookup to avoid redundant Map accesses.
+   *
+   * @param key - The storage key
+   * @param currentTier - The current tier of the data
+   * @returns Promotion decision with target tier if applicable
+   */
+  private shouldPromote(key: string, currentTier: StorageTier): { promote: boolean; targetTier?: StorageTier } {
+    if (!this.config.autoPromote) return { promote: false }
+    const entry = this.getIndexEntryOptimized(key)
+    if (!entry) return { promote: false }
+    if (currentTier === 'cold' && entry.accessCount >= this.config.coldToWarmThreshold) return { promote: true, targetTier: 'warm' }
+    if (currentTier === 'warm' && entry.accessCount >= this.config.warmToHotThreshold) {
+      const age = Date.now() - entry.created
+      if (age <= this.config.promotionWindowMs) return { promote: true, targetTier: 'hot' }
+    }
+    return { promote: false }
+  }
+
+  private isCircuitOpen(tier: StorageTier): boolean {
+    if (!this.config.circuitBreaker?.enabled) return false
+    const cb = this.circuitBreakers[tier]
+    if (cb.state === 'open' && cb.openedAt) {
+      const resetTimeout = this.config.circuitBreaker.resetTimeoutMs ?? DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS
+      if (Date.now() - cb.openedAt >= resetTimeout) { cb.state = 'half-open'; return false }
+    }
+    return cb.state === 'open'
+  }
+
+  private recordCircuitBreakerFailure(tier: StorageTier, error?: Error): void {
+    if (!this.config.circuitBreaker?.enabled) return
+    const cb = this.circuitBreakers[tier]
+    cb.failures++
+    cb.lastFailure = Date.now()
+    if (cb.failures >= (this.config.circuitBreaker.failureThreshold ?? DEFAULT_CIRCUIT_BREAKER_FAILURE_THRESHOLD)) {
+      cb.state = 'open'
+      cb.openedAt = Date.now()
+      this.notifyCircuitBreakerChange({ tier, state: 'open', failures: cb.failures, error })
+    }
+  }
+
+  private recordCircuitBreakerSuccess(tier: StorageTier): void {
+    if (!this.config.circuitBreaker?.enabled) return
+    const cb = this.circuitBreakers[tier]
+    cb.lastSuccess = Date.now()
+    if (cb.state === 'half-open') { cb.state = 'closed'; cb.failures = 0 }
+  }
+
+  async read(key: string, options?: ReadOptions): Promise<ReadResult> {
+    const startTime = this.config.metrics?.trackLatency ? Date.now() : 0
+    const skipPromotion = options?.skipPromotion ?? false
+    const skipTracking = options?.skipTracking ?? false
+    const ctx = options?.ctx
+    const correlationId = `read-${++this.correlationCounter}`
+    const retryCount = this.keyRetryCounters.get(key) ?? 0
+    this.keyRetryCounters.set(key, retryCount + 1)
+    const coldCircuitOpen = this.isCircuitOpen('cold')
+    const recordLatency = () => { if (this.config.metrics?.trackLatency && startTime > 0) { this.latencyMeasurements.push(Date.now() - startTime); if (this.latencyMeasurements.length > 1000) this.latencyMeasurements.shift() } }
+
+    if (this.swrCacheLayer) {
+      try {
+        const result = await this.swrCacheLayer.get(key, ctx)
+        if (result.hit) {
+          if (!skipTracking) this.updateIndex(key, 'hot', result.data?.length ?? 0)
+          this.recordCircuitBreakerSuccess('hot')
+          recordLatency()
+          return { data: result.data, tier: 'hot', stale: result.stale, revalidating: result.revalidating }
+        }
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e))
+        this.tierHealth.hot = 'degraded'
+        this.recordCircuitBreakerFailure('hot', error)
+        this.notifyError({ context: 'tier_read_failure', error, tier: 'hot', key, timestamp: Date.now(), retryCount, correlationId })
+      }
+    } else if (this.cacheLayer) {
+      try {
+        const cached = await this.cacheLayer.get(key)
+        if (cached) {
+          if (!skipTracking) this.updateIndex(key, 'hot', cached.length)
+          this.recordCircuitBreakerSuccess('hot')
+          recordLatency()
+          return { data: cached, tier: 'hot' }
+        }
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e))
+        this.tierHealth.hot = 'degraded'
+        this.recordCircuitBreakerFailure('hot', error)
+        this.notifyError({ context: 'tier_read_failure', error, tier: 'hot', key, timestamp: Date.now(), retryCount, correlationId })
+      }
+    }
+
+    try {
+      const doData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+      if (doData) {
+        this.warmStats.reads++
+        this.warmStats.bytesRead += doData.length
+        if (!skipTracking) this.updateIndex(key, 'warm', doData.length)
+        this.recordCircuitBreakerSuccess('warm')
+        if (!skipPromotion) {
+          const { promote, targetTier } = this.shouldPromote(key, 'warm')
+          if (promote && targetTier === 'hot') this.promoteToHot(key, doData).catch(() => {})
+        }
+        recordLatency()
+        return { data: doData, tier: 'warm', fallback: coldCircuitOpen ? true : undefined }
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e))
+      this.tierHealth.warm = 'degraded'
+      this.recordCircuitBreakerFailure('warm', error)
+      this.notifyError({ context: 'tier_read_failure', error, tier: 'warm', key, timestamp: Date.now(), retryCount, correlationId })
+    }
+
+    if (coldCircuitOpen) { recordLatency(); return { data: null } }
+
+    try {
+      const r2Data = await this.r2Layer.get(key)
+      if (r2Data) {
+        if (!skipTracking) this.updateIndex(key, 'cold', r2Data.length)
+        this.recordCircuitBreakerSuccess('cold')
+        if (!skipPromotion) {
+          const { promote, targetTier } = this.shouldPromote(key, 'cold')
+          if (promote && targetTier === 'warm') this.promoteToWarm(key, r2Data).catch(() => {})
+        }
+        recordLatency()
+        return { data: r2Data, tier: 'cold' }
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e))
+      this.tierHealth.cold = 'degraded'
+      this.recordCircuitBreakerFailure('cold', error)
+      this.notifyError({ context: 'tier_read_failure', error, tier: 'cold', key, timestamp: Date.now(), retryCount, correlationId })
+    }
+
+    recordLatency()
+    return { data: null }
+  }
+
+  async write(key: string, data: Uint8Array, options?: WriteOptions): Promise<void> {
+    const tier = options?.tier ?? 'warm'
+    const writeThrough = options?.writeThrough ?? this.config.writeThrough
+    const skipIndex = options?.skipIndex ?? false
+
+    switch (tier) {
+      case 'hot':
+        await this.doStorage.put(this.doKey(key), data)
+        this.warmStats.writes++
+        this.warmStats.bytesWritten += data.length
+        if (this.swrCacheLayer) await this.swrCacheLayer.put(key, data)
+        else if (this.cacheLayer) await this.cacheLayer.put(key, data, { lastAccessed: Date.now(), accessCount: 1 })
+        if (!skipIndex) this.updateIndex(key, 'hot', data.length, writeThrough ? false : true)
+        break
+      case 'warm':
+        await this.doStorage.put(this.doKey(key), data)
+        this.warmStats.writes++
+        this.warmStats.bytesWritten += data.length
+        if (!skipIndex) this.updateIndex(key, 'warm', data.length, writeThrough ? false : true)
+        break
+      case 'cold':
+        await this.r2Layer.put(key, data, { customMetadata: options?.metadata })
+        if (!skipIndex) this.updateIndex(key, 'cold', data.length, false)
+        break
+    }
+
+    if (writeThrough && tier !== 'cold') {
+      try {
+        await this.r2Layer.put(key, data, { customMetadata: { ...options?.metadata, writeThroughAt: Date.now().toString(), sourceTier: tier } })
+        const entry = this.storageIndex.get(key)
+        if (entry) entry.dirty = false
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e))
+        this.tierHealth.cold = 'degraded'
+        this.notifyError({ context: 'write_through_failure', error, tier: 'cold', key, timestamp: Date.now() })
+      }
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const errors: Error[] = []
+    if (this.swrCacheLayer) { try { await this.swrCacheLayer.invalidate(key) } catch (e) { errors.push(e instanceof Error ? e : new Error(String(e))) } }
+    else if (this.cacheLayer) { try { await this.cacheLayer.delete(key) } catch (e) { errors.push(e instanceof Error ? e : new Error(String(e))) } }
+    try { await this.doStorage.delete(this.doKey(key)); this.warmStats.deletes++ } catch (e) { errors.push(e instanceof Error ? e : new Error(String(e))) }
+    try { await this.r2Layer.delete(key) } catch (e) { errors.push(e instanceof Error ? e : new Error(String(e))) }
+    // Update memory tracking before deleting from index
+    if (this.storageIndex.has(key)) {
+      this.indexMemoryBytes -= TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD + key.length * 2
+      if (this.indexMemoryBytes < 0) this.indexMemoryBytes = 0
+    }
+    this.storageIndex.delete(key)
+    if (errors.length === 3) throw new Error(`Failed to delete from all tiers: ${errors.map(e => e.message).join('; ')}`)
+  }
+
+  async promoteToWarm(key: string, data?: Uint8Array): Promise<TierMigrationEvent> {
+    const timestamp = Date.now()
+    const pageData = data ?? await this.r2Layer.get(key)
+    if (!pageData) {
+      const event: TierMigrationEvent = { key, fromTier: 'cold', toTier: 'warm', success: false, timestamp, error: 'Data not found in cold tier', reason: 'access_pattern' }
+      this.promotionStats.failed++
+      this.notifyMigration(event)
+      return event
+    }
+    try {
+      await this.doStorage.put(this.doKey(key), pageData)
+      this.warmStats.writes++
+      this.warmStats.bytesWritten += pageData.length
+      this.promotionStats.coldToWarm++
+      this.updateIndex(key, 'warm', pageData.length)
+      const event: TierMigrationEvent = { key, fromTier: 'cold', toTier: 'warm', success: true, timestamp, reason: 'access_pattern' }
+      this.notifyMigration(event)
+      return event
+    } catch (e) {
+      this.promotionStats.failed++
+      const event: TierMigrationEvent = { key, fromTier: 'cold', toTier: 'warm', success: false, timestamp, error: e instanceof Error ? e.message : String(e), reason: 'access_pattern' }
+      this.notifyMigration(event)
+      return event
+    }
+  }
+
+  async promoteToHot(key: string, data?: Uint8Array): Promise<TierMigrationEvent> {
+    const timestamp = Date.now()
+    const pageData = data ?? await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+    if (!pageData) {
+      const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'hot', success: false, timestamp, error: 'Data not found in warm tier', reason: 'access_pattern' }
+      this.promotionStats.failed++
+      this.notifyMigration(event)
+      return event
+    }
+    try {
+      if (this.swrCacheLayer) await this.swrCacheLayer.put(key, pageData)
+      else if (this.cacheLayer) {
+        const entry = this.storageIndex.get(key)
+        await this.cacheLayer.put(key, pageData, { lastAccessed: timestamp, accessCount: entry?.accessCount ?? 1 })
+      }
+      this.promotionStats.warmToHot++
+      this.updateIndex(key, 'hot', pageData.length)
+      const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'hot', success: true, timestamp, reason: 'access_pattern' }
+      this.notifyMigration(event)
+      return event
+    } catch (e) {
+      this.promotionStats.failed++
+      const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'hot', success: false, timestamp, error: e instanceof Error ? e.message : String(e), reason: 'access_pattern' }
+      this.notifyMigration(event)
+      return event
+    }
+  }
+
+  async demoteFromHot(key: string, reason: TierMigrationEvent['reason'] = 'ttl_expired'): Promise<TierMigrationEvent> {
+    const timestamp = Date.now()
+    try {
+      if (this.swrCacheLayer) await this.swrCacheLayer.invalidate(key)
+      else if (this.cacheLayer) await this.cacheLayer.delete(key)
+      this.demotionStats.hotToWarm++
+      this.updateIndex(key, 'warm', this.storageIndex.get(key)?.size ?? 0)
+      const event: TierMigrationEvent = { key, fromTier: 'hot', toTier: 'warm', success: true, timestamp, reason }
+      this.notifyMigration(event)
+      return event
+    } catch (e) {
+      this.demotionStats.failed++
+      const event: TierMigrationEvent = { key, fromTier: 'hot', toTier: 'warm', success: false, timestamp, error: e instanceof Error ? e.message : String(e), reason }
+      this.notifyMigration(event)
+      return event
+    }
+  }
+
+  async demoteFromWarm(key: string, reason: TierMigrationEvent['reason'] = 'ttl_expired'): Promise<TierMigrationEvent> {
+    const timestamp = Date.now()
+    try {
+      const data = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+      if (!data) {
+        const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'cold', success: false, timestamp, error: 'Data not found in warm tier', reason }
+        this.demotionStats.failed++
+        this.notifyMigration(event)
+        return event
+      }
+      await this.r2Layer.put(key, data, { customMetadata: { demotedAt: timestamp.toString(), reason } })
+      await this.doStorage.delete(this.doKey(key))
+      this.warmStats.deletes++
+      this.demotionStats.warmToCold++
+      this.updateIndex(key, 'cold', data.length)
+      const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'cold', success: true, timestamp, reason }
+      this.notifyMigration(event)
+      return event
+    } catch (e) {
+      this.demotionStats.failed++
+      const event: TierMigrationEvent = { key, fromTier: 'warm', toTier: 'cold', success: false, timestamp, error: e instanceof Error ? e.message : String(e), reason }
+      this.notifyMigration(event)
+      return event
+    }
+  }
+
+  async runDemotionCycle(maxDemotions = 10): Promise<TierMigrationEvent[]> {
+    if (!this.config.autoDemote) return []
+    const events: TierMigrationEvent[] = []
+    const now = Date.now()
+    const hotCandidates: StorageIndexEntry[] = []
+    for (const entry of this.storageIndex.values()) {
+      // Skip pinned entries
+      if (this.pinnedEntries.has(entry.key)) continue
+      if (entry.tier === 'hot' && now - entry.lastAccess >= this.config.hotTtlMs) hotCandidates.push(entry)
+    }
+    hotCandidates.sort((a, b) => a.lastAccess - b.lastAccess)
+    for (const entry of hotCandidates.slice(0, maxDemotions)) events.push(await this.demoteFromHot(entry.key))
+    const warmCandidates: StorageIndexEntry[] = []
+    for (const entry of this.storageIndex.values()) {
+      // Skip pinned entries
+      if (this.pinnedEntries.has(entry.key)) continue
+      if (entry.tier === 'warm' && now - entry.lastAccess >= this.config.warmTtlMs) warmCandidates.push(entry)
+    }
+    warmCandidates.sort((a, b) => a.lastAccess - b.lastAccess)
+    const remainingSlots = maxDemotions - events.length
+    for (const entry of warmCandidates.slice(0, remainingSlots)) events.push(await this.demoteFromWarm(entry.key))
+    return events
+  }
+
+  async evictLRUFromHot(count: number): Promise<TierMigrationEvent[]> {
+    const hotPages: StorageIndexEntry[] = []
+    for (const entry of this.storageIndex.values()) { if (entry.tier === 'hot') hotPages.push(entry) }
+    hotPages.sort((a, b) => a.lastAccess - b.lastAccess)
+    const events: TierMigrationEvent[] = []
+    for (const entry of hotPages.slice(0, count)) events.push(await this.demoteFromHot(entry.key, 'lru_eviction'))
+    return events
+  }
+
+  async syncDirtyToCold(): Promise<number> {
+    let synced = 0
+    for (const entry of this.storageIndex.values()) {
+      if (entry.dirty) {
+        try {
+          const data = await this.doStorage.get(this.doKey(entry.key)) as Uint8Array | undefined
+          if (data) {
+            await this.r2Layer.put(entry.key, data, { customMetadata: { syncedAt: Date.now().toString(), sourceTier: entry.tier } })
+            entry.dirty = false
+            synced++
+          }
+        } catch (e) {
+          const error = e instanceof Error ? e : new Error(String(e))
+          this.notifyError({ context: 'sync_dirty_to_cold', error, key: entry.key, timestamp: Date.now() })
+        }
+      }
+    }
+    return synced
+  }
+
+  getIndexEntry(key: string): StorageIndexEntry | undefined { return this.storageIndex.get(key) }
+  hasInIndex(key: string): boolean { return this.storageIndex.has(key) }
+  getTier(key: string): StorageTier | undefined { return this.storageIndex.get(key)?.tier }
+
+  /**
+   * Get detailed memory usage breakdown for the storage index
+   *
+   * ## Memory Components
+   *
+   * - **entryOverhead**: Fixed overhead per entry (~120 bytes)
+   * - **keyStorage**: Memory for key strings (2 bytes per char in JS)
+   * - **mapOverhead**: Estimated Map internal structures (~10% of entry memory)
+   *
+   * @returns Detailed memory breakdown in bytes
+   */
+  getIndexMemoryBreakdown(): {
+    totalBytes: number
+    entryOverhead: number
+    keyStorage: number
+    mapOverheadEstimate: number
+    bytesPerEntry: number
+    entries: number
+    peakBytes: number
+    utilizationPercent: number | null
+    memoryBudgetBytes: number | null
+  } {
+    let keyStorage = 0
+    for (const key of this.storageIndex.keys()) {
+      keyStorage += key.length * 2 // JS strings are UTF-16
+    }
+
+    const entryOverhead = this.storageIndex.size * TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD
+    // Estimate Map internal overhead as ~10% of entry memory
+    const mapOverheadEstimate = Math.ceil(entryOverhead * MAP_OVERHEAD_ESTIMATE_PERCENT)
+    const totalBytes = entryOverhead + keyStorage + mapOverheadEstimate
+    const bytesPerEntry = this.storageIndex.size > 0
+      ? totalBytes / this.storageIndex.size
+      : 0
+
+    return {
+      totalBytes,
+      entryOverhead,
+      keyStorage,
+      mapOverheadEstimate,
+      bytesPerEntry,
+      entries: this.storageIndex.size,
+      peakBytes: this.performanceMetrics.peakMemoryBytes,
+      utilizationPercent: this.config.maxIndexMemoryBytes
+        ? (this.indexMemoryBytes / this.config.maxIndexMemoryBytes) * 100
+        : null,
+      memoryBudgetBytes: this.config.maxIndexMemoryBytes ?? null,
+    }
+  }
+
+  /**
+   * Estimate memory for a given number of entries with average key length
+   *
+   * Useful for capacity planning:
+   * ```typescript
+   * // How much memory for 10,000 entries with ~30 char keys?
+   * const estimate = orchestrator.estimateIndexMemory(10000, 30)
+   * console.log(`Estimated: ${estimate / 1024 / 1024}MB`)
+   * ```
+   *
+   * @param entryCount - Number of entries to estimate for
+   * @param avgKeyLength - Average key length in characters (default: 20)
+   * @returns Estimated memory usage in bytes
+   */
+  estimateIndexMemory(entryCount: number, avgKeyLength = DEFAULT_AVG_KEY_LENGTH_CHARS): number {
+    const entryOverhead = entryCount * TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD
+    const keyStorage = entryCount * avgKeyLength * 2 // UTF-16
+    const mapOverhead = Math.ceil(entryOverhead * MAP_OVERHEAD_ESTIMATE_PERCENT)
+    return entryOverhead + keyStorage + mapOverhead
+  }
+
+  /**
+   * Get the current memory usage as a percentage of the configured limit
+   *
+   * @returns Percentage (0-100) or null if no limit configured
+   */
+  getIndexMemoryUtilization(): number | null {
+    if (!this.config.maxIndexMemoryBytes) return null
+    return (this.indexMemoryBytes / this.config.maxIndexMemoryBytes) * 100
+  }
+
+  /**
+   * Check if the index is approaching memory limits
+   *
+   * @param threshold - Warning threshold as decimal (default: 0.8 = 80%)
+   * @returns Object with warning status and details
+   */
+  checkIndexMemoryStatus(threshold = 0.8): {
+    isNearLimit: boolean
+    currentBytes: number
+    limitBytes: number | null
+    utilizationPercent: number | null
+    warningThreshold: number
+  } {
+    const utilization = this.getIndexMemoryUtilization()
+    return {
+      isNearLimit: utilization !== null && utilization >= threshold * 100,
+      currentBytes: this.indexMemoryBytes,
+      limitBytes: this.config.maxIndexMemoryBytes ?? null,
+      utilizationPercent: utilization,
+      warningThreshold: threshold * 100,
+    }
+  }
+
+  /**
+   * Get comprehensive statistics including performance metrics
+   *
+   * ## Performance Metrics Included
+   *
+   * - **lookupCount**: Total number of index lookups
+   * - **updateCount**: Total number of index updates
+   * - **evictionCount**: Total entries evicted
+   * - **avgLookupTimeNs**: Average lookup time in nanoseconds
+   * - **avgUpdateTimeNs**: Average update time in nanoseconds
+   * - **peakEntries**: Maximum index size observed
+   * - **peakMemoryBytes**: Maximum memory usage observed
+   * - **cacheHitCount/cacheMissCount**: Hot path cache effectiveness
+   *
+   * @returns Complete orchestrator statistics
+   */
+  getStats(): OrchestratorStats {
+    const indexStats: OrchestratorStats['index'] = {
+      totalEntries: this.storageIndex.size,
+      byTier: { hot: 0, warm: 0, cold: 0 } as Record<StorageTier, number>,
+      totalSize: 0,
+      dirtyEntries: 0,
+      memoryBytes: this.indexMemoryBytes,
+      performance: {
+        lookupCount: this.performanceMetrics.lookupCount,
+        updateCount: this.performanceMetrics.updateCount,
+        evictionCount: this.performanceMetrics.evictionCount,
+        totalLookupTimeNs: this.performanceMetrics.totalLookupTimeNs,
+        totalUpdateTimeNs: this.performanceMetrics.totalUpdateTimeNs,
+        totalEvictionTimeNs: this.performanceMetrics.totalEvictionTimeNs,
+        totalMaintenanceTimeNs: this.performanceMetrics.totalMaintenanceTimeNs,
+        avgLookupTimeNs: this.performanceMetrics.lookupCount > 0
+          ? this.performanceMetrics.totalLookupTimeNs / this.performanceMetrics.lookupCount
+          : 0,
+        avgUpdateTimeNs: this.performanceMetrics.updateCount > 0
+          ? this.performanceMetrics.totalUpdateTimeNs / this.performanceMetrics.updateCount
+          : 0,
+        peakEntries: this.performanceMetrics.peakEntries,
+        peakMemoryBytes: this.performanceMetrics.peakMemoryBytes,
+        evictionBatches: this.performanceMetrics.evictionBatches,
+        entriesPerEvictionBatch: this.performanceMetrics.evictionBatches > 0
+          ? this.performanceMetrics.evictionCount / this.performanceMetrics.evictionBatches
+          : 0,
+        cacheHitCount: this.performanceMetrics.cacheHitCount,
+        cacheMissCount: this.performanceMetrics.cacheMissCount,
+      },
+    }
+    for (const entry of this.storageIndex.values()) {
+      indexStats.byTier[entry.tier]++
+      indexStats.totalSize += entry.size
+      if (entry.dirty) indexStats.dirtyEntries++
+    }
+    return {
+      index: indexStats,
+      hot: this.swrCacheLayer?.getStats() ?? this.cacheLayer?.getStats() ?? { hits: 0, misses: 0, writes: 0, deletes: 0, bytesRead: 0, bytesWritten: 0, errors: 0, hitRatio: 0 },
+      warm: { ...this.warmStats },
+      cold: this.r2Layer.getStats(),
+      promotions: { ...this.promotionStats },
+      demotions: { ...this.demotionStats },
+      health: { ...this.tierHealth },
+      errors: { ...this.errorCounts },
+    }
+  }
+
+  /**
+   * Reset all statistics counters
+   *
+   * Resets:
+   * - Warm tier stats (reads, writes, deletes, bytes)
+   * - Promotion/demotion counters
+   * - Performance metrics (lookup/update/eviction counts and timing)
+   *
+   * Does NOT reset:
+   * - Peak values (peakEntries, peakMemoryBytes)
+   * - Current index state
+   */
+  resetStats(): void {
+    this.warmStats = { reads: 0, writes: 0, deletes: 0, bytesRead: 0, bytesWritten: 0 }
+    this.promotionStats = { coldToWarm: 0, warmToHot: 0, failed: 0 }
+    this.demotionStats = { hotToWarm: 0, warmToCold: 0, failed: 0 }
+  }
+
+  /**
+   * Reset only performance metrics while preserving operational stats
+   *
+   * Useful for:
+   * - Starting a new measurement window
+   * - Benchmarking specific operations
+   * - A/B testing configuration changes
+   *
+   * @param preservePeaks - If true, keeps peakEntries and peakMemoryBytes (default: false)
+   */
+  resetPerformanceMetrics(preservePeaks = false): void {
+    const peakEntries = preservePeaks ? this.performanceMetrics.peakEntries : 0
+    const peakMemoryBytes = preservePeaks ? this.performanceMetrics.peakMemoryBytes : 0
+
+    this.performanceMetrics = {
+      lookupCount: 0,
+      updateCount: 0,
+      evictionCount: 0,
+      totalLookupTimeNs: 0,
+      totalUpdateTimeNs: 0,
+      totalEvictionTimeNs: 0,
+      totalMaintenanceTimeNs: 0,
+      peakEntries,
+      peakMemoryBytes,
+      evictionBatches: 0,
+      cacheHitCount: 0,
+      cacheMissCount: 0,
+    }
+
+    // Clear lookup cache
+    this.lastLookupKey = null
+    this.lastLookupEntry = null
+  }
+
+  /**
+   * Get a human-readable performance summary
+   *
+   * @returns Formatted string with key performance metrics
+   */
+  getPerformanceSummary(): string {
+    const m = this.performanceMetrics
+    const cacheHitRate = (m.cacheHitCount + m.cacheMissCount) > 0
+      ? ((m.cacheHitCount / (m.cacheHitCount + m.cacheMissCount)) * 100).toFixed(1)
+      : '0.0'
+    const avgLookup = m.lookupCount > 0
+      ? (m.totalLookupTimeNs / m.lookupCount / 1000).toFixed(2)
+      : '0.00'
+    const avgUpdate = m.updateCount > 0
+      ? (m.totalUpdateTimeNs / m.updateCount / 1000).toFixed(2)
+      : '0.00'
+    const avgEvictionBatch = m.evictionBatches > 0
+      ? (m.totalEvictionTimeNs / m.evictionBatches / 1000).toFixed(2)
+      : '0.00'
+
+    return [
+      `Index Performance Summary:`,
+      `  Entries: ${this.storageIndex.size} current, ${m.peakEntries} peak`,
+      `  Memory: ${(this.indexMemoryBytes / 1024).toFixed(1)}KB current, ${(m.peakMemoryBytes / 1024).toFixed(1)}KB peak`,
+      `  Lookups: ${m.lookupCount} total, ${avgLookup}μs avg`,
+      `  Updates: ${m.updateCount} total, ${avgUpdate}μs avg`,
+      `  Evictions: ${m.evictionCount} entries in ${m.evictionBatches} batches, ${avgEvictionBatch}μs/batch`,
+      `  Cache: ${cacheHitRate}% hit rate (${m.cacheHitCount} hits, ${m.cacheMissCount} misses)`,
+      `  Maintenance: ${(m.totalMaintenanceTimeNs / 1e6).toFixed(1)}ms total`,
+    ].join('\n')
+  }
+
+  /**
+   * Clear the index and all associated tracking
+   */
+  clearIndex(): void {
+    this.storageIndex.clear()
+    this.indexMemoryBytes = 0
+    this.memoryWarningEmitted = false
+    this.lastLookupKey = null
+    this.lastLookupEntry = null
+  }
+
+  resetHealth(tier?: StorageTier): void {
+    if (tier) this.tierHealth[tier] = 'healthy'
+    else this.tierHealth = { hot: 'healthy', warm: 'healthy', cold: 'healthy' }
+  }
+
+  getConfig(): InternalConfig { return { ...this.config } }
+
+  // DO Lifecycle Hooks
+  async onHibernate(): Promise<HibernateResult> {
+    const timestamp = Date.now()
+    let persistedCount = 0
+    const hotKeys: string[] = []
+    for (const entry of this.storageIndex.values()) { if (entry.tier === 'hot') hotKeys.push(entry.key) }
+    for (const key of hotKeys) {
+      const entry = this.storageIndex.get(key)
+      if (entry) { entry.tier = 'warm'; persistedCount++ }
+    }
+    const syncedToCold = await this.syncDirtyToCold()
+    const indexSnapshot = new Map(this.storageIndex)
+    return { success: true, persistedCount, syncedToCold, hotKeys, indexSnapshot, timestamp }
+  }
+
+  async onWake(hibernateState: HibernateState | null, options?: WakeOptions): Promise<WakeResult> {
+    let restoredCount = 0, prefetchedCount = 0, indexRepairs = 0
+    const indexValidated = options?.validateIndex ?? false
+    if (hibernateState?.hotKeys) {
+      for (const key of hibernateState.hotKeys) {
+        try {
+          const data = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+          if (data) {
+            if (this.swrCacheLayer) await this.swrCacheLayer.put(key, data)
+            else if (this.cacheLayer) await this.cacheLayer.put(key, data, { lastAccessed: Date.now(), accessCount: 1 })
+            this.updateIndex(key, 'hot', data.length)
+            restoredCount++
+          }
+        } catch (e) {
+          const error = e instanceof Error ? e : new Error(String(e))
+          this.notifyError({ context: 'wake_restore', error, key, timestamp: Date.now() })
+        }
+      }
+    }
+    if (options?.prefetchThreshold && hibernateState?.indexSnapshot) {
+      for (const [key, entry] of hibernateState.indexSnapshot) {
+        if (entry.accessCount >= options.prefetchThreshold && entry.tier !== 'hot') {
+          try { const event = await this.promoteToHot(key); if (event.success) prefetchedCount++ } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e))
+            this.notifyError({ context: 'wake_prefetch', error, key, timestamp: Date.now() })
+          }
+        }
+      }
+    }
+    if (indexValidated) {
+      for (const [key, entry] of this.storageIndex) {
+        let found = false, actualTier: StorageTier | undefined
+        const warmData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+        if (warmData) { found = true; actualTier = 'warm' }
+        if (!found) {
+          const coldData = await this.r2Layer.get(key)
+          if (coldData) { found = true; actualTier = 'cold' }
+        }
+        if (!found) { this.storageIndex.delete(key); indexRepairs++ }
+        else if (actualTier && actualTier !== entry.tier && entry.tier !== 'hot') { entry.tier = actualTier; indexRepairs++ }
+      }
+    }
+    return { restoredCount, prefetchedCount, indexValidated, indexRepairs }
+  }
+
+  // Background Task Scheduling
+  async scheduleAlarm(alarmConfig: AlarmConfig): Promise<void> {
+    const storage = this.doStorage as DurableObjectStorage & { getAlarm?: () => Promise<number | null>; setAlarm?: (time: number) => Promise<void> }
+    if (alarmConfig.skipIfExists && storage.getAlarm) {
+      const existingAlarm = await storage.getAlarm()
+      if (existingAlarm !== null && existingAlarm !== undefined) return
+    }
+    const scheduledTime = Date.now() + alarmConfig.delayMs
+    if (storage.setAlarm) await storage.setAlarm(scheduledTime)
+  }
+
+  async handleAlarm(alarmConfig: AlarmConfig & { rescheduleMs?: number }): Promise<AlarmResult> {
+    const result: AlarmResult = {}
+    switch (alarmConfig.type) {
+      case 'demotion': { const events = await this.runDemotionCycle(); result.demotionCount = events.length; break }
+      case 'sync': { result.syncedCount = await this.syncDirtyToCold(); break }
+      default: assertNever(alarmConfig.type, 'Unknown alarm type')
+    }
+    if (alarmConfig.rescheduleMs) {
+      await this.scheduleAlarm({ type: alarmConfig.type, delayMs: alarmConfig.rescheduleMs })
+      result.nextAlarmMs = alarmConfig.rescheduleMs
+    }
+    return result
+  }
+
+  // Circuit Breaker Pattern
+  getCircuitBreakerState(tier: StorageTier): CircuitBreakerStateInfo {
+    const state = { ...this.circuitBreakers[tier] }
+    if (state.state === 'open' && state.openedAt) {
+      const resetTimeout = this.config.circuitBreaker?.resetTimeoutMs ?? DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS
+      if (Date.now() - state.openedAt >= resetTimeout) { this.circuitBreakers[tier].state = 'half-open'; state.state = 'half-open' }
+    }
+    return state
+  }
+
+  setCircuitBreakerState(tier: StorageTier, state: CircuitBreakerState): void {
+    this.circuitBreakers[tier].state = state
+    if (state === 'open') this.circuitBreakers[tier].openedAt = Date.now()
+  }
+
+  // Metrics Aggregation
+  getAggregatedMetrics(): AggregatedMetrics {
+    const hotStats = this.swrCacheLayer?.getStats() ?? this.cacheLayer?.getStats() ?? { hits: 0, misses: 0, writes: 0, bytesRead: 0, bytesWritten: 0, hitRatio: 0 }
+    const coldStats = this.r2Layer.getStats()
+    let warmBytesStored = 0, coldBytesStored = 0
+    for (const entry of this.storageIndex.values()) {
+      if (entry.tier === 'warm') warmBytesStored += entry.size
+      if (entry.tier === 'cold') coldBytesStored += entry.size
+    }
+    const metrics: AggregatedMetrics = {
+      timestamp: Date.now(),
+      period: 'current',
+      tiers: {
+        hot: { reads: 'hits' in hotStats ? hotStats.hits + hotStats.misses : 0, writes: hotStats.writes, hitRatio: 'hitRatio' in hotStats ? hotStats.hitRatio : 0, bytesRead: hotStats.bytesRead, bytesWritten: hotStats.bytesWritten },
+        warm: { reads: this.warmStats.reads, writes: this.warmStats.writes, bytesStored: warmBytesStored, bytesRead: this.warmStats.bytesRead, bytesWritten: this.warmStats.bytesWritten },
+        cold: { reads: coldStats.reads, writes: coldStats.writes, bytesStored: coldBytesStored, bytesRead: coldStats.bytesRead, bytesWritten: coldStats.bytesWritten },
+      },
+      migrations: { promotions: this.promotionStats.coldToWarm + this.promotionStats.warmToHot, demotions: this.demotionStats.hotToWarm + this.demotionStats.warmToCold, failures: this.promotionStats.failed + this.demotionStats.failed },
+      circuitBreakers: { hot: this.getCircuitBreakerState('hot'), warm: this.getCircuitBreakerState('warm'), cold: this.getCircuitBreakerState('cold') },
+      errors: { totalErrors: this.errorCounts.hot + this.errorCounts.warm + this.errorCounts.cold, byTier: { ...this.errorCounts } },
+    }
+    if (this.config.metrics?.trackLatency && this.latencyMeasurements.length > 0) {
+      const sorted = [...this.latencyMeasurements].sort((a, b) => a - b)
+      metrics.latency = { p50: sorted[Math.floor(sorted.length * 0.5)] ?? 0, p95: sorted[Math.floor(sorted.length * 0.95)] ?? 0, p99: sorted[Math.floor(sorted.length * 0.99)] ?? 0 }
+    }
+    if (this.config.metrics?.trackCost && this.config.metrics.costConfig) {
+      const cc = this.config.metrics.costConfig
+      const r2Cost = (coldBytesStored / (1024 * 1024 * 1024)) * cc.r2StoragePerGBMonth + coldStats.writes * cc.r2ClassAOperations + coldStats.reads * cc.r2ClassBOperations
+      const doCost = (warmBytesStored / (1024 * 1024 * 1024)) * cc.doStoragePerGBMonth
+      metrics.estimatedCost = { r2: r2Cost, do: doCost, cache: 0, total: r2Cost + doCost }
+    }
+    return metrics
+  }
+
+  exportMetrics(format: 'prometheus' | 'json'): string | AggregatedMetrics {
+    const metrics = this.getAggregatedMetrics()
+    if (format === 'json') return metrics
+    const lines: string[] = [
+      '# HELP tiered_storage_writes_total Total number of writes', '# TYPE tiered_storage_writes_total counter',
+      `tiered_storage_writes_total{tier="hot"} ${metrics.tiers.hot.writes}`, `tiered_storage_writes_total{tier="warm"} ${metrics.tiers.warm.writes}`, `tiered_storage_writes_total{tier="cold"} ${metrics.tiers.cold.writes}`, '',
+      '# HELP tiered_storage_bytes_written Total bytes written', '# TYPE tiered_storage_bytes_written counter',
+      `tiered_storage_bytes_written{tier="hot"} ${metrics.tiers.hot.bytesWritten}`, `tiered_storage_bytes_written{tier="warm"} ${metrics.tiers.warm.bytesWritten}`, `tiered_storage_bytes_written{tier="cold"} ${metrics.tiers.cold.bytesWritten}`, '',
+      '# HELP tiered_storage_reads_total Total number of reads', '# TYPE tiered_storage_reads_total counter',
+      `tiered_storage_reads_total{tier="hot"} ${metrics.tiers.hot.reads}`, `tiered_storage_reads_total{tier="warm"} ${metrics.tiers.warm.reads}`, `tiered_storage_reads_total{tier="cold"} ${metrics.tiers.cold.reads}`, '',
+      '# HELP tiered_storage_errors_total Total number of errors', '# TYPE tiered_storage_errors_total counter',
+      `tiered_storage_errors_total{tier="hot"} ${metrics.errors.byTier.hot}`, `tiered_storage_errors_total{tier="warm"} ${metrics.errors.byTier.warm}`, `tiered_storage_errors_total{tier="cold"} ${metrics.errors.byTier.cold}`,
+    ]
+    return lines.join('\n')
+  }
+
+  // Component Integration
+  createVFSInterface(_options?: { pageSize?: number; promotionThreshold?: number }): VFSInterface {
+    return {
+      readPage: async (pageId: string) => { const result = await this.read(pageId); return result.data },
+      writePage: async (pageId: string, data: Uint8Array) => { await this.write(pageId, data) },
+      deletePage: async (pageId: string) => { await this.delete(pageId) },
+    }
+  }
+
+  configureAutoPromoter(config: AutoPromoterConfig): void {
+    this.autoPromoterConfig = { ...config }
+    this.config.coldToWarmThreshold = config.coldToWarm.accessThreshold
+    this.config.warmToHotThreshold = config.warmToHot.accessThreshold
+    if (config.warmToHot.timeWindowMs) this.config.promotionWindowMs = config.warmToHot.timeWindowMs
+  }
+
+  getAutoPromoterConfig(): AutoPromoterConfig { return { ...this.autoPromoterConfig } }
+
+  configureAutoDemoter(config: AutoDemoterConfig): void {
+    this.autoDemoterConfig = { ...config }
+    this.config.hotTtlMs = config.hotToWarm.ttlMs
+    this.config.warmTtlMs = config.warmToCold.ttlMs
+  }
+
+  getAutoDemoterConfig(): AutoDemoterConfig { return { ...this.autoDemoterConfig } }
+
+  setDemotionStrategy(tier: StorageTier, strategy: DemotionStrategy): void { this.demotionStrategies[tier] = strategy }
+
+  async runDemotionWithStrategy(tier: StorageTier, count: number): Promise<TierMigrationEvent[]> {
+    const strategy = this.demotionStrategies[tier]
+    if (!strategy) { if (tier === 'hot') return this.evictLRUFromHot(count); return [] }
+    const entries: StorageIndexEntry[] = []
+    for (const entry of this.storageIndex.values()) { if (entry.tier === tier) entries.push(entry) }
+    const keysToDemote = strategy(entries, count)
+    const events: TierMigrationEvent[] = []
+    for (const key of keysToDemote) {
+      const event = tier === 'hot' ? await this.demoteFromHot(key, 'lru_eviction') : await this.demoteFromWarm(key, 'lru_eviction')
+      events.push(event)
+    }
+    return events
+  }
+
+  // Error Recovery
+  async runConsistencyCheck(): Promise<{ inconsistencies: number; repairs: { key: string; issue: string; action: string }[] }> {
+    const repairs: { key: string; issue: string; action: string }[] = []
+    for (const [key, entry] of this.storageIndex) {
+      let found = false, actualTier: StorageTier | undefined
+      const warmData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+      if (warmData) { found = true; actualTier = 'warm' }
+      if (!found) { const coldData = await this.r2Layer.get(key); if (coldData) { found = true; actualTier = 'cold' } }
+      if (!found) { repairs.push({ key, issue: `Data not found in ${entry.tier} tier`, action: 'removed from index' }); this.storageIndex.delete(key) }
+      else if (actualTier && actualTier !== entry.tier && entry.tier !== 'hot') { repairs.push({ key, issue: `Index says ${entry.tier} but found in ${actualTier}`, action: `updated tier to ${actualTier}` }); entry.tier = actualTier }
+    }
+    return { inconsistencies: repairs.length, repairs }
+  }
+
+  // Advanced Tier Management
+  setIndexEntryTimestamp(key: string, field: 'created' | 'lastAccess' | 'modified', timestamp: number): void {
+    const entry = this.storageIndex.get(key)
+    if (entry) entry[field] = timestamp
+  }
+
+  getAccessPatternMetrics(key: string): { isBurst: boolean; accessRate: number; recentAccesses: number } {
+    const entry = this.storageIndex.get(key)
+    if (!entry) return { isBurst: false, accessRate: 0, recentAccesses: 0 }
+    const ageMs = Math.max(1, Date.now() - entry.created)
+    const accessRate = (entry.accessCount / ageMs) * 1000
+    return { isBurst: accessRate > 5, accessRate, recentAccesses: entry.accessCount }
+  }
+
+  async evictByMemoryPressure(bytesToFree: number): Promise<TierMigrationEvent[]> {
+    const events: TierMigrationEvent[] = []
+    let freedBytes = 0
+    const hotEntries = Array.from(this.storageIndex.values()).filter(e => e.tier === 'hot').sort((a, b) => b.size - a.size)
+    for (const entry of hotEntries) {
+      if (freedBytes >= bytesToFree) break
+      const event = await this.demoteFromHot(entry.key, 'lru_eviction')
+      events.push(event)
+      if (event.success) freedBytes += entry.size
+    }
+    return events
+  }
+
+  setEntryPriority(key: string, priority: 'low' | 'normal' | 'high'): void { this.entryPriorities.set(key, priority) }
+  getEntryPriority(key: string): 'low' | 'normal' | 'high' { return this.entryPriorities.get(key) ?? 'normal' }
+
+  async batchPromoteToWarm(keys: string[]): Promise<TierMigrationEvent[]> { return Promise.all(keys.map(key => this.promoteToWarm(key))) }
+  async batchDemoteFromWarm(keys: string[]): Promise<TierMigrationEvent[]> { return Promise.all(keys.map(key => this.demoteFromWarm(key))) }
+
+  async healthCheck(): Promise<{ overall: 'healthy' | 'degraded' | 'unhealthy'; tiers: Record<StorageTier, { status: string; latency: number; error?: string }>; latency: Record<StorageTier, number> }> {
+    const checkTier = async (tier: StorageTier): Promise<{ status: string; latency: number; error?: string }> => {
+      const start = Date.now()
+      try {
+        if (tier === 'hot') return { status: this.cacheLayer || this.swrCacheLayer ? 'healthy' : 'unavailable', latency: Date.now() - start }
+        if (tier === 'warm') { await this.doStorage.get('__health_check__'); return { status: 'healthy', latency: Date.now() - start } }
+        await this.r2Layer.get('__health_check__'); return { status: 'healthy', latency: Date.now() - start }
+      } catch (e) { return { status: 'unhealthy', latency: Date.now() - start, error: e instanceof Error ? e.message : String(e) } }
+    }
+    const [hot, warm, cold] = await Promise.all([checkTier('hot'), checkTier('warm'), checkTier('cold')])
+    const statuses = [hot.status, warm.status, cold.status]
+    let overall: 'healthy' | 'degraded' | 'unhealthy' = 'healthy'
+    if (statuses.some(s => s === 'unhealthy')) overall = 'degraded'
+    if (statuses.every(s => s === 'unhealthy')) overall = 'unhealthy'
+    return { overall, tiers: { hot, warm, cold }, latency: { hot: hot.latency, warm: warm.latency, cold: cold.latency } }
+  }
+
+  getMemoryUsage(): { hot: number; warm: number; cold: number; total: number; limit: number; utilizationPercent: number } {
+    let hot = 0, warm = 0, cold = 0
+    for (const entry of this.storageIndex.values()) {
+      if (entry.tier === 'hot') hot += entry.size
+      else if (entry.tier === 'warm') warm += entry.size
+      else cold += entry.size
+    }
+    const total = hot + warm + cold
+    const limit = (this.memoryLimits.hot ?? Infinity) + (this.memoryLimits.warm ?? Infinity)
+    return { hot, warm, cold, total, limit, utilizationPercent: limit === Infinity ? 0 : (total / limit) * 100 }
+  }
+
+  setMemoryLimit(limits: Partial<Record<StorageTier, number>>): void { this.memoryLimits = { ...this.memoryLimits, ...limits } }
+  getMemoryLimits(): Partial<Record<StorageTier, number>> { return { ...this.memoryLimits } }
+
+  async prefetch(keys: string[], options?: { targetTier?: StorageTier; maxConcurrency?: number }): Promise<{ prefetchedCount: number; failedKeys: string[] }> {
+    const targetTier = options?.targetTier ?? 'warm'
+    const maxConcurrency = options?.maxConcurrency ?? 5
+    const failedKeys: string[] = []
+    let prefetchedCount = 0
+    for (let i = 0; i < keys.length; i += maxConcurrency) {
+      const batch = keys.slice(i, i + maxConcurrency)
+      const results = await Promise.allSettled(batch.map(async key => {
+        const event = targetTier === 'hot' ? await this.promoteToHot(key) : await this.promoteToWarm(key)
+        if (!event.success) throw new Error(event.error)
+        return key
+      }))
+      for (let j = 0; j < results.length; j++) {
+        const result = results[j]
+        if (result?.status === 'fulfilled') prefetchedCount++
+        else if (result?.status === 'rejected' && batch[j]) failedKeys.push(batch[j]!)
+      }
+    }
+    return { prefetchedCount, failedKeys }
+  }
+
+  subscribeToEvents(callback: TierMigrationCallback, options?: { filter?: { type?: 'promotion' | 'demotion' } }): () => void {
+    const subscriber = { callback, filter: options?.filter }
+    this.eventSubscribers.push(subscriber)
+    return () => { const idx = this.eventSubscribers.indexOf(subscriber); if (idx !== -1) this.eventSubscribers.splice(idx, 1) }
+  }
+
+  async createSnapshot(): Promise<{ version: number; timestamp: number; index: StorageIndexEntry[]; stats: OrchestratorStats }> {
+    return { version: 1, timestamp: Date.now(), index: Array.from(this.storageIndex.values()), stats: this.getStats() }
+  }
+
+  async restoreFromSnapshot(snapshot: { version: number; timestamp: number; index: StorageIndexEntry[]; stats: Record<string, unknown> }): Promise<void> {
+    this.storageIndex.clear()
+    this.indexMemoryBytes = 0
+    for (const entry of snapshot.index) {
+      this.storageIndex.set(entry.key, { ...entry })
+      this.indexMemoryBytes += TieredStorageOrchestrator.ENTRY_MEMORY_OVERHEAD + entry.key.length * 2
+    }
+  }
+
+  async warmup(options: { strategy: 'all' | 'most-accessed' | 'recent'; targetTier: StorageTier; maxBytes?: number; limit?: number }): Promise<{ warmedUp: number; bytesTransferred: number; keys: string[] }> {
+    let candidates = Array.from(this.storageIndex.values()).filter(e => e.tier === 'cold')
+    if (options.strategy === 'most-accessed') candidates.sort((a, b) => b.accessCount - a.accessCount)
+    else if (options.strategy === 'recent') candidates.sort((a, b) => b.lastAccess - a.lastAccess)
+    if (options.limit) candidates = candidates.slice(0, options.limit)
+    let bytesTransferred = 0
+    const warmedKeys: string[] = []
+    for (const entry of candidates) {
+      if (options.maxBytes && bytesTransferred + entry.size > options.maxBytes) break
+      const event = options.targetTier === 'hot' ? await this.promoteToHot(entry.key) : await this.promoteToWarm(entry.key)
+      if (event.success) { bytesTransferred += entry.size; warmedKeys.push(entry.key) }
+    }
+    return { warmedUp: warmedKeys.length, bytesTransferred, keys: warmedKeys }
+  }
+
+  async garbageCollect(options?: { compactCold?: boolean }): Promise<{ removedEntries: number; compactionStats?: { bytesReclaimed: number } }> {
+    let removedEntries = 0
+    const keysToRemove: string[] = []
+    for (const [key, entry] of this.storageIndex) {
+      if (entry.tier === 'hot') continue
+      let exists = false
+      if (entry.tier === 'warm') { const data = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined; exists = !!data }
+      else { const data = await this.r2Layer.get(key); exists = !!data }
+      if (!exists) keysToRemove.push(key)
+    }
+    for (const key of keysToRemove) { this.storageIndex.delete(key); removedEntries++ }
+    return options?.compactCold ? { removedEntries, compactionStats: { bytesReclaimed: 0 } } : { removedEntries }
+  }
+
+  pinToTier(key: string, _tier: StorageTier): void { this.pinnedEntries.add(key) }
+  unpinFromTier(key: string): void { this.pinnedEntries.delete(key) }
+  isPinned(key: string): boolean { return this.pinnedEntries.has(key) }
+
+  getCostBreakdown(): { storage: { r2: number; do: number; cache: number }; operations: { r2Writes: number; r2Reads: number; doWrites: number; doReads: number }; total: number; projectedMonthly: number } {
+    const metrics = this.getAggregatedMetrics()
+    const cc = this.config.metrics?.costConfig ?? { r2StoragePerGBMonth: 0.015, r2ClassAOperations: 0.0000045, r2ClassBOperations: 0.00000036, doStoragePerGBMonth: 0.20, cacheOperations: 0 }
+    const r2Storage = (metrics.tiers.cold.bytesStored / (1024 ** 3)) * cc.r2StoragePerGBMonth
+    const doStorage = (metrics.tiers.warm.bytesStored / (1024 ** 3)) * cc.doStoragePerGBMonth
+    const r2Writes = metrics.tiers.cold.writes * cc.r2ClassAOperations
+    const r2Reads = metrics.tiers.cold.reads * cc.r2ClassBOperations
+    const total = r2Storage + doStorage + r2Writes + r2Reads
+    return { storage: { r2: r2Storage, do: doStorage, cache: 0 }, operations: { r2Writes, r2Reads, doWrites: 0, doReads: 0 }, total, projectedMonthly: total }
+  }
+
+  async optimizeTierPlacement(): Promise<{ promotions: Array<{ key: string; currentTier: StorageTier; suggestedTier: StorageTier; reason: string }>; demotions: Array<{ key: string; currentTier: StorageTier; suggestedTier: StorageTier; reason: string }>; estimatedSavings: number }> {
+    const promotions: Array<{ key: string; currentTier: StorageTier; suggestedTier: StorageTier; reason: string }> = []
+    const demotions: Array<{ key: string; currentTier: StorageTier; suggestedTier: StorageTier; reason: string }> = []
+    for (const entry of this.storageIndex.values()) {
+      if (entry.tier === 'cold' && entry.accessCount > 10) promotions.push({ key: entry.key, currentTier: 'cold', suggestedTier: 'warm', reason: 'High access count' })
+      if (entry.tier === 'warm' && entry.accessCount < 5 && Date.now() - entry.lastAccess > 86400000) demotions.push({ key: entry.key, currentTier: 'warm', suggestedTier: 'cold', reason: 'Low access, stale' })
+    }
+    return { promotions, demotions, estimatedSavings: 0 }
+  }
+
+  async ensureDurability(key: string): Promise<{ durable: boolean; tier: StorageTier | null; copied: boolean }> {
+    const coldData = await this.r2Layer.get(key)
+    if (coldData) return { durable: true, tier: 'cold', copied: false }
+    const warmData = await this.doStorage.get(this.doKey(key)) as Uint8Array | undefined
+    if (warmData) { await this.r2Layer.put(key, warmData, { customMetadata: { durabilityBackup: 'true' } }); return { durable: true, tier: 'warm', copied: true } }
+    return { durable: false, tier: null, copied: false }
+  }
+}
+
+export function createTieredStorageOrchestrator(config: TieredOrchestratorConfig): TieredStorageOrchestrator {
+  return new TieredStorageOrchestrator(config)
+}