/**
 * API Service Gateway request envelope types.
 *
 * These types describe the HTTP request bodies the API gateway accepts on
 * its public-facing routes. They live in core (not in packages/api/src/) so
 * the gateway's Zod validators can `satisfies z.ZodType<...>` against them
 * — making the parse-output → domain-type contract a compile-time gate
 * rather than a runtime assumption (D0045 / W0187).
 *
 * The shapes here are intentionally a LOOSE subset of the canonical domain
 * types they relate to:
 *
 *   - `ValidateConfigRequest.config` overlaps with `ModelsConfig`, but the
 *     API surface accepts string[] for modes (not branded EvalMode[]) and
 *     all fields are optional. This is a deliberate gateway contract — the
 *     route's job is to validate the user's input, not to require a fully
 *     domain-shaped payload.
 *   - `ValidateTaskDef` overlaps with `GeneralizedTaskDefinition` but uses
 *     the older flat shape (`featureArea`, `canonicalDocs`) instead of the
 *     mode-discriminated union. Harmonizing these is tracked separately —
 *     out of scope for W0187.
 *
 * Any fields not on these types are rejected by the gateway's validators
 * and won't reach domain code; the satisfies clause is what pins that
 * contract in place.
 */
/**
 * POST /v1/validate/config — request envelope.
 * @see packages/api/src/schemas/validate-requests.ts
 */
export interface ValidateConfigRequest {
    config: {
        defaults?: Record<string, unknown>;
        grader?: {
            id: string;
            label?: string;
        };
        maxConcurrency?: number;
        models?: {
            config?: Record<string, unknown>;
            id: string;
            label?: string;
            modes?: string[];
        }[];
    };
}
/**
 * Canonical doc reference used inside `ValidateTaskDef.canonicalDocs`.
 * Mirrors the four shapes the API gateway accepts.
 */
export type ValidateTaskCanonicalDocRef = {
    reason?: string;
    slug: string;
} | {
    path: string;
    reason?: string;
} | {
    id: string;
    path?: string;
    reason?: string;
    slug?: string;
} | {
    perspective: string;
    reason?: string;
};
/**
 * Assertion definition accepted by the API gateway's task validator.
 * Either an `llm-rubric` shape with explicit fields, or a generic
 * type+value pair for non-LLM assertions.
 */
export type ValidateTaskAssertionDef = {
    criteria: string[];
    template: string;
    type: "llm-rubric";
    weight?: number;
} | {
    type: string;
    value?: unknown;
    weight?: number;
};
/**
 * The "task definition" shape accepted by POST /v1/validate/task.
 *
 * Distinct from `GeneralizedTaskDefinition` (the mode-discriminated
 * canonical task type): this is the older flat shape preserved at the
 * API surface. Harmonization tracked separately.
 */
export interface ValidateTaskDef {
    assertions: ValidateTaskAssertionDef[];
    baseline?: {
        enabled?: boolean;
        rubric?: "abbreviated" | "full" | "none";
    };
    canonicalDocs: ValidateTaskCanonicalDocRef[];
    description: string;
    docCoverage: boolean;
    extraVars?: Record<string, unknown>;
    featureArea: string;
    id: string;
    referenceSolution: string;
    taskPrompt: string;
}
/**
 * POST /v1/validate/task — request envelope.
 * @see packages/api/src/schemas/validate-requests.ts
 */
export interface ValidateTaskRequest {
    strict: boolean;
    tasks: ValidateTaskDef[];
}
/**
 * POST /v1/validate/source — request envelope.
 * @see packages/api/src/schemas/validate-requests.ts
 */
export interface ValidateSourceRequest {
    source: {
        baseUrl?: string;
        dataset?: string;
        projectId?: string;
        token?: string;
    };
}
/**
 * POST /v1/lookup-doc — request envelope.
 * @see packages/api/src/schemas/lookup-request.ts
 */
export interface LookupDocRequest {
    keyword: string;
    limit: number;
    source: string;
}
/**
 * Inline-score-or-report-id reference used by `CompareRequest`.
 *
 * Either:
 *   - A partial inline score summary (used by the gateway's compare()
 *     endpoint without a Content Lake round-trip), with `passthrough`
 *     extra fields preserved, or
 *   - A string report ID (the gateway fetches the corresponding
 *     `ScoreSummary` from Content Lake before comparing).
 */
export type CompareScoreSummaryRef = string | {
    [extra: string]: unknown;
    features?: Record<string, unknown>;
    overall: {
        [extra: string]: unknown;
        areaCount: number;
        avgScore: number;
    };
};
/**
 * POST /v1/compare — request envelope.
 * @see packages/api/src/schemas/compare-request.ts
 */
export interface CompareRequest {
    baseline: CompareScoreSummaryRef;
    experiment: CompareScoreSummaryRef;
    threshold: number;
}
