import { JudgeVerdictKind } from './extraction-judge.js';
import './types.js';
import './local-llm.js';
import './model-registry.js';
import './fallback-llm.js';

/**
 * Extraction Judge Telemetry (issue #562, PR 3).
 *
 * Appends one structured event per judge verdict to the observation ledger
 * under a dedicated JSONL file. The ledger is the same directory used by
 * the turn-count observation writer
 * (`state/observation-ledger/rebuilt-observations.jsonl`) but judge events
 * live in their own file so aggregation stays cheap and schemas do not
 * collide.
 *
 * Emit path is best-effort and fail-open: a telemetry write must never
 * block an extraction run.
 */

/**
 * Observation-ledger category for judge verdict events. Callers that
 * aggregate across event kinds can filter on this constant.
 */
declare const EXTRACTION_JUDGE_VERDICT_CATEGORY = "EXTRACTION_JUDGE_VERDICT";
/**
 * Structured event written for every judge verdict (including verdicts
 * served from cache). The `version` field lets future readers upgrade the
 * schema without breaking older rows.
 */
interface JudgeVerdictEvent {
    version: 1;
    category: typeof EXTRACTION_JUDGE_VERDICT_CATEGORY;
    ts: string;
    verdictKind: JudgeVerdictKind;
    /** Short free-text reason from the judge / deterministic fallback. */
    reason: string;
    /**
     * How many times this candidate's content hash had already been deferred
     * before this verdict. 0 for the first defer, 1 for the second, etc.
     * Not applicable for non-defer kinds — emitted as 0.
     */
    deferrals: number;
    /**
     * Milliseconds between batch start and batch return (the whole
     * `judgeFactDurability` call, shared across all verdicts in a single
     * batch).
     */
    elapsedMs: number;
    /** Candidate metadata for coarse filtering. */
    candidateCategory: string;
    confidence?: number;
    /** SHA-256 of the (text\0category) pair, same as the verdict-cache key. */
    contentHash: string;
    /** Whether the verdict came from the in-memory verdict cache. */
    fromCache: boolean;
    /**
     * True when the judge forcibly converted a defer to reject because the
     * defer cap was reached. Only set on cap-triggered rejects.
     */
    deferCapTriggered?: boolean;
}
/**
 * Options to control emit behavior. `enabled` gates all writes; when
 * false, `recordJudgeVerdict` is a no-op so callers can unconditionally
 * invoke it.
 */
interface JudgeTelemetryOptions {
    enabled: boolean;
    memoryDir: string;
}
declare function judgeTelemetryPath(memoryDir: string): string;
/**
 * Append a single verdict event as a JSONL row. Fails open — if the write
 * cannot be completed (directory missing, permissions, disk full), the
 * error is logged at debug level and swallowed so extraction never fails
 * because of telemetry.
 */
declare function recordJudgeVerdict(event: JudgeVerdictEvent, options: JudgeTelemetryOptions): Promise<void>;
/**
 * Aggregate statistics over the verdict ledger, optionally restricted to a
 * time window. Returns zero-count stats when the ledger is missing or
 * empty — callers do not need to special-case a cold install.
 */
interface JudgeVerdictStats {
    total: number;
    accept: number;
    reject: number;
    defer: number;
    deferCapTriggered: number;
    /** Mean elapsed milliseconds across all events in the window. */
    meanElapsedMs: number;
    /** Defer rate as `defer / total`, in `[0, 1]`. `0` when total is 0. */
    deferRate: number;
    /** First and last event timestamps observed in the window. */
    firstTs?: string;
    lastTs?: string;
    /** Number of rows skipped because they were malformed or wrong shape. */
    malformed: number;
}
/**
 * Read and aggregate events from the verdict ledger.
 *
 * `sinceMs` / `untilMs` bound by `ts` parse — events with unparseable
 * timestamps are counted toward `malformed`. The upper bound is exclusive
 * (`ts < untilMs`), per CLAUDE.md gotcha 35.
 */
declare function readJudgeVerdictStats(memoryDir: string, opts?: {
    sinceMs?: number;
    untilMs?: number;
}): Promise<JudgeVerdictStats>;

export { EXTRACTION_JUDGE_VERDICT_CATEGORY, type JudgeTelemetryOptions, type JudgeVerdictEvent, type JudgeVerdictStats, judgeTelemetryPath, readJudgeVerdictStats, recordJudgeVerdict };
