/**
 * Tier Manager Implementation
 * Handles data movement between storage tiers and maintains unified key index
 * Requirements: 2.7, 4.1, 4.2, 4.3, 4.4, 4.6
 */
import { Tier, KeyIndexEntry } from '../types/index.js';
import { StorageTier } from '../storage/StorageTier.js';
import { AccessTracker } from '../tracking/AccessTracker.js';
/**
 * Thresholds for tier classification based on access frequency
 * Access frequency is measured in accesses per minute
 */
export interface TierThresholds {
    /** Accesses per minute to be classified as "hot" (RAM tier) */
    hotAccessFrequency: number;
    /** Accesses per minute to be classified as "warm" (SSD tier) */
    warmAccessFrequency: number;
    /** Below this frequency is classified as "cold" (DB tier) */
    coldAccessFrequency: number;
}
/**
 * Statistics about tier distribution and usage
 */
export interface TierStats {
    /** Statistics for RAM tier */
    ram: TierStatEntry;
    /** Statistics for SSD tier */
    ssd: TierStatEntry;
    /** Statistics for DB tier */
    db: TierStatEntry;
    /** Total keys across all tiers */
    totalKeys: number;
    /** Total bytes across all tiers */
    totalBytes: number;
}
/**
 * Statistics for a single tier
 */
export interface TierStatEntry {
    /** Number of keys in this tier */
    keyCount: number;
    /** Total bytes used in this tier */
    usedBytes: number;
    /** Percentage of total keys in this tier */
    keyPercentage: number;
    /** Percentage of total bytes in this tier */
    bytePercentage: number;
}
/**
 * Result of batch tier movement operations
 */
export interface MovementResult {
    /** Number of successful promotions */
    promotions: number;
    /** Number of successful demotions */
    demotions: number;
    /** Errors encountered during movement */
    errors: Error[];
}
/**
 * Entry in the movement queue for async processing
 */
export interface MovementQueueEntry {
    /** The key to move */
    key: string;
    /** Source tier */
    sourceTier: Tier;
    /** Target tier */
    targetTier: Tier;
    /** Priority for processing (higher = process first) */
    priority: number;
    /** Timestamp when queued */
    queuedAt: number;
    /** Reason for movement */
    reason: 'promotion' | 'demotion' | 'eviction' | 'prediction';
}
/**
 * Storage tiers configuration for TierManager
 */
export interface StorageTiers {
    ram: StorageTier;
    ssd: StorageTier;
    db: StorageTier;
}
/**
 * TierManager handles tier placement decisions and maintains the unified key index.
 *
 * The unified key index provides O(1) lookup for determining which tier contains
 * a given key, eliminating the need to search through all tiers.
 *
 * Requirements:
 * - 2.7: Maintain a unified key index across all tiers for O(1) tier location lookup
 * - 4.1: Promote to RAM when access frequency exceeds hot threshold
 * - 4.2: Demote from RAM to SSD when frequency falls below warm threshold
 * - 4.3: Demote from SSD to DB when frequency falls below cold threshold
 * - 4.4: Evaluate promotion when data is accessed from lower tiers
 * - 4.6: Support configurable thresholds for hot, warm, and cold classification
 */
export declare class TierManager {
    /** Unified key index for O(1) tier lookup - Requirement 2.7 */
    private keyIndex;
    /** Tier classification thresholds - Requirement 4.6 */
    private thresholds;
    /** Storage tiers for data movement */
    private storageTiers;
    /** Access tracker for frequency-based decisions */
    private accessTracker;
    /**
     * Movement queue for async batch processing - Requirement 4.5, 4.7
     * Stores pending tier movements to be processed asynchronously
     */
    private movementQueue;
    /** Batch size for processing movements */
    private batchSize;
    /** Flag to track if processing is currently running */
    private isProcessing;
    constructor(thresholds?: Partial<TierThresholds>);
    /**
     * Set the storage tiers for data movement operations.
     * Must be called before promote/demote operations.
     *
     * @param tiers - The storage tier implementations
     */
    setStorageTiers(tiers: StorageTiers): void;
    /**
     * Set the access tracker for frequency-based tier decisions.
     * Must be called before evaluatePromotion/evaluateDemotion operations.
     *
     * @param tracker - The access tracker instance
     */
    setAccessTracker(tracker: AccessTracker): void;
    /**
     * Get the tier where a key is currently stored.
     * Provides O(1) lookup using the unified key index.
     *
     * @param key - The cache key to look up
     * @returns The tier containing the key, or null if not found
     *
     * Requirement 2.7: O(1) tier location lookup
     */
    getTierForKey(key: string): Tier | null;
    /**
     * Get statistics about tier distribution and usage.
     *
     * @returns Statistics for all tiers including key counts, bytes, and percentages
     */
    getTierStats(): TierStats;
    /**
     * Set the thresholds for tier classification.
     *
     * @param thresholds - New threshold values for hot/warm/cold classification
     *
     * Requirement 4.6: Support configurable thresholds
     */
    setThresholds(thresholds: TierThresholds): void;
    /**
     * Get the current tier thresholds.
     */
    getThresholds(): TierThresholds;
    /**
     * Register a key in the unified index.
     * Called when a key is stored in any tier.
     *
     * @param entry - The key index entry to register
     */
    registerKey(entry: KeyIndexEntry): void;
    /**
     * Update the tier for an existing key in the index.
     * Called during promotion/demotion operations.
     *
     * @param key - The key to update
     * @param newTier - The new tier for the key
     * @returns true if the key was found and updated, false otherwise
     */
    updateKeyTier(key: string, newTier: Tier): boolean;
    /**
     * Update the size of a key in the index.
     * Called when a key's value is updated.
     *
     * @param key - The key to update
     * @param sizeBytes - The new size in bytes
     * @returns true if the key was found and updated, false otherwise
     */
    updateKeySize(key: string, sizeBytes: number): boolean;
    /**
     * Remove a key from the unified index.
     * Called when a key is deleted from the cache.
     *
     * @param key - The key to remove
     * @returns true if the key was found and removed, false otherwise
     */
    removeKey(key: string): boolean;
    /**
     * Get the full index entry for a key.
     *
     * @param key - The key to look up
     * @returns The full index entry, or undefined if not found
     */
    getKeyEntry(key: string): KeyIndexEntry | undefined;
    /**
     * Check if a key exists in the index.
     *
     * @param key - The key to check
     * @returns true if the key exists in any tier
     */
    hasKey(key: string): boolean;
    /**
     * Get all keys in a specific tier.
     *
     * @param tier - The tier to get keys from
     * @returns Array of keys in the specified tier
     */
    getKeysInTier(tier: Tier): string[];
    /**
     * Determine the appropriate tier for a key based on access frequency.
     *
     * @param accessFrequency - Access frequency in accesses per minute
     * @returns The recommended tier based on the frequency
     */
    determineTierByFrequency(accessFrequency: number): Tier;
    /**
     * Get the total number of keys in the index.
     */
    getKeyCount(): number;
    /**
     * Clear all entries from the key index.
     * Used for testing or reset operations.
     */
    clear(): void;
    /**
     * Get all keys that have expired.
     *
     * @returns Array of keys that have passed their expiration time
     */
    getExpiredKeys(): string[];
    /**
     * Update the expiration time for a key.
     *
     * @param key - The key to update
     * @param expiresAt - New expiration timestamp (null for no expiration)
     * @returns true if the key was found and updated, false otherwise
     */
    updateKeyExpiration(key: string, expiresAt: number | null): boolean;
    /**
     * Get the storage tier instance for a given tier type.
     *
     * @param tier - The tier type
     * @returns The storage tier instance
     */
    private getStorageTier;
    /**
     * Evaluate if a key should be promoted to a higher tier based on access frequency.
     *
     * Requirement 4.4: Evaluate promotion when data is accessed from lower tiers
     *
     * @param key - The key to evaluate
     * @returns The target tier for promotion, or null if no promotion needed
     */
    evaluatePromotion(key: string): Tier | null;
    /**
     * Evaluate if a key should be demoted to a lower tier based on access frequency.
     *
     * Requirement 4.2: Demote from RAM to SSD when frequency falls below warm threshold
     * Requirement 4.3: Demote from SSD to DB when frequency falls below cold threshold
     *
     * @param key - The key to evaluate
     * @returns The target tier for demotion, or null if no demotion needed
     */
    evaluateDemotion(key: string): Tier | null;
    /**
     * Promote a key to a higher tier.
     * Moves data from the current tier to the target tier.
     *
     * Requirement 4.1: Promote to RAM when access frequency exceeds hot threshold
     *
     * @param key - The key to promote
     * @param targetTier - The target tier (must be higher than current)
     */
    promote(key: string, targetTier: Tier): Promise<void>;
    /**
     * Demote a key to a lower tier.
     * Moves data from the current tier to the target tier.
     *
     * Requirement 4.2: Demote from RAM to SSD when frequency falls below warm threshold
     * Requirement 4.3: Demote from SSD to DB when frequency falls below cold threshold
     *
     * @param key - The key to demote
     * @param targetTier - The target tier (must be lower than current)
     */
    demote(key: string, targetTier: Tier): Promise<void>;
    /**
     * Check if tier A is higher than tier B in the tier hierarchy.
     * Hierarchy: ram > ssd > db
     *
     * @param tierA - First tier
     * @param tierB - Second tier
     * @returns true if tierA is higher than tierB
     */
    private isHigherTier;
    /**
     * Check if tier A is lower than tier B in the tier hierarchy.
     * Hierarchy: ram > ssd > db
     *
     * @param tierA - First tier
     * @param tierB - Second tier
     * @returns true if tierA is lower than tierB
     */
    private isLowerTier;
    /**
     * Queue a movement for async batch processing.
     * Movements are processed asynchronously to avoid blocking read operations.
     *
     * Requirement 4.5: Perform tier movements asynchronously to avoid blocking read operations
     *
     * @param entry - The movement queue entry to add
     */
    queueMovement(entry: Omit<MovementQueueEntry, 'queuedAt'>): void;
    /**
     * Process pending movements in batches.
     * Batches movements to minimize I/O overhead.
     *
     * Requirement 4.5: Perform tier movements asynchronously to avoid blocking read operations
     * Requirement 4.7: Batch tier movements to minimize I/O overhead
     *
     * @returns Result of the batch processing including counts and errors
     */
    processPendingMovements(): Promise<MovementResult>;
    /**
     * Get the current size of the movement queue.
     *
     * @returns Number of pending movements in the queue
     */
    getQueueSize(): number;
    /**
     * Clear all pending movements from the queue.
     */
    clearQueue(): void;
    /**
     * Get a copy of the current movement queue.
     * Useful for inspection and debugging.
     *
     * @returns Array of pending movement entries
     */
    getQueuedMovements(): MovementQueueEntry[];
    /**
     * Set the batch size for processing movements.
     *
     * @param size - Number of movements to process per batch
     */
    setBatchSize(size: number): void;
    /**
     * Get the current batch size.
     *
     * @returns Current batch size for movement processing
     */
    getBatchSize(): number;
    /**
     * Check if movement processing is currently running.
     *
     * @returns true if processing is in progress
     */
    isProcessingMovements(): boolean;
    /**
     * Remove a specific key from the movement queue.
     * Useful when a key is deleted and pending movements should be cancelled.
     *
     * @param key - The key to remove from the queue
     * @returns true if a movement was removed, false otherwise
     */
    removeFromQueue(key: string): boolean;
    /**
     * Queue proactive prefetch promotions based on prediction engine results.
     * Promotes predicted keys to RAM tier for faster access.
     *
     * Requirement 8.2: When the Prediction_Engine identifies a high-probability future access,
     * THE Tier_Manager SHALL proactively promote the data to RAM_Tier
     *
     * @param keys - Array of keys predicted to be accessed soon
     * @returns Number of keys queued for promotion
     */
    queuePredictedPromotions(keys: string[]): number;
    /**
     * Process proactive prefetch from prediction engine.
     * This is a convenience method that queues and immediately processes predicted promotions.
     *
     * Requirement 8.2: Proactive promotion to RAM_Tier based on predictions
     *
     * @param keys - Array of keys predicted to be accessed soon
     * @returns Result of the promotion processing
     */
    processProactivePrefetch(keys: string[]): Promise<MovementResult>;
}
//# sourceMappingURL=TierManager.d.ts.map