import type { ModelConfig, Usage } from "./contracts-core.js";
/**
 * Prompt-cache telemetry surface (0.1.7, plan 019 Task 2).
 *
 * Dependency-free aggregator hosts attach to their `usage` `ProviderEvent`
 * stream (or run-ledger usage records) to get per-provider/model cache
 * statistics for tuning the `cache_aware` input layout. Explicit activation:
 * nothing subscribes by import — the host calls `record()`.
 */
/** Single provider/model statistics sample. */
export interface CacheTelemetrySample {
    readonly provider: string;
    readonly model: string;
    readonly requests: number;
    readonly cacheReadTokens: number;
    readonly cacheWriteTokens: number;
    readonly inputTokens: number;
    /** Cached-input ratio across the sample (`cacheHitRate` math, aggregated). */
    readonly hitRate?: number;
    /** Estimated read-token savings via `cacheSavings` math; present only when
     *  the sample's model carries cost metadata (`ModelCost.input`/`cacheRead`). */
    readonly estimatedSavings?: number;
    readonly currency?: string;
}
/** Aggregated report. Samples are sorted by provider then model. */
export interface CacheTelemetryReport {
    readonly samples: readonly CacheTelemetrySample[];
    readonly overflowed: boolean;
    readonly totalRequests: number;
    readonly totalCacheReadTokens: number;
    readonly totalCacheWriteTokens: number;
}
export interface CacheTelemetryOptions {
    /** Distinct provider/model keys before excess keys collapse into the
     *  `__overflow__` bucket. Default {@link DEFAULT_CACHE_TELEMETRY_CAP}. */
    readonly maxKeys?: number;
}
export interface CacheTelemetry {
    /** Aggregate one usage record attributed to `model` (or an unknown bucket
     *  when no model is supplied). Rejects non-finite/negative token counts
     *  with {@link CacheTelemetryError}; validates before mutating. */
    record(usage: Usage, model?: ModelConfig): void;
    /** Snapshot of all samples (O(keys)); never throws. */
    report(): CacheTelemetryReport;
    /** Clear all samples (host rotation / long-run reset). */
    reset(): void;
    /** Number of distinct provider/model keys held (excluding the overflow bucket). */
    readonly size: number;
}
/** Cardinality ceiling: keys beyond this collapse into `__overflow__`. */
export declare const DEFAULT_CACHE_TELEMETRY_CAP = 256;
/** Sample bucket key for provider/model keys beyond the cap. */
export declare const CACHE_TELEMETRY_OVERFLOW_KEY = "__overflow__";
export declare class CacheTelemetryError extends Error {
    readonly code = "ERR_PRISM_CACHE_TELEMETRY";
    constructor(message: string);
}
export declare function createCacheTelemetry(options?: CacheTelemetryOptions): CacheTelemetry;