/**
 * Liveness canaries — cheap statistical checks that catch the failure
 * modes a green test suite never sees.
 *
 * Three canary types in this module:
 *
 *   1. **Silent judge fallback** — the judge degraded to a fallback
 *      path (rules-only / cached / heuristic) without anyone
 *      noticing. Signature: a string of consecutive runs whose
 *      `judgeMetadata.confidence` equals a known fallback constant
 *      (default 0.30) OR whose `judgeMetadata.fallback` is true.
 *
 *   2. **Judge calibration drift** — the judge's confidence
 *      distribution has drifted from a historical window. Two-sample
 *      Kolmogorov-Smirnov test on the recent vs historical confidences,
 *      with the empirical-CDF max-difference statistic.
 *
 *   3. **Eval-set distribution shift** — the mix of categories /
 *      buckets in the recent runs differs significantly from the
 *      historical mix. Chi-square test on the binned counts.
 *
 * Outputs are alerts. The canary does NOT fail loud the way a test
 * does — failing tests are reserved for hard correctness violations.
 * A canary that fires is a *signal* to investigate, not a verdict.
 *
 * Why this lives here rather than in `observability.ts`: that module
 * exports already, and is a pure-fanout-to-Langfuse/Prometheus
 * adapter. Canaries are statistical detectors, not adapters.
 */
import type { RunRecord } from './run-record';
export type CanaryKind = 'silent_judge_fallback' | 'judge_calibration_drift' | 'distribution_shift';
export type CanarySeverity = 'info' | 'warn' | 'error';
export interface CanaryAlert {
    kind: CanaryKind;
    severity: CanarySeverity;
    message: string;
    /** Numbers that informed the decision — drop straight into a
     *  dashboard / paper figure. */
    evidence: Record<string, unknown>;
}
export interface CanaryReport {
    alerts: CanaryAlert[];
    /** Per-kind summary count. */
    counts: Record<CanaryKind, number>;
}
export interface CanaryOptions {
    /**
     * Silent-fallback detection.
     * - `constant`: confidence value treated as the fallback signal.
     *   Default 0.30 (matches the soft-fail default in
     *   `propose-review.ts`).
     * - `consecutiveThreshold`: trip the alert after this many
     *   consecutive runs at `constant` (or `fallback === true`).
     *   Default 3.
     */
    silentFallback?: {
        constant?: number;
        consecutiveThreshold?: number;
        /** Floating-point tolerance when comparing against `constant`. */
        epsilon?: number;
    };
    /**
     * Calibration-drift detection.
     * - `historyWindow`: number of past runs (oldest-first) treated as
     *   the historical baseline. Default 50.
     * - `recentWindow`: number of recent runs (newest-first) compared
     *   against history. Default 20.
     * - `ksAlpha`: alpha for the KS statistic vs critical value.
     *   Default 0.05.
     * - `minRecent`: minimum recent runs required to even attempt the
     *   check. Default 10.
     */
    calibrationDrift?: {
        historyWindow?: number;
        recentWindow?: number;
        ksAlpha?: number;
        minRecent?: number;
    };
    /**
     * Distribution-shift detection.
     * - `category`: function that maps a run to a categorical bucket.
     *   Required to enable this canary; if omitted the chi-square check
     *   is skipped entirely.
     * - `chiSquareAlpha`: alpha. Default 0.05.
     * - `historyWindow`, `recentWindow`, `minRecent`: like above.
     */
    distributionShift?: {
        category: (run: RunRecord) => string | null;
        chiSquareAlpha?: number;
        historyWindow?: number;
        recentWindow?: number;
        minRecent?: number;
    };
}
/**
 * Run all configured canaries against a chronological run list.
 * Runs MUST be sorted oldest-to-newest by the caller — the order of
 * the input is used to define "recent" vs "historical" windows.
 */
export declare function runCanaries(runs: RunRecord[], opts?: CanaryOptions): CanaryReport;
//# sourceMappingURL=canary.d.ts.map