/**
 * ai-cache.ts
 *
 * Disk-based cache for page summaries and healing results.
 *
 * Stores analyzed page summaries, selector mappings, and healing results
 * on disk under .ai-cache/ so repeat visits to the same page skip re-analysis
 * and avoid unnecessary AI calls.
 *
 * Cache key = MD5 of (url + dominant element fingerprint).
 * TTL = 24 hours by default (configurable).
 *
 * The cache has two sub-stores:
 *   - pages/   — caches CompactElement[] + CompactStep[] + pomCode for a URL
 *   - healing/ — caches a successful healing result keyed by (testName, stepIndex, originalLocator)
 *
 * Stale entries are purged lazily (on getPage/getHealing calls) or eagerly
 * by calling purgeExpired(), which the MCP server calls on startup.
 *
 * Role in the overall flow:
 *   MCP server startup → aiCache.purgeExpired()
 *   generate_test (future) → aiCache.getPageSummary() / aiCache.setPageSummary()
 *   heal_test (future)     → aiCache.getHealingResult() / aiCache.setHealingResult()
 */
import { CompactElement, CompactStep } from '../types';
/** A cached page summary entry stored in .ai-cache/pages/. */
export interface CachedPageSummary {
    /** The URL this cache entry is for. */
    url: string;
    /** The page title at cache time. */
    title: string;
    /** Compressed element table. */
    elements: CompactElement[];
    /** Compressed step list with assertions. */
    steps: CompactStep[];
    /** Complete POM TypeScript source code. */
    pomCode: string;
    /** MD5 hash of (url + element keys) used as the cache key. */
    fingerprint: string;
    /** ISO timestamp when this entry was written. */
    cachedAt: string;
    /** Time-to-live in milliseconds. */
    ttlMs: number;
}
/** A cached healing result stored in .ai-cache/healing/. */
export interface CachedHealingResult {
    /** Test name this healing result belongs to. */
    testName: string;
    /** Zero-based step index. */
    stepIndex: number;
    /** The locator expression that originally failed. */
    originalLocator: string;
    /** The locator expression that successfully replaced it. */
    repairedLocator: string;
    /** Name of the healing strategy that was used. */
    strategy: string;
    /** ISO timestamp when this entry was written. */
    cachedAt: string;
    /** Time-to-live in milliseconds. */
    ttlMs: number;
}
/**
 * Manages a file-based cache for page summaries and healing results to
 * avoid redundant analysis and AI calls for pages that haven't changed.
 */
export declare class AICache {
    private cacheDir;
    /**
     * Initialize the cache directory structure asynchronously.
     * Does not block server startup — any directory creation failures are logged
     * as warnings, not thrown.
     *
     * @param baseDir - Root directory under which the .ai-cache/ folder is created.
     * @param ttlMs   - Default time-to-live for cache entries. Defaults to 24 hours.
     */
    constructor(baseDir: string, ttlMs?: number);
    /**
     * Compute a stable cache fingerprint from the URL and the first 20 element keys.
     * Fingerprint = MD5(url + sorted element keys).
     *
     * @param url         - The page URL.
     * @param elementKeys - The element key strings from the page analysis.
     * @returns A 12-character hex fingerprint string.
     */
    fingerprint(url: string, elementKeys: string[]): string;
    /**
     * Look up a cached page summary for the given URL and element fingerprint.
     * Returns null if no entry exists or if the entry has expired.
     *
     * @param url         - The page URL to look up.
     * @param elementKeys - Current element keys used to compute the fingerprint.
     * @returns The cached summary, or null on cache miss or expiry.
     */
    getPageSummary(url: string, elementKeys: string[]): Promise<CachedPageSummary | null>;
    /**
     * Store a page summary in the cache.
     *
     * @param summary - The page summary to cache (without fingerprint/cachedAt/ttlMs fields).
     * @param ttlMs   - Time-to-live override. Defaults to DEFAULT_TTL_MS (24 hours).
     */
    setPageSummary(summary: Omit<CachedPageSummary, 'fingerprint' | 'cachedAt' | 'ttlMs'>, ttlMs?: number): Promise<void>;
    /**
     * Compute a cache key for a healing result.
     *
     * @param testName        - Test name.
     * @param stepIndex       - Zero-based step index.
     * @param originalLocator - The locator that failed.
     * @returns A 12-character hex key.
     */
    private healKey;
    /**
     * Look up a cached healing result. Returns null on cache miss or expiry.
     *
     * @param testName        - Test name.
     * @param stepIndex       - Zero-based step index.
     * @param originalLocator - The locator expression that failed.
     * @returns The cached healing result, or null.
     */
    getHealingResult(testName: string, stepIndex: number, originalLocator: string): Promise<CachedHealingResult | null>;
    /**
     * Store a successful healing result in the cache.
     *
     * @param result - The healing result to cache (without cachedAt/ttlMs fields).
     * @param ttlMs  - Time-to-live override. Defaults to DEFAULT_TTL_MS (24 hours).
     */
    setHealingResult(result: Omit<CachedHealingResult, 'cachedAt' | 'ttlMs'>, ttlMs?: number): Promise<void>;
    /**
     * Delete all expired entries from both the pages and healing sub-stores.
     * Called on server startup to keep the cache directory from growing indefinitely.
     *
     * @returns The number of entries that were deleted.
     */
    purgeExpired(): Promise<number>;
    /**
     * Check whether a cache entry has exceeded its time-to-live.
     *
     * @param cachedAt - ISO timestamp when the entry was written.
     * @param ttlMs    - Time-to-live in milliseconds.
     * @returns True if the entry is older than its TTL.
     */
    private isExpired;
    /** The absolute path to the cache directory. */
    get directory(): string;
}
//# sourceMappingURL=ai-cache.d.ts.map