/**
 * @file Process-scoped LRU cache for `readJson` / `readJsonSync` results, keyed
 *   by absolute path + stat (`ino + size + mtimeMs`). Why default-on caching is
 *   safe:
 *
 *   - Stat-validated keys: a `stat()` call before serving a cache hit ensures the
 *     file hasn't changed (mtime + size mismatch ⇒ cache miss, re-read).
 *   - Defensive clone on hit: every hit returns `structuredClone(parsed)` so
 *     callers can mutate the returned object without poisoning the cache for
 *     the next reader. The clone cost is far less than re-read + re-parse for
 *     anything bigger than a trivial JSON document.
 *   - Reviver opt-out: when the caller passes a `reviver` function, we skip the
 *     cache. Function identity isn't safely hashable across boundaries, and the
 *     reviver can produce a different shape from the same bytes.
 *   - Per-call escape hatch: `cache: false` in the options bypasses the cache for
 *     cases where staleness must be observed (file-watcher tooling, etc.).
 *   - Bounded growth: an LRU cap (default 256 entries) protects long-running
 *     daemons. Tunable via `SOCKET_LIB_READ_JSON_CACHE_MAX` env or
 *     `setReadJsonCacheMax()`.
 *   - Test escape hatch: `clearReadJsonCache()` resets the whole cache between
 *     test cases that rely on fresh reads. Not cached:
 *   - Read failures (ENOENT under `throws: false` returns `undefined`). Caching
 *     undefined would silently miss a file that gets created later.
 *   - Reads with a `reviver` (see above).
 *   - Reads with explicit `cache: false`.
 *   - Relative paths whose `resolvePath` would change CWD-sensitively. We key on
 *     the literal input path, so callers passing relative paths from different
 *     CWDs would get separate cache entries — correct but pessimistic.
 */
import type { JsonValue } from '../json/types';
/**
 * Drop all cached entries. Tests call this between cases that depend on a fresh
 * read; long-running daemons can call it on file-watcher invalidation events
 * for paths the daemon knows are about to change in bulk.
 */
export declare function clearReadJsonCache(): void;
/**
 * Look up a cached parse result. Returns a fresh structured clone on hit (so
 * callers can mutate freely), or `undefined` on miss.
 *
 * @param key Cache key — absolute file path. Caller resolves any relative
 *   inputs to absolute so two different CWDs don't share an entry.
 * @param ino Inode (or `0` on platforms without one — Windows reports 0 from
 *   the Node `fs.Stats` shim, in which case size + mtimeMs carry the
 *   invalidation signal).
 * @param size File size in bytes.
 * @param mtimeMs Modification time in milliseconds.
 */
export declare function getCachedJson(key: string, ino: number, size: number, mtimeMs: number): JsonValue | undefined;
/**
 * Snapshot diagnostics. Useful for tests and for tooling that wants to log
 * cache effectiveness at end of run.
 */
export declare function getReadJsonCacheStats(): {
    size: number;
    max: number;
    ttlMs: number;
    hits: number;
    misses: number;
};
export declare function readMaxFromEnv(): number;
export declare function readTtlFromEnv(): number;
/**
 * Store a parsed value. Evicts the oldest entry when the cache is full.
 *
 * Never stores `undefined` — callers must guard for the "file not found,
 * throws: false" case before invoking this.
 */
export declare function setCachedJson(key: string, ino: number, size: number, mtimeMs: number, parsed: JsonValue): void;
/**
 * Adjust the cache size cap at runtime. Useful for tooling that knows it'll
 * walk many manifests in one pass and wants a larger cap, or for tests that
 * want to bound the cap small so eviction is observable.
 *
 * Trims excess entries on shrink.
 */
export declare function setReadJsonCacheMax(max: number): void;
/**
 * Adjust the time-based ejection window at runtime. Default is 5 minutes; pass
 * `0` to disable time-based ejection entirely (entries then live until LRU
 * eviction or `clearReadJsonCache`).
 */
export declare function setReadJsonCacheTtlMs(ttlMs: number): void;
