@dotdo/postgres 0.1.0

package/dist/storage/tiered-orchestrator.js

@@ -0,0 +1,1731 @@
+/**
+ * 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
+ */
+// =============================================================================
+// 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;
+/**
+ * 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 {
+    cacheLayer;
+    swrCacheLayer;
+    doStorage;
+    r2Layer;
+    config;
+    storageIndex = new Map();
+    indexMemoryBytes = 0;
+    maintenanceTimer;
+    memoryWarningEmitted = 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)
+     */
+    static ENTRY_MEMORY_OVERHEAD = ENTRY_MEMORY_OVERHEAD_BYTES;
+    // Performance metrics tracking
+    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
+    lastLookupKey = null;
+    lastLookupEntry = null;
+    warmStats = { reads: 0, writes: 0, deletes: 0, bytesRead: 0, bytesWritten: 0 };
+    promotionStats = { coldToWarm: 0, warmToHot: 0, failed: 0 };
+    demotionStats = { hotToWarm: 0, warmToCold: 0, failed: 0 };
+    tierHealth = { hot: 'healthy', warm: 'healthy', cold: 'healthy' };
+    circuitBreakers = {
+        hot: { state: 'closed', failures: 0 },
+        warm: { state: 'closed', failures: 0 },
+        cold: { state: 'closed', failures: 0 },
+    };
+    latencyMeasurements = [];
+    demotionStrategies = {};
+    autoPromoterConfig = { coldToWarm: { accessThreshold: DEFAULT_COLD_TO_WARM_THRESHOLD }, warmToHot: { accessThreshold: DEFAULT_WARM_TO_HOT_THRESHOLD } };
+    autoDemoterConfig = { hotToWarm: { ttlMs: DEFAULT_HOT_TTL_MS }, warmToCold: { ttlMs: DEFAULT_WARM_TTL_MS } };
+    migrationCallbacks = [];
+    errorObservers = [];
+    circuitBreakerObservers = [];
+    errorCounts = { hot: 0, warm: 0, cold: 0 };
+    keyRetryCounters = new Map();
+    correlationCounter = 0;
+    eventSubscribers = [];
+    entryPriorities = new Map();
+    pinnedEntries = new Set();
+    memoryLimits = {};
+    constructor(config) {
+        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) { this.migrationCallbacks.push(callback); }
+    onError(callback) { this.errorObservers.push(callback); }
+    onCircuitBreakerChange(callback) { this.circuitBreakerObservers.push(callback); }
+    notifyError(error) {
+        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 */ }
+        }
+    }
+    notifyCircuitBreakerChange(event) {
+        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 */ }
+        }
+    }
+    notifyMigration(event) {
+        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 */ }
+            }
+        }
+    }
+    doKey(key) { return `${this.config.doPrefix}${key}`; }
+    /**
+     * High-resolution timer for performance measurement
+     * Uses performance.now() when available, falls back to Date.now() * 1e6
+     */
+    getNowNs() {
+        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
+     */
+    updateIndex(key, tier, size, dirty = false) {
+        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 = { 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
+     */
+    enforceIndexBounds() {
+        // 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.
+     */
+    selectSmallestEntries(k, getScore) {
+        const result = [];
+        const resultScores = [];
+        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
+     */
+    evictIndexEntries(count) {
+        if (this.storageIndex.size === 0 || count <= 0)
+            return;
+        const startNs = this.getNowNs();
+        // Select comparison function based on policy
+        let getScore;
+        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 = [];
+        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
+     */
+    checkMemoryWarning() {
+        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
+     */
+    startIndexMaintenance() {
+        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() {
+        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() {
+        const startNs = this.getNowNs();
+        let removed = 0;
+        const keysToRemove = [];
+        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));
+                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));
+                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
+     */
+    getIndexEntryOptimized(key) {
+        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
+     */
+    shouldPromote(key, currentTier) {
+        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 };
+    }
+    isCircuitOpen(tier) {
+        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';
+    }
+    recordCircuitBreakerFailure(tier, error) {
+        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 });
+        }
+    }
+    recordCircuitBreakerSuccess(tier) {
+        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, options) {
+        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));
+            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, data, options) {
+        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) {
+        const errors = [];
+        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, data) {
+        const timestamp = Date.now();
+        const pageData = data ?? await this.r2Layer.get(key);
+        if (!pageData) {
+            const event = { 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 = { key, fromTier: 'cold', toTier: 'warm', success: true, timestamp, reason: 'access_pattern' };
+            this.notifyMigration(event);
+            return event;
+        }
+        catch (e) {
+            this.promotionStats.failed++;
+            const event = { 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, data) {
+        const timestamp = Date.now();
+        const pageData = data ?? await this.doStorage.get(this.doKey(key));
+        if (!pageData) {
+            const event = { 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 = { key, fromTier: 'warm', toTier: 'hot', success: true, timestamp, reason: 'access_pattern' };
+            this.notifyMigration(event);
+            return event;
+        }
+        catch (e) {
+            this.promotionStats.failed++;
+            const event = { 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, reason = 'ttl_expired') {
+        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 = { key, fromTier: 'hot', toTier: 'warm', success: true, timestamp, reason };
+            this.notifyMigration(event);
+            return event;
+        }
+        catch (e) {
+            this.demotionStats.failed++;
+            const event = { 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, reason = 'ttl_expired') {
+        const timestamp = Date.now();
+        try {
+            const data = await this.doStorage.get(this.doKey(key));
+            if (!data) {
+                const event = { 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 = { key, fromTier: 'warm', toTier: 'cold', success: true, timestamp, reason };
+            this.notifyMigration(event);
+            return event;
+        }
+        catch (e) {
+            this.demotionStats.failed++;
+            const event = { 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) {
+        if (!this.config.autoDemote)
+            return [];
+        const events = [];
+        const now = Date.now();
+        const hotCandidates = [];
+        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 = [];
+        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) {
+        const hotPages = [];
+        for (const entry of this.storageIndex.values()) {
+            if (entry.tier === 'hot')
+                hotPages.push(entry);
+        }
+        hotPages.sort((a, b) => a.lastAccess - b.lastAccess);
+        const events = [];
+        for (const entry of hotPages.slice(0, count))
+            events.push(await this.demoteFromHot(entry.key, 'lru_eviction'));
+        return events;
+    }
+    async syncDirtyToCold() {
+        let synced = 0;
+        for (const entry of this.storageIndex.values()) {
+            if (entry.dirty) {
+                try {
+                    const data = await this.doStorage.get(this.doKey(entry.key));
+                    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) { return this.storageIndex.get(key); }
+    hasInIndex(key) { return this.storageIndex.has(key); }
+    getTier(key) { 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() {
+        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, avgKeyLength = DEFAULT_AVG_KEY_LENGTH_CHARS) {
+        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() {
+        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) {
+        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() {
+        const indexStats = {
+            totalEntries: this.storageIndex.size,
+            byTier: { hot: 0, warm: 0, cold: 0 },
+            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() {
+        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) {
+        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() {
+        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() {
+        this.storageIndex.clear();
+        this.indexMemoryBytes = 0;
+        this.memoryWarningEmitted = false;
+        this.lastLookupKey = null;
+        this.lastLookupEntry = null;
+    }
+    resetHealth(tier) {
+        if (tier)
+            this.tierHealth[tier] = 'healthy';
+        else
+            this.tierHealth = { hot: 'healthy', warm: 'healthy', cold: 'healthy' };
+    }
+    getConfig() { return { ...this.config }; }
+    // DO Lifecycle Hooks
+    async onHibernate() {
+        const timestamp = Date.now();
+        let persistedCount = 0;
+        const hotKeys = [];
+        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, options) {
+        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));
+                    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;
+                const warmData = await this.doStorage.get(this.doKey(key));
+                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) {
+        const storage = this.doStorage;
+        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) {
+        const result = {};
+        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) {
+        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, state) {
+        this.circuitBreakers[tier].state = state;
+        if (state === 'open')
+            this.circuitBreakers[tier].openedAt = Date.now();
+    }
+    // Metrics Aggregation
+    getAggregatedMetrics() {
+        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 = {
+            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) {
+        const metrics = this.getAggregatedMetrics();
+        if (format === 'json')
+            return metrics;
+        const lines = [
+            '# 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) {
+        return {
+            readPage: async (pageId) => { const result = await this.read(pageId); return result.data; },
+            writePage: async (pageId, data) => { await this.write(pageId, data); },
+            deletePage: async (pageId) => { await this.delete(pageId); },
+        };
+    }
+    configureAutoPromoter(config) {
+        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() { return { ...this.autoPromoterConfig }; }
+    configureAutoDemoter(config) {
+        this.autoDemoterConfig = { ...config };
+        this.config.hotTtlMs = config.hotToWarm.ttlMs;
+        this.config.warmTtlMs = config.warmToCold.ttlMs;
+    }
+    getAutoDemoterConfig() { return { ...this.autoDemoterConfig }; }
+    setDemotionStrategy(tier, strategy) { this.demotionStrategies[tier] = strategy; }
+    async runDemotionWithStrategy(tier, count) {
+        const strategy = this.demotionStrategies[tier];
+        if (!strategy) {
+            if (tier === 'hot')
+                return this.evictLRUFromHot(count);
+            return [];
+        }
+        const entries = [];
+        for (const entry of this.storageIndex.values()) {
+            if (entry.tier === tier)
+                entries.push(entry);
+        }
+        const keysToDemote = strategy(entries, count);
+        const events = [];
+        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() {
+        const repairs = [];
+        for (const [key, entry] of this.storageIndex) {
+            let found = false, actualTier;
+            const warmData = await this.doStorage.get(this.doKey(key));
+            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, field, timestamp) {
+        const entry = this.storageIndex.get(key);
+        if (entry)
+            entry[field] = timestamp;
+    }
+    getAccessPatternMetrics(key) {
+        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) {
+        const events = [];
+        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, priority) { this.entryPriorities.set(key, priority); }
+    getEntryPriority(key) { return this.entryPriorities.get(key) ?? 'normal'; }
+    async batchPromoteToWarm(keys) { return Promise.all(keys.map(key => this.promoteToWarm(key))); }
+    async batchDemoteFromWarm(keys) { return Promise.all(keys.map(key => this.demoteFromWarm(key))); }
+    async healthCheck() {
+        const checkTier = async (tier) => {
+            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';
+        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() {
+        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) { this.memoryLimits = { ...this.memoryLimits, ...limits }; }
+    getMemoryLimits() { return { ...this.memoryLimits }; }
+    async prefetch(keys, options) {
+        const targetTier = options?.targetTier ?? 'warm';
+        const maxConcurrency = options?.maxConcurrency ?? 5;
+        const failedKeys = [];
+        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, options) {
+        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() {
+        return { version: 1, timestamp: Date.now(), index: Array.from(this.storageIndex.values()), stats: this.getStats() };
+    }
+    async restoreFromSnapshot(snapshot) {
+        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) {
+        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 = [];
+        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) {
+        let removedEntries = 0;
+        const keysToRemove = [];
+        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));
+                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, _tier) { this.pinnedEntries.add(key); }
+    unpinFromTier(key) { this.pinnedEntries.delete(key); }
+    isPinned(key) { return this.pinnedEntries.has(key); }
+    getCostBreakdown() {
+        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() {
+        const promotions = [];
+        const demotions = [];
+        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) {
+        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));
+        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) {
+    return new TieredStorageOrchestrator(config);
+}
+//# sourceMappingURL=tiered-orchestrator.js.map