/**
 * Port: How evaluation caching works.
 *
 * The CacheStore abstracts pipeline step caching behind a uniform
 * interface. The StepRunner uses it for automatic cache lookup/record
 * so individual steps don't need to manage their own caching.
 *
 * Adapters:
 * - FilesystemCache — local results/cache/ directory (current behavior)
 * - ContentLakeCacheAdapter — decorator that adds remote fingerprint
 *   lookup on local cache miss
 * - NoOpCache (testing) — always misses
 *
 * @see packages/eval/src/pipeline/cache.ts — existing implementation
 * @see docs/design-docs/content-lake-eval-caching.md
 */
/**
 * Opaque cache key — a content hash of the step's input files.
 * Branded to prevent accidentally passing raw strings.
 */
export type CacheKey = string & {
    readonly __brand: "CacheKey";
};
/**
 * Stored metadata for a cache entry.
 * Kept minimal — just enough for cache status reporting.
 */
export interface CacheEntryMetadata {
    /** Duration of the original execution in milliseconds */
    durationMs: number;
    /** Output file paths produced (relative to package root) */
    outputPaths: string[];
    /** Human-readable summary of what was cached */
    summary: string;
    /** When this entry was created (ISO 8601) */
    timestamp: string;
}
/** Result of a cache lookup */
export type CacheLookupResult = {
    hit: true;
    entry: CacheEntryMetadata;
} | {
    hit: false;
};
/** Metadata to record after a successful step execution */
export interface CacheRecordInput {
    /** Duration of the execution in milliseconds */
    durationMs: number;
    /** Output file paths produced (relative to package root) */
    outputPaths: string[];
    /** Human-readable summary */
    summary: string;
}
/**
 * Port: Pipeline step caching.
 *
 * The StepRunner calls these methods around step execution:
 * 1. computeKey(step.cacheInputs(ctx)) → CacheKey
 * 2. lookup(stepName, key) → hit or miss
 * 3. (on miss) execute step
 * 4. (on success) record(stepName, key, metadata)
 */
export interface CacheStore {
    /** Compute a cache key from file paths and optional context strings */
    computeKey(inputPaths: string[], context?: string[]): Promise<CacheKey>;
    /** Look up a cache entry by step name and key */
    lookup(step: string, key: CacheKey): Promise<CacheLookupResult>;
    /** Record a cache entry after successful step execution */
    record(step: string, key: CacheKey, metadata: CacheRecordInput): Promise<void>;
    /** Clear all cache entries */
    clear(): Promise<void>;
}
