import { BufferSurpriseEvent } from './types.js';

/**
 * Buffer-surprise telemetry report (issue #563 PR 3).
 *
 * Reads the append-only `state/buffer-surprise-ledger.jsonl` file written
 * by `SmartBuffer` and summarizes the recent distribution of surprise
 * scores for the Doctor surface. This module is intentionally standalone
 * and pure — the only I/O is reading the ledger via the injected
 * `readEvents` callback, so it can be exercised directly in tests
 * without touching the filesystem.
 *
 * # Output shape
 *
 * `BufferSurpriseDistribution` has fields sized for a one-screen Doctor
 * display:
 *
 *   - `count`            — rows considered in the summary window.
 *   - `triggeredCount`   — rows whose `triggeredFlush === true`.
 *   - `triggeredRate`    — `triggeredCount / count`, or `0` when empty.
 *   - `mean`             — arithmetic mean of `surpriseScore`.
 *   - `median`           — middle value (50th percentile).
 *   - `p90`              — 90th percentile (tail of novelty).
 *   - `min`, `max`       — window extremes.
 *   - `currentThreshold` — threshold from the MOST RECENT row, or `null`.
 *
 * All percentile math uses the nearest-rank method (no interpolation) so
 * the report is stable across small windows.
 *
 * # Why a pure function + injected reader?
 *
 * The Doctor surface is exercised both at runtime (through the CLI and
 * gateway tools) and in tests. A pure distribution helper fed from an
 * arbitrary `readEvents` callback keeps the report logic trivially
 * testable without spinning up a real `StorageManager`.
 */

interface BufferSurpriseDistribution {
    count: number;
    triggeredCount: number;
    triggeredRate: number;
    mean: number;
    median: number;
    p90: number;
    min: number;
    max: number;
    currentThreshold: number | null;
}
interface BufferSurpriseReportOptions {
    /**
     * Maximum number of recent rows to include. Defaults to `200` — large
     * enough to see a distribution, small enough to read in one sitting.
     */
    limit?: number;
    /** Lower-bound ISO timestamp; rows at or before this are excluded. */
    since?: string;
}
/**
 * Reader callback shape. The helper does not want to know whether the
 * rows come from a file, a queue, or an in-memory buffer.
 */
type BufferSurpriseReader = (options: BufferSurpriseReportOptions) => Promise<readonly BufferSurpriseEvent[]>;
/**
 * Summarize the recent buffer-surprise distribution. Returns the empty
 * distribution shape when the ledger has no applicable rows — callers can
 * detect this via `count === 0` and render "no data yet".
 */
declare function reportBufferSurpriseDistribution(readEvents: BufferSurpriseReader, options?: BufferSurpriseReportOptions): Promise<BufferSurpriseDistribution>;

export { type BufferSurpriseDistribution, type BufferSurpriseReader, type BufferSurpriseReportOptions, reportBufferSurpriseDistribution };
