/**
 * pipeline/extract-grader-judgments-resilient.ts
 *
 * Resilient grader-judgment extraction for the `calculate-scores` persist
 * junction.
 *
 * Background: `calculateAndWriteScores` extracts grader judgments from the
 * eval results file(s), then writes `grader-judgments.json` only when the
 * array is non-empty (the `judgments.length > 0` guard). A runtime anomaly was
 * observed where `extractGraderJudgments` returned 0 judgments for a results
 * file that demonstrably contained classifiable llm-rubric components — the
 * same file, read tens of milliseconds later by `extractStoredTestResults`,
 * yielded the full set (entries with populated dimensions). The empty array
 * silently skipped the write, so gap-analysis and compute-attribution skipped
 * and the report shipped with a score but no tests.
 *
 * The committed code reads the file via a pure `readFileSync` with identical
 * classification on both sides, so the divergence is not reproducible from the
 * source + captured artifacts — it is a transient read anomaly at the live
 * junction. This wrapper does not pretend to know the mechanism; it makes the
 * junction observable and recovers from the transient:
 *
 *  1. **Instruments** — logs the resolved path(s), file size/mtime, parsed
 *     result count, and judgment count on every run (never silent on 0), so a
 *     future empty-judgments persist is diagnosable from the run log alone.
 *  2. **Self-heals** — when extraction yields 0 judgments but a results file
 *     exists, it re-extracts with bounded retries. A later read that yields
 *     judgments proves the initial 0 was transient; the recovered judgments
 *     are returned. If every attempt yields 0, severity is decided by an
 *     independent classifiable-component count: a genuinely judgment-free run
 *     (all api-errors / no llm-rubric) logs a warning, while 0 judgments
 *     against present classifiable components logs an error (the downstream
 *     gap-analysis fail-loud guard is the backstop).
 *
 * The extractor and fs helpers are injected so the wrapper is unit-testable
 * without importing the ~3000-line scoring module (which would be circular)
 * or touching the real filesystem.
 */
import type { GraderJudgment, GraderReliability, Logger } from "../_vendor/ailf-core/index.d.ts";
/** Telemetry sink threaded into each extraction (shared reliability counters). */
export interface ExtractionTelemetry {
    reliability: GraderReliability;
    runId?: string;
}
/** Cheap on-disk stat used for diagnostics and the retry gate. */
export interface FileStat {
    exists: boolean;
    mtimeMs: number;
    size: number;
}
/** Injectable seams — defaults wire the real fs; tests substitute fakes. */
export interface ResilientExtractionDeps {
    /**
     * The real `extractGraderJudgments`. Injected (rather than imported) to
     * avoid a circular dependency with `calculate-scores.ts`.
     */
    extract: (path: string, telemetry?: ExtractionTelemetry) => GraderJudgment[];
    /** Parsed result-entry count for a path — diagnostics only. */
    countResults?: (path: string) => number;
    /**
     * Count of classifiable llm-rubric components for a path. Used only to set
     * the severity of a persistent-empty extraction: a file with classifiable
     * components but 0 extracted judgments is an error; a file with none (all
     * api-errors / no llm-rubric) is a benign empty.
     */
    countClassifiable?: (path: string) => number;
    /** On-disk stat (existence + size + mtime). */
    statFile?: (path: string) => FileStat;
    /** Backoff between self-heal attempts. */
    sleep?: (ms: number) => Promise<void>;
}
export interface ResilientExtractionOptions {
    /** Total extraction attempts when the first yields 0 (default 3, min 1). */
    maxAttempts?: number;
    /** Delay before each retry, in ms (default 200). */
    delayMs?: number;
    deps: ResilientExtractionDeps;
}
/**
 * Extract grader judgments across one or more results files, instrumented and
 * self-healing. See the module header for the rationale.
 *
 * @param resultsPaths  One or more results files (e.g. baseline + agentic in
 *   literacy full mode). Missing paths are skipped.
 * @param telemetry  Shared reliability sink threaded into every extraction.
 * @param log  Pipeline logger — the junction is logged here on every run.
 */
export declare function extractGraderJudgmentsResilient(resultsPaths: readonly string[], telemetry: ExtractionTelemetry | undefined, log: Logger, options: ResilientExtractionOptions): Promise<GraderJudgment[]>;
