@dotdo/postgres 0.1.0

package/dist/storage/tiered-orchestrator.d.ts

@@ -0,0 +1,951 @@
+/**
+ * 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';
+/**
+ * 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;
+    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 {
+    lookupCount: number;
+    updateCount: number;
+    evictionCount: number;
+    totalLookupTimeNs: number;
+    totalUpdateTimeNs: number;
+    totalEvictionTimeNs: number;
+    totalMaintenanceTimeNs: number;
+    avgLookupTimeNs: number;
+    avgUpdateTimeNs: number;
+    peakEntries: number;
+    peakMemoryBytes: number;
+    evictionBatches: number;
+    entriesPerEvictionBatch: number;
+    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>;
+}
+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 declare class TieredStorageOrchestrator {
+    private cacheLayer?;
+    private swrCacheLayer?;
+    private doStorage;
+    private r2Layer;
+    private config;
+    private storageIndex;
+    private indexMemoryBytes;
+    private maintenanceTimer?;
+    private memoryWarningEmitted;
+    /**
+     * 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;
+    private performanceMetrics;
+    private lastLookupKey;
+    private lastLookupEntry;
+    private warmStats;
+    private promotionStats;
+    private demotionStats;
+    private tierHealth;
+    private circuitBreakers;
+    private latencyMeasurements;
+    private demotionStrategies;
+    private autoPromoterConfig;
+    private autoDemoterConfig;
+    private migrationCallbacks;
+    private errorObservers;
+    private circuitBreakerObservers;
+    private errorCounts;
+    private keyRetryCounters;
+    private correlationCounter;
+    private eventSubscribers;
+    private entryPriorities;
+    private pinnedEntries;
+    private memoryLimits;
+    constructor(config: TieredOrchestratorConfig);
+    onMigration(callback: TierMigrationCallback): void;
+    onError(callback: ErrorObserver): void;
+    onCircuitBreakerChange(callback: CircuitBreakerChangeObserver): void;
+    private notifyError;
+    private notifyCircuitBreakerChange;
+    private notifyMigration;
+    private doKey;
+    /**
+     * High-resolution timer for performance measurement
+     * Uses performance.now() when available, falls back to Date.now() * 1e6
+     */
+    private getNowNs;
+    /**
+     * 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;
+    /**
+     * Enforce index bounds by evicting entries if necessary
+     */
+    private enforceIndexBounds;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Check and emit memory warning if threshold exceeded
+     */
+    private checkMemoryWarning;
+    /**
+     * Start periodic index maintenance
+     */
+    private startIndexMaintenance;
+    /**
+     * Stop periodic index maintenance
+     */
+    stopIndexMaintenance(): void;
+    /**
+     * 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
+     */
+    runIndexMaintenance(): Promise<{
+        removed: number;
+        durationMs: number;
+    }>;
+    /**
+     * 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;
+    /**
+     * 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;
+    private isCircuitOpen;
+    private recordCircuitBreakerFailure;
+    private recordCircuitBreakerSuccess;
+    read(key: string, options?: ReadOptions): Promise<ReadResult>;
+    write(key: string, data: Uint8Array, options?: WriteOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    promoteToWarm(key: string, data?: Uint8Array): Promise<TierMigrationEvent>;
+    promoteToHot(key: string, data?: Uint8Array): Promise<TierMigrationEvent>;
+    demoteFromHot(key: string, reason?: TierMigrationEvent['reason']): Promise<TierMigrationEvent>;
+    demoteFromWarm(key: string, reason?: TierMigrationEvent['reason']): Promise<TierMigrationEvent>;
+    runDemotionCycle(maxDemotions?: number): Promise<TierMigrationEvent[]>;
+    evictLRUFromHot(count: number): Promise<TierMigrationEvent[]>;
+    syncDirtyToCold(): Promise<number>;
+    getIndexEntry(key: string): StorageIndexEntry | undefined;
+    hasInIndex(key: string): boolean;
+    getTier(key: string): StorageTier | undefined;
+    /**
+     * 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;
+    };
+    /**
+     * 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?: number): number;
+    /**
+     * 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;
+    /**
+     * 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?: number): {
+        isNearLimit: boolean;
+        currentBytes: number;
+        limitBytes: number | null;
+        utilizationPercent: number | null;
+        warningThreshold: number;
+    };
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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?: boolean): void;
+    /**
+     * Get a human-readable performance summary
+     *
+     * @returns Formatted string with key performance metrics
+     */
+    getPerformanceSummary(): string;
+    /**
+     * Clear the index and all associated tracking
+     */
+    clearIndex(): void;
+    resetHealth(tier?: StorageTier): void;
+    getConfig(): InternalConfig;
+    onHibernate(): Promise<HibernateResult>;
+    onWake(hibernateState: HibernateState | null, options?: WakeOptions): Promise<WakeResult>;
+    scheduleAlarm(alarmConfig: AlarmConfig): Promise<void>;
+    handleAlarm(alarmConfig: AlarmConfig & {
+        rescheduleMs?: number;
+    }): Promise<AlarmResult>;
+    getCircuitBreakerState(tier: StorageTier): CircuitBreakerStateInfo;
+    setCircuitBreakerState(tier: StorageTier, state: CircuitBreakerState): void;
+    getAggregatedMetrics(): AggregatedMetrics;
+    exportMetrics(format: 'prometheus' | 'json'): string | AggregatedMetrics;
+    createVFSInterface(_options?: {
+        pageSize?: number;
+        promotionThreshold?: number;
+    }): VFSInterface;
+    configureAutoPromoter(config: AutoPromoterConfig): void;
+    getAutoPromoterConfig(): AutoPromoterConfig;
+    configureAutoDemoter(config: AutoDemoterConfig): void;
+    getAutoDemoterConfig(): AutoDemoterConfig;
+    setDemotionStrategy(tier: StorageTier, strategy: DemotionStrategy): void;
+    runDemotionWithStrategy(tier: StorageTier, count: number): Promise<TierMigrationEvent[]>;
+    runConsistencyCheck(): Promise<{
+        inconsistencies: number;
+        repairs: {
+            key: string;
+            issue: string;
+            action: string;
+        }[];
+    }>;
+    setIndexEntryTimestamp(key: string, field: 'created' | 'lastAccess' | 'modified', timestamp: number): void;
+    getAccessPatternMetrics(key: string): {
+        isBurst: boolean;
+        accessRate: number;
+        recentAccesses: number;
+    };
+    evictByMemoryPressure(bytesToFree: number): Promise<TierMigrationEvent[]>;
+    setEntryPriority(key: string, priority: 'low' | 'normal' | 'high'): void;
+    getEntryPriority(key: string): 'low' | 'normal' | 'high';
+    batchPromoteToWarm(keys: string[]): Promise<TierMigrationEvent[]>;
+    batchDemoteFromWarm(keys: string[]): Promise<TierMigrationEvent[]>;
+    healthCheck(): Promise<{
+        overall: 'healthy' | 'degraded' | 'unhealthy';
+        tiers: Record<StorageTier, {
+            status: string;
+            latency: number;
+            error?: string;
+        }>;
+        latency: Record<StorageTier, number>;
+    }>;
+    getMemoryUsage(): {
+        hot: number;
+        warm: number;
+        cold: number;
+        total: number;
+        limit: number;
+        utilizationPercent: number;
+    };
+    setMemoryLimit(limits: Partial<Record<StorageTier, number>>): void;
+    getMemoryLimits(): Partial<Record<StorageTier, number>>;
+    prefetch(keys: string[], options?: {
+        targetTier?: StorageTier;
+        maxConcurrency?: number;
+    }): Promise<{
+        prefetchedCount: number;
+        failedKeys: string[];
+    }>;
+    subscribeToEvents(callback: TierMigrationCallback, options?: {
+        filter?: {
+            type?: 'promotion' | 'demotion';
+        };
+    }): () => void;
+    createSnapshot(): Promise<{
+        version: number;
+        timestamp: number;
+        index: StorageIndexEntry[];
+        stats: OrchestratorStats;
+    }>;
+    restoreFromSnapshot(snapshot: {
+        version: number;
+        timestamp: number;
+        index: StorageIndexEntry[];
+        stats: Record<string, unknown>;
+    }): Promise<void>;
+    warmup(options: {
+        strategy: 'all' | 'most-accessed' | 'recent';
+        targetTier: StorageTier;
+        maxBytes?: number;
+        limit?: number;
+    }): Promise<{
+        warmedUp: number;
+        bytesTransferred: number;
+        keys: string[];
+    }>;
+    garbageCollect(options?: {
+        compactCold?: boolean;
+    }): Promise<{
+        removedEntries: number;
+        compactionStats?: {
+            bytesReclaimed: number;
+        };
+    }>;
+    pinToTier(key: string, _tier: StorageTier): void;
+    unpinFromTier(key: string): void;
+    isPinned(key: string): boolean;
+    getCostBreakdown(): {
+        storage: {
+            r2: number;
+            do: number;
+            cache: number;
+        };
+        operations: {
+            r2Writes: number;
+            r2Reads: number;
+            doWrites: number;
+            doReads: number;
+        };
+        total: number;
+        projectedMonthly: number;
+    };
+    optimizeTierPlacement(): Promise<{
+        promotions: Array<{
+            key: string;
+            currentTier: StorageTier;
+            suggestedTier: StorageTier;
+            reason: string;
+        }>;
+        demotions: Array<{
+            key: string;
+            currentTier: StorageTier;
+            suggestedTier: StorageTier;
+            reason: string;
+        }>;
+        estimatedSavings: number;
+    }>;
+    ensureDurability(key: string): Promise<{
+        durable: boolean;
+        tier: StorageTier | null;
+        copied: boolean;
+    }>;
+}
+export declare function createTieredStorageOrchestrator(config: TieredOrchestratorConfig): TieredStorageOrchestrator;
+export {};
+//# sourceMappingURL=tiered-orchestrator.d.ts.map