/**
 * webhook/eval-request-handler.ts
 *
 * Server-side handler for `ailf.evalRequest` documents from the Sanity
 * Content Lake. This is the counterpart to the Studio's "Request Evaluation"
 * and "Run Task Eval" actions — when a content editor creates an eval
 * request document via the Studio UI, a Sanity webhook fires and calls
 * this handler.
 *
 * Designed to run in any HTTP environment: Cloudflare Workers, Vercel
 * functions, Express, Hono, etc.
 *
 * The eval-request document carries a canonical `PipelineRequest` JSON
 * blob in its `pipelineRequest` field (see W0239). The handler parses it
 * via `PipelineRequestSchema` from `@sanity/ailf-core` and forwards it
 * to the dispatcher as-is. Scoping (release-scoped via `perspective`,
 * task-scoped via `tasks`) is asserted on the parsed `PipelineRequest`
 * — at least one must be present.
 *
 * Flow:
 * 1. Receive eval request payload (from Sanity webhook projection)
 * 2. Validate envelope: must be `ailf.evalRequest` type, `pending` status,
 *    `pipelineRequest` present
 * 3. Parse + Zod-validate `pipelineRequest` against `PipelineRequestSchema`
 * 4. Assert scoping: parsed request must have `perspective` or `tasks`
 * 5. Dispatch evaluation to GitHub Actions via `repository_dispatch`
 *    with `external-eval` event type — the parsed `PipelineRequest`
 *    rides as `client_payload.request` unchanged
 * 6. On success: PATCH the eval request document → `status: "dispatched"`
 * 7. On failure: PATCH the eval request document → `status: "failed"` + error
 * 8. Return a structured result
 *
 * ## Sanity Manage Webhook Configuration
 *
 * The Sanity webhook projection MUST include all fields consumed by
 * EvalRequestPayload. The recommended projection is `{...}` (spread),
 * which passes the entire document and avoids silently dropping fields
 * when the schema evolves.
 *
 * Recommended projection:
 * ```
 * {...}
 * ```
 *
 * @see packages/api/src/routes/webhooks.ts — API gateway webhook handler
 * @see packages/studio/src/actions/RunEvaluationAction.tsx — release eval
 * @see packages/studio/src/actions/RunTaskEvaluationAction.tsx — task eval
 * @see .github/workflows/external-eval.yml — receiving workflow
 * @see docs/design-docs/report-store/visibility-workflows.md
 */
/**
 * Projected shape of an `ailf.evalRequest` document from a Sanity webhook.
 *
 * Per the W0239 schema redesign, request-scope fields (mode, perspective,
 * tasks, areas, debug, tag, etc.) ride inside the `pipelineRequest` JSON
 * blob — the canonical `PipelineRequest` serialization. The handler parses
 * it via `PipelineRequestSchema` from `@sanity/ailf-core` and forwards it
 * to the dispatcher as-is.
 */
export interface EvalRequestPayload {
    /** The Sanity document _id */
    _id: string;
    /** The Sanity document _type (should be "ailf.evalRequest") */
    _type: string;
    /** Sanity dataset hosting the eval-request document itself */
    dataset: string;
    /** Error message (only if status is "failed") */
    error?: string;
    /**
     * Canonical `PipelineRequest` JSON. Source of truth for the dispatch
     * payload. Parses against `PipelineRequestSchema` from `@sanity/ailf-core`.
     */
    pipelineRequest: string;
    /** Sanity project ID hosting the eval-request document itself */
    projectId: string;
    /** ISO datetime of when the request was created */
    requestedAt: string;
    /** User ID who requested */
    requestedBy?: string;
    /** Request status */
    status: string;
}
/** Configuration for the eval request handler. */
export interface EvalRequestHandlerConfig {
    /** GitHub PAT with repo or actions:write scope */
    githubToken: string;
    /** Target AILF repo (default: "sanity-labs/ai-literacy-framework") */
    githubRepo?: string;
    /** Sanity API token for updating the eval request document status */
    sanityToken: string;
}
/** Result of handling an eval request. */
export interface EvalRequestResult {
    /** Whether the dispatch succeeded */
    ok: boolean;
    /** The eval request document ID */
    requestId: string;
    /** Error message on failure */
    error?: string;
}
/**
 * Handle an incoming `ailf.evalRequest` document from a Sanity webhook.
 *
 * Validates the payload, dispatches a GitHub Actions evaluation, and
 * updates the eval request document status in the Content Lake.
 *
 * ```ts
 * // In a Cloudflare Worker or Vercel function:
 * export default async function handler(req: Request) {
 *   const payload = await req.json()
 *   const result = await handleEvalRequest(payload, {
 *     githubToken: env.GITHUB_TOKEN,
 *     sanityToken: env.SANITY_API_TOKEN,
 *   })
 *   return Response.json(result, { status: result.ok ? 200 : 400 })
 * }
 * ```
 */
export declare function handleEvalRequest(payload: EvalRequestPayload, config: EvalRequestHandlerConfig): Promise<EvalRequestResult>;
