/**
 * pipeline/cache.ts
 *
 * Content-aware caching for pipeline steps. Each step's cache key is derived
 * from a hash of its inputs (config files, context files, task files, etc.).
 * When inputs haven't changed between runs, cached outputs are reused.
 *
 * Cache storage: `results/cache/` directory with one JSON manifest per step.
 * Each manifest maps a content hash to the step's output metadata.
 *
 * Cache invalidation triggers:
 *   - Content change: any input file's content changes → hash changes → miss
 *   - Config change: config/models, config/sources, tasks/*.yaml changes → miss
 *   - Manual bypass: --no-cache flag skips all cache lookups
 *   - Cache clear: delete results/cache/ to start fresh
 */
/** A single cache entry — stored per step per unique input hash */
export interface CacheEntry {
    /** Duration of the original execution in milliseconds */
    durationMs: number;
    /** SHA-256 hash of all input content */
    inputHash: string;
    /** Output file paths that were produced (relative to package root) */
    outputPaths: string[];
    /** Human-readable summary of what was cached */
    summary: string;
    /** When this entry was created */
    timestamp: string;
}
/** Result of a cache lookup */
export type ManifestCacheLookupResult = {
    hit: false;
    currentHash: string;
} | {
    hit: true;
    entry: CacheEntry;
};
/** The cache manifest for a single pipeline step */
export interface CacheManifest {
    /** The most recent cache entry */
    entry: CacheEntry | null;
    /** Step name (e.g., "fetch-docs", "generate-configs") */
    step: string;
}
/** Stats collected across all pipeline steps for reporting */
export interface CacheStats {
    /** Steps where cache was hit (skipped execution) */
    hits: number;
    /** Steps where cache was missed (executed normally) */
    misses: number;
    /** Steps that were skipped for other reasons (--no-fetch, etc.) */
    skipped: number;
    /** Per-step detail */
    steps: Record<string, "disabled" | "hit" | "miss" | "skipped">;
    /** Total steps that participated in caching */
    total: number;
}
/** Create an empty CacheStats object */
export declare function createCacheStats(): CacheStats;
/** Format cache stats as a human-readable summary line */
export declare function formatCacheStats(stats: CacheStats): string;
/**
 * Collect all file paths that serve as inputs for a given pipeline step.
 * This is the core of cache key computation — if any of these files change,
 * the step must re-execute.
 */
export declare function getStepInputPaths(rootDir: string, step: string): string[];
/**
 * Compute a SHA-256 hash of the concatenated content of multiple files.
 * Files are sorted by path for deterministic ordering. Missing files
 * contribute a sentinel value so the hash changes if a file is deleted.
 *
 * Optional `context` strings are included in the hash so that non-file
 * state (e.g., filter flags, environment variables) can also participate
 * in cache key computation.
 */
export declare function hashFiles(paths: string[], context?: string[]): string;
/**
 * Look up the cache for a pipeline step.
 *
 * Computes the current input hash and compares it against the stored manifest.
 * Returns a hit if the hashes match AND all expected output files still exist.
 *
 * Optional `context` strings are included in the hash so that non-file
 * state (e.g., area/task filter flags) participates in cache key computation.
 */
export declare function lookupCache(rootDir: string, step: string, context?: string[]): ManifestCacheLookupResult;
/**
 * Read the cache manifest for a step.
 * Returns null if no manifest exists or it's corrupt.
 */
export declare function readManifest(rootDir: string, step: string): CacheManifest | null;
/**
 * Record a cache entry after a successful step execution.
 */
export declare function recordCache(rootDir: string, step: string, inputHash: string, summary: string, durationMs: number, outputPaths: string[]): void;
/**
 * Write a cache manifest for a step.
 * Creates the cache directory if it doesn't exist.
 */
export declare function writeManifest(rootDir: string, step: string, entry: CacheEntry): void;
