/**
 * ModeHandler — the common interface every evaluation mode implements.
 *
 * The pipeline dispatches to mode handlers through the PluginRegistry:
 *   1. Look up the mode: `ctx.registry.getMode(mode)`
 *   2. Import the handler module: `import(registration.handlerModule)`
 *   3. Call: `module.handler.compileTask(task, ctx)`
 *
 * Each handler file exports a `handler` object conforming to this interface.
 * The handler narrows the GeneralizedTaskDefinition to its mode-specific
 * variant and produces a ModeCompileResult.
 *
 * Types here are minimal structural contracts — the eval package's Promptfoo
 * types satisfy them via TypeScript structural compatibility.
 *
 * @see docs/design-docs/architecture-overhaul/extensibility-plugins.md
 * @see packages/eval/src/pipeline/compiler/mode-handlers/
 */
import type { GeneralizedTaskDefinition } from "../types/generalized-task.js";
import type { PreflightRubricContext } from "../types/preflight-scoring.js";
/**
 * A prompt template owned by a mode handler.
 *
 * Mode handlers can return these via `getPrompts()` to override the global
 * config/prompts.ts templates. This lets non-literacy modes define their
 * own prompt structures without polluting the global config.
 */
export interface PromptTemplate {
    /** Unique identifier (e.g. "with-docs", "agentic") */
    id: string;
    /** Human-readable label for display */
    label: string;
    /** The prompt template string with {{variable}} placeholders */
    template: string;
    /** Variable names used by this template — for documentation only */
    variables?: string[];
}
/** Compilation context — shared state the pipeline provides to every handler */
export interface CompilationContext {
    /** Eval package root directory (for resolving file paths) */
    rootDir: string;
    /** Grader provider ID for LLM-graded assertions */
    graderProvider?: string;
    /** Model providers to include in the evaluation */
    models?: ModeProviderEntry[];
    /** Rubric config (templates, weights) — loaded from config/rubrics */
    rubricConfig?: ModeRubricConfig;
    /**
     * Grader context policy.
     *
     * - `"rubric-only"`: the grader sees only the rubric template + criteria +
     *   the candidate's response.
     * - `"with-docs"`: the canonical reference content for the task is injected
     *   into the assertion's `rubricPrompt` so the grader has authoritative
     *   ground truth alongside the rubric.
     *
     * Mode handlers without canonical doc context (agent-harness, knowledge-probe)
     * ignore this field — the `canonicalReference` parameter on
     * `resolveTemplatedAssertion` is optional, so unset means current behavior.
     */
    graderContext?: "rubric-only" | "with-docs";
    /**
     * W0198 Phase 6 — when supplied, mode handlers prefix the
     * `code-correctness` rubric with a "DETERMINISTIC PREFLIGHT" system
     * instruction telling the grader to treat the preflight's existence
     * findings as ground truth. Sourced upstream from the package-surface
     * manifest; absence collapses cleanly to the pre-W0198 rubric.
     */
    preflightContext?: PreflightRubricContext;
}
/** A model provider entry for compilation */
export interface ModeProviderEntry {
    id: string;
    label: string;
    config?: Record<string, unknown>;
}
/** Minimal rubric config needed by mode handlers */
export interface ModeRubricConfig {
    templates: Record<string, {
        dimension?: string;
        header: string;
        scale: string[];
        criteria_label?: string;
        /**
         * Plan 03-02 — per-dimension legal failure-mode list. The runtime
         * rubric assembler announces these modes to the grader before the
         * structured-shape footer when the list is non-empty. Stamped at
         * config-load time by `failureModesForDimension(dimension)` in
         * `packages/eval/src/grader/index.ts`.
         */
        failureModes?: readonly string[];
    }>;
    /**
     * Plan 03-01 — formerly hard-coded literal in
     * `pipeline/compiler/rubric-resolution.ts`; now sourced from
     * RubricConfig.footer and threaded through to the runtime prompt
     * assembler so the grader is told exactly what wire format to emit.
     */
    footer: string;
}
/** A provider entry in the compile result */
export interface CompileResultProvider {
    id: string;
    label?: string;
    config?: Record<string, unknown>;
}
/** A prompt entry in the compile result */
export interface CompileResultPrompt {
    id: string;
    label: string;
    raw: string;
}
/** A test case entry in the compile result */
export interface CompileResultTestCase {
    description: string;
    vars: Record<string, unknown>;
    assert?: CompileResultAssertion[];
    prompts?: string[];
}
/** An assertion entry in a test case */
export interface CompileResultAssertion {
    type: string;
    value?: unknown;
    provider?: string;
    /**
     * Structured metadata. Carries the rubric `dimension` and the
     * `scoring: false` marker the compiler sets on diagnostic-only assertions
     * (e.g. URL extraction) so they stay out of `assertion-pass-rate` (D0083).
     */
    metadata?: Record<string, unknown>;
}
/**
 * ModeCompileResult — the common output every mode handler produces.
 *
 * All four fields (providers, tests, prompts, warnings) are present in
 * every handler's result type. Mode-specific extras (sandbox config,
 * metadata, extensions) go in the `extras` bag.
 */
export interface ModeCompileResult {
    /** Provider configurations for Promptfoo */
    providers: CompileResultProvider[];
    /** Compiled test cases */
    tests: CompileResultTestCase[];
    /** Prompt templates */
    prompts: CompileResultPrompt[];
    /** Warnings generated during compilation */
    warnings: string[];
    /** Mode-specific extras (extensions, sandboxConfig, metadata, etc.) */
    extras?: Record<string, unknown>;
}
/**
 * ModeHandler — the interface every evaluation mode handler exports.
 *
 * Handler modules are referenced by `ModeRegistration.handlerModule` in the
 * plugin registry. The pipeline imports the module and calls `handler.compileTask()`.
 *
 * Each handler file should export:
 *   export const handler: ModeHandler = { ... }
 */
export interface ModeHandler {
    /** Compile a task definition into evaluation configuration */
    compileTask(task: GeneralizedTaskDefinition, ctx: CompilationContext): ModeCompileResult;
    /**
     * Return prompt templates owned by this mode.
     *
     * When defined, the compiler uses these instead of global config/prompts.ts.
     * Keys are prompt IDs (e.g. "with-docs", "agentic"). Returning undefined
     * or omitting the method falls back to global prompts.
     */
    getPrompts?(): Record<string, PromptTemplate>;
}
