import { type ExternalTemplateCacheMetadata } from './template-source-cache-markers.js';
export { EXTERNAL_TEMPLATE_CACHE_DIR_ENV, EXTERNAL_TEMPLATE_CACHE_ENV, EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV, EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, } from './template-source-cache-policy.js';
/**
 * Describes a deterministic external template cache entry.
 *
 * `namespace` scopes independent cache families, `keyParts` identify the exact
 * source/integrity tuple, and `metadata` is persisted to the marker file.
 */
export interface ExternalTemplateCacheDescriptor {
    /**
     * Ordered values that deterministically identify one cached template source.
     */
    keyParts: readonly string[];
    /**
     * Diagnostic values persisted to the cache marker after sanitization.
     */
    metadata: ExternalTemplateCacheMetadata;
    /**
     * Cache family scope, stored as a single safe directory segment.
     */
    namespace: string;
}
/**
 * Result returned when a cache entry is reused or populated.
 */
export interface ExternalTemplateCacheResolution {
    /**
     * Whether the returned source directory came from an existing cache entry.
     */
    cacheHit: boolean;
    /**
     * Populated or reused template source directory.
     */
    sourceDir: string;
}
/**
 * Metadata-only lookup descriptor for finding an existing reusable cache entry.
 */
export interface ExternalTemplateCacheLookupDescriptor {
    /**
     * Metadata fields that must match the sanitized marker metadata.
     */
    metadata: ExternalTemplateCacheMetadata;
    /**
     * Cache family scope, stored as a single safe directory segment.
     */
    namespace: string;
}
/**
 * Options for best-effort external template cache pruning.
 */
export interface ExternalTemplateCachePruneOptions {
    /**
     * Environment object to inspect, defaulting to `process.env`.
     */
    env?: NodeJS.ProcessEnv;
    /**
     * Force a full prune scan even when the last-pruned marker is still fresh.
     */
    force?: boolean;
    /**
     * Clock override for deterministic tests.
     */
    now?: Date | number;
    /**
     * Minimum interval between full prune scans. Omit for the environment/default.
     */
    pruneIntervalMs?: number;
    /**
     * TTL override in days. When omitted, the TTL environment variable is used.
     */
    ttlDays?: number;
}
/**
 * Summary returned after external template cache pruning.
 */
export interface ExternalTemplateCachePruneResult {
    /**
     * Absolute cache root inspected by the pruning helper.
     */
    cacheRoot: string;
    /**
     * Entries removed because their marker timestamp exceeded the TTL.
     */
    prunedEntries: number;
    /**
     * Candidate cache entry directories inspected.
     */
    scannedEntries: number;
    /**
     * Candidate directories skipped because they were malformed or unsafe.
     */
    skippedEntries: number;
    /**
     * Whether a recent last-pruned marker skipped the full cache directory scan.
     */
    skippedByThrottle: boolean;
    /**
     * Resolved TTL in milliseconds, or `null` when pruning was disabled.
     */
    ttlMs: number | null;
}
/**
 * Creates a deterministic cache key from source identity and integrity parts.
 *
 * @param keyParts Ordered values that identify one cached template source.
 * @returns SHA-256 hex digest of the JSON-serialized key parts.
 */
export declare function createExternalTemplateCacheKey(keyParts: readonly string[]): string;
/**
 * Removes stale external template cache entries when a positive TTL is configured.
 *
 * The helper is best-effort: malformed cache directories are skipped, cache
 * roots must remain private and non-symlinked, and deletes are constrained to
 * deterministic entry directories under the configured cache root.
 *
 * @param options Optional TTL, clock, and environment overrides.
 * @returns Pruning summary with counts for inspected, skipped, and removed entries.
 */
export declare function pruneExternalTemplateCache(options?: ExternalTemplateCachePruneOptions): Promise<ExternalTemplateCachePruneResult>;
/**
 * Finds a reusable cache entry whose marker metadata includes the expected fields.
 *
 * This lookup is intended for resilient fallbacks where a caller cannot compute
 * the exact deterministic key but can safely reuse a previously validated local
 * cache entry for the same source identity.
 *
 * @param descriptor Cache namespace and marker metadata fields to match.
 * @returns Existing cache resolution details, or `null` when no safe entry exists.
 */
export declare function findReusableExternalTemplateSourceCache(descriptor: ExternalTemplateCacheLookupDescriptor): Promise<ExternalTemplateCacheResolution | null>;
/**
 * Resolves or populates a cached external template source directory.
 *
 * Returns `null` when caching is disabled. Cache misses populate a temporary
 * directory first and then atomically move it into place; concurrent writers
 * that lose the race reuse the completed marker/source pair.
 *
 * @param descriptor Namespace, key parts, and metadata for the cache entry.
 * @param populateSourceDir Callback that writes the guarded source on a miss.
 * @returns Cache resolution details, or `null` when caching is disabled.
 */
export declare function resolveExternalTemplateSourceCache(descriptor: ExternalTemplateCacheDescriptor, populateSourceDir: (sourceDir: string) => Promise<void>): Promise<ExternalTemplateCacheResolution | null>;