/**
 * Disk-backed TTL cache for API responses.
 *
 * Layout: `<cache home>/us-gov-open-data-mcp/v3/<namespace>/<sha256(key)>.json`,
 * one file per response, holding `{ key, fetchedAt, expires, data }`.
 *
 * - Writes go to a temp file and are renamed into place, so readers (in this
 *   or another process) see either the old entry or the new one, never a torn
 *   file. The last writer wins.
 * - Reads go to disk every time; there is no process-wide copy of the store to
 *   go stale or to rewrite in full.
 * - Entries larger than `maxEntryBytes` are not stored. When the total passes
 *   `maxTotalBytes`, a sweep deletes the least recently used entries (file
 *   mtime, refreshed on every hit) until the total is under 80% of the budget.
 * - The directories are 0700 and the files 0600 on POSIX. Keys never contain
 *   credentials (see client.ts). If no private directory can be created, the
 *   cache is kept in memory for the life of the process instead of falling
 *   back to a shared location such as /tmp.
 */
/** Bump when the on-disk format changes; older layouts are deleted. */
export declare const CACHE_LAYOUT = "v3";
export declare const DEFAULT_MAX_ENTRY_BYTES: number;
export declare const DEFAULT_MAX_TOTAL_BYTES: number;
export interface CachedResponse {
    data: unknown;
    /** When the response was fetched from the upstream API (epoch ms). */
    fetchedAt: number;
    expires: number;
}
export interface CacheStoreOptions {
    /** Directory holding the namespace directories, or null for memory only. */
    root: string | null;
    maxEntryBytes?: number;
    maxTotalBytes?: number;
}
/** One cache location, shared by every namespace (API client) in the process. */
export declare class CacheStore {
    readonly root: string | null;
    readonly maxEntryBytes: number;
    readonly maxTotalBytes: number;
    private readonly memory;
    private readonly readyDirs;
    /** Estimated bytes on disk; null until the first scan finishes. */
    private totalBytes;
    private scanStarted;
    private sweeping;
    constructor(opts: CacheStoreOptions);
    private nsDir;
    private entryPath;
    get(ns: string, key: string): Promise<CachedResponse | undefined>;
    set(ns: string, key: string, data: unknown, ttlMs: number, fetchedAt?: number): void;
    /** Delete every entry in a namespace. Synchronous so a following read can't see old data. */
    clear(ns: string): void;
    /**
     * Measure the cache and delete stale entries and orphaned temp files; when
     * `evict` is set (or the cache is over budget), also delete least recently
     * used entries until the total is under 80% of the budget.
     */
    private sweep;
    /** Resolves when any background scan or sweep has finished. */
    idle(): Promise<void>;
}
/**
 * Resolve the private cache directory (created if needed) and delete files
 * from older layouts: cache.json and per-module *.json files could contain
 * API keys in plaintext, and cache.v2.json is superseded.
 */
export declare function resolveCacheRoot(env?: NodeJS.ProcessEnv): string | null;
/** Cache for one API client. The store may be passed lazily, as a function. */
export declare class DiskCache {
    private readonly store;
    private readonly ns;
    private readonly ttlMs;
    constructor(store: CacheStore | (() => CacheStore), ns: string, ttlMs: number);
    private resolve;
    get(key: string): Promise<CachedResponse | undefined>;
    set(key: string, data: unknown, fetchedAt?: number): void;
    clear(): void;
}
//# sourceMappingURL=disk-cache.d.ts.map