/**
 * pipeline/grader-validation.ts
 *
 * Pure computation module for grader validation against human reference grades.
 *
 * Takes paired (graderScore, humanScore) observations and computes:
 * - Mean Absolute Error (MAE)
 * - Pearson correlation
 * - Per-dimension breakdown
 * - Largest disagreements (for diagnosis)
 *
 * This module has NO side effects — no file I/O, no API calls.
 *
 * @see docs/archive/exec-plans/grader-reliability.md — Phase 2
 */
/** Quality label for a correlation value */
export type CorrelationQuality = "excellent" | "good" | "moderate" | "poor" | "very-poor";
/** Per-dimension validity metrics */
export interface DimensionValidity {
    /** Mean signed error (positive = grader scores higher than human) */
    bias: number;
    /** Pearson correlation coefficient (-1 to 1) */
    correlation: number;
    /** Number of observations */
    count: number;
    /** Mean Absolute Error for this dimension */
    mae: number;
}
/** A single large disagreement between grader and human */
export interface Disagreement {
    /** Absolute difference */
    absoluteError: number;
    /** Feature area */
    area: string;
    /** Scoring dimension */
    dimension: "codeCorrectness" | "docCoverage" | "taskCompletion";
    /** Grader score */
    graderScore: number;
    /** Human score */
    humanScore: number;
    /** Optional notes from the human grader */
    notes?: string;
    /** Signed difference (grader - human) */
    signedError: number;
    /** Task ID */
    taskId: string;
}
/** Top-level grader validation result */
export interface GraderValidation {
    /** When this validation was generated */
    generatedAt: string;
    /** Grader model that was validated */
    graderModel: string;
    /** Top N largest disagreements (sorted by absolute error, descending) */
    largestDisagreements: Disagreement[];
    /** The MAE threshold used */
    maeThreshold: number;
    /** Overall bias (positive = grader grades higher than humans on average) */
    overallBias: number;
    /** Overall Pearson correlation */
    overallCorrelation: number;
    /** Overall Mean Absolute Error across all dimensions */
    overallMae: number;
    /** Whether the grader passes the MAE threshold (default: MAE < 10) */
    passesThreshold: boolean;
    /** Per-dimension validity metrics (keyed by dimension name) */
    perDimension: Record<string, DimensionValidity>;
    /** Total number of (grader, human) score pairs analyzed */
    totalObservations: number;
}
/** A single human reference grade for one (response, rubric) judgment */
export interface HumanReferenceGrade {
    /** Feature area */
    area: string;
    /** Which scoring dimension */
    dimension: "codeCorrectness" | "docCoverage" | "taskCompletion";
    /** The grader's score (0–100) — populated after grading */
    graderScore: number;
    /** The human expert's score (0–100) */
    humanScore: number;
    /** Optional notes from the human grader */
    notes?: string;
    /** Which task this judgment belongs to */
    taskId: string;
}
/** Classify a correlation value into a human-readable quality label */
export declare function classifyCorrelation(r: number): CorrelationQuality;
/** Compute Pearson correlation coefficient between two arrays of equal length */
export declare function pearsonCorrelation(x: number[], y: number[]): number;
/**
 * Validate grader scores against human reference grades.
 *
 * This is the main entry point — a pure function with no side effects.
 *
 * @param grades Array of paired (grader, human) observations
 * @param graderModel The grader model identifier
 * @param options Optional configuration
 * @returns GraderValidation report
 */
export declare function validateGrader(grades: HumanReferenceGrade[], graderModel: string, options?: {
    maeThreshold?: number;
    maxDisagreements?: number;
}): GraderValidation;
