/**
 * Cache Engine Implementation
 * Central coordinator for all cache operations with tier fallthrough
 * Requirements: 6.1, 6.2, 6.3, 6.4, 6.5
 */
import { CacheValue, SetOptions } from '../types/index.js';
import { StorageTier } from '../storage/StorageTier.js';
import { AccessTracker } from '../tracking/AccessTracker.js';
import { TierManager } from '../tier/TierManager.js';
import { EvictionPolicy } from '../eviction/EvictionPolicy.js';
import { SnapshotManager } from './SnapshotManager.js';
/**
 * Configuration for CacheEngine
 */
export interface CacheEngineConfig {
    /** Default TTL in seconds for keys without explicit TTL */
    defaultTtlSeconds?: number;
    /** Whether to record access on get operations */
    trackAccess?: boolean;
    /** Interval in milliseconds for background expiration scanner (default: 1000ms) */
    expirationScanIntervalMs?: number;
    /** Number of keys to check per expiration scan cycle (default: 100) */
    expirationScanBatchSize?: number;
    /** Path to save/load RAM tier snapshots for persistence (optional) */
    snapshotPath?: string;
    /** Interval in milliseconds for tier movement processing (default: 5000ms) */
    tierMovementIntervalMs?: number;
}
/**
 * Dependencies required by CacheEngine
 */
export interface CacheEngineDependencies {
    ramTier: StorageTier;
    ssdTier: StorageTier;
    dbTier: StorageTier;
    accessTracker: AccessTracker;
    tierManager: TierManager;
    evictionPolicy: EvictionPolicy;
}
/**
 * CacheEngine is the central coordinator for all cache operations.
 * It implements transparent data retrieval across tiers and manages
 * data placement based on access patterns.
 *
 * Requirements:
 * - 6.1: Check RAM_Tier first on GET request
 * - 6.2: Check SSD_Tier when data not found in RAM_Tier
 * - 6.3: Check DB_Tier when data not found in SSD_Tier
 * - 6.4: Return null when data not found in any tier
 * - 6.5: Return data regardless of which tier contains it
 */
export declare class CacheEngine {
    private readonly ramTier;
    private readonly ssdTier;
    private readonly dbTier;
    private readonly accessTracker;
    private readonly tierManager;
    private readonly evictionPolicy;
    private readonly config;
    /** Tier search order for fallthrough */
    private readonly tierOrder;
    /** Timer for background expiration scanner */
    private expirationScannerTimer;
    /** Flag to track if expiration scanner is running */
    private isExpirationScannerRunning;
    /** Flag to track if the cache engine is running */
    private isRunning;
    /** Timer for background tier movement processor */
    private tierMovementTimer;
    /** Interval in milliseconds for tier movement processing (default: 5000ms) */
    private tierMovementIntervalMs;
    /** Snapshot manager for RAM tier persistence */
    private readonly snapshotManager;
    constructor(dependencies: CacheEngineDependencies, config?: CacheEngineConfig);
    /**
     * Get the storage tier instance for a given tier type.
     */
    private getTierStorage;
    /**
     * Retrieve a value by key with tier fallthrough.
     * Searches RAM → SSD → DB until found or returns null.
     * Implements lazy expiration check during retrieval.
     *
     * Requirements:
     * - 6.1: Check RAM_Tier first
     * - 6.2: Check SSD_Tier when not in RAM
     * - 6.3: Check DB_Tier when not in SSD
     * - 6.4: Return null when not found in any tier
     * - 6.5: Return data regardless of which tier contains it
     * - 7.3: Perform lazy expiration checks during key access
     *
     * @param key - The cache key to retrieve
     * @returns The cached value with tier info, or null if not found
     */
    get(key: string): Promise<CacheValue | null>;
    /**
     * Store a key-value pair with optional TTL.
     * Places data in the appropriate tier based on access patterns.
     *
     * @param key - The cache key
     * @param value - The value to store
     * @param options - Optional settings (TTL, NX, XX)
     */
    set(key: string, value: Buffer, options?: SetOptions): Promise<void>;
    /**
     * Delete a key from all tiers and the key index.
     *
     * @param key - The cache key to delete
     * @returns true if the key was deleted from any tier, false otherwise
     */
    delete(key: string): Promise<boolean>;
    /**
     * Check if a key exists in any tier.
     *
     * @param key - The cache key to check
     * @returns true if the key exists, false otherwise
     */
    exists(key: string): Promise<boolean>;
    /**
     * Delete a key from all tiers.
     * @returns true if deleted from any tier
     */
    private deleteFromAllTiers;
    /**
     * Evict data from a tier to make space.
     * @param tier - The tier to evict from
     * @param bytesNeeded - Minimum bytes to free
     * @returns true if enough space was freed
     */
    private evictFromTier;
    /**
     * Get the next lower tier in the hierarchy.
     */
    private getNextLowerTier;
    /**
     * Retrieve multiple values by keys with tier fallthrough.
     * Searches RAM → SSD → DB for each key until found or returns null.
     *
     * Requirements:
     * - 1.4: Support MGET command to retrieve multiple values in a single request
     *
     * @param keys - Array of cache keys to retrieve
     * @returns Array of cached values with tier info, or null for keys not found
     */
    mget(keys: string[]): Promise<(CacheValue | null)[]>;
    /**
     * Store multiple key-value pairs with optional TTL.
     * Places data in the appropriate tier based on access patterns.
     *
     * Requirements:
     * - 1.5: Support MSET command to store multiple key-value pairs in a single request
     *
     * @param entries - Array of key-value pairs with optional settings
     */
    mset(entries: Array<{
        key: string;
        value: Buffer;
        options?: SetOptions;
    }>): Promise<void>;
    /**
     * Atomically increment a numeric value stored at key.
     * If the key doesn't exist, it is initialized to 0 before incrementing.
     * If the value is not a valid integer, throws an error.
     *
     * Requirements:
     * - 1.9: Support INCR and DECR commands for atomic integer operations
     *
     * @param key - The cache key
     * @param by - Amount to increment by (default: 1)
     * @returns The new value after incrementing
     * @throws Error if the value is not a valid integer
     */
    incr(key: string, by?: number): Promise<number>;
    /**
     * Atomically decrement a numeric value stored at key.
     * If the key doesn't exist, it is initialized to 0 before decrementing.
     * If the value is not a valid integer, throws an error.
     *
     * Requirements:
     * - 1.9: Support INCR and DECR commands for atomic integer operations
     *
     * @param key - The cache key
     * @param by - Amount to decrement by (default: 1)
     * @returns The new value after decrementing
     * @throws Error if the value is not a valid integer
     */
    decr(key: string, by?: number): Promise<number>;
    /**
     * Get the TierManager instance for external access.
     */
    getTierManager(): TierManager;
    /**
     * Get the AccessTracker instance for external access.
     */
    getAccessTracker(): AccessTracker;
    /**
     * Get the EvictionPolicy instance for external access.
     */
    getEvictionPolicy(): EvictionPolicy;
    /**
     * Set expiration time on an existing key.
     *
     * Requirement 7.1: Store the expiration timestamp when a key is set with a TTL
     *
     * @param key - The cache key
     * @param ttlSeconds - Time-to-live in seconds
     * @returns true if the key exists and expiration was set, false otherwise
     */
    expire(key: string, ttlSeconds: number): Promise<boolean>;
    /**
     * Get the remaining time-to-live for a key in seconds.
     *
     * @param key - The cache key
     * @returns Remaining TTL in seconds, -1 if no expiration, -2 if key doesn't exist
     */
    ttl(key: string): Promise<number>;
    /**
     * Start the background expiration scanner.
     * The scanner periodically checks for expired keys and removes them.
     *
     * Requirement 7.4: Perform periodic background expiration scans
     */
    startExpirationScanner(): void;
    /**
     * Stop the background expiration scanner.
     */
    stopExpirationScanner(): void;
    /**
     * Check if the expiration scanner is currently running.
     */
    isExpirationScannerActive(): boolean;
    /**
     * Run a single expiration scan cycle.
     * Checks a batch of keys for expiration and deletes expired ones.
     *
     * Requirement 7.2: Remove keys when their TTL expires
     * Requirement 7.4: Perform periodic background expiration scans
     */
    private runExpirationScan;
    /**
     * Manually trigger an expiration scan.
     * Useful for testing or immediate cleanup.
     *
     * @returns Number of keys deleted
     */
    scanExpiredKeys(): Promise<number>;
    /**
     * Start the background tier movement processor.
     * The processor periodically evaluates keys for promotion/demotion
     * and processes pending tier movements.
     */
    private startTierMovementProcessor;
    /**
     * Evaluate all keys for promotion/demotion and process pending movements.
     * This is called periodically by the tier movement processor.
     */
    private evaluateAndProcessTierMovements;
    /**
     * Stop the background tier movement processor.
     */
    private stopTierMovementProcessor;
    /**
     * Initialize and start the cache engine.
     * Starts all background processes including expiration scanner and tier movement processor.
     * If a snapshot path is configured, attempts to restore from the last snapshot.
     *
     * Requirement 11.1: Persist RAM_Tier data to SSD_Tier during graceful shutdown
     * Requirement 11.2: Restore the tier index from persistent storage on startup
     * Requirement 11.4: Recover from the last snapshot and SSD_Tier state on unexpected shutdown
     *
     * @throws Error if the engine is already running
     */
    start(): Promise<void>;
    /**
     * Rebuild the key index from SSD and DB tiers.
     * This recovers keys that were persisted but not in the RAM snapshot.
     */
    private rebuildKeyIndexFromPersistentTiers;
    /**
     * Gracefully shutdown the cache engine.
     * Stops all background processes, processes pending tier movements,
     * saves a snapshot of RAM tier data, and persists RAM tier data to SSD for recovery on next start.
     *
     * Requirement 11.1: Persist RAM_Tier data to SSD_Tier during graceful shutdown
     * Requirement 11.3: Support configurable persistence intervals for RAM_Tier snapshots
     */
    shutdown(): Promise<void>;
    /**
     * Persist all RAM tier data to SSD tier for recovery on next start.
     * This is called during graceful shutdown.
     *
     * Requirement 11.1: Persist RAM_Tier data to SSD_Tier during graceful shutdown
     */
    private persistRamTierToSsd;
    /**
     * Check if the cache engine is currently running.
     *
     * @returns true if the engine is running, false otherwise
     */
    isEngineRunning(): boolean;
    /**
     * Save a snapshot of the RAM tier to the configured path.
     *
     * Requirement 11.3: Support configurable persistence intervals for RAM_Tier snapshots
     */
    private saveSnapshot;
    /**
     * Restore RAM tier from a snapshot at the configured path.
     *
     * Requirement 11.2: Restore the tier index from persistent storage on startup
     * Requirement 11.4: Recover from the last snapshot and SSD_Tier state on unexpected shutdown
     */
    private restoreFromSnapshot;
    /**
     * Get the SnapshotManager instance for external access.
     */
    getSnapshotManager(): SnapshotManager;
    /**
     * Manually create and save a snapshot.
     * Useful for periodic snapshots or manual backup.
     *
     * @param path - Optional path to save to (defaults to configured snapshotPath)
     * @returns The created snapshot, or null if no path is configured
     */
    createAndSaveSnapshot(path?: string): Promise<import('./SnapshotManager.js').RamSnapshot | null>;
}
//# sourceMappingURL=CacheEngine.d.ts.map