/**
 * `ailf.job` document domain types.
 *
 * An `ailf.job` is a Content Lake document that records an asynchronous
 * job. The API gateway creates one when work is dispatched and updates its
 * status; callers read it back via `GET /v1/jobs/{jobId}`. Content Lake is
 * the system of record.
 *
 * The contract is a discriminated union on `kind`:
 *   - `"pipeline"` — an evaluation run dispatched to an execution backend
 *     (the original, and historically only, job variant).
 *   - `"ask"` — a Framework Q&A question handled by the question-answering
 *     flow (see docs/design-docs/framework-qa-agent-endpoint.md). Carries
 *     the question, the resolved retrieval `context` slice, and the answer.
 *
 * Authored independently of the Zod schema in
 * `packages/api/src/routes/jobs.ts`, which asserts
 * `satisfies z.ZodType<Job>` against this type so schema/type drift becomes
 * a build error rather than a silent runtime regression (D0045 / W0187).
 *
 * **Additive invariant.** Every `ailf.job` document written before `kind`
 * existed carries no discriminant. Readers MUST treat a missing `kind` as
 * `"pipeline"` (the boundary schema normalizes it). Writers are NOT
 * backfilled — the existing pipeline-job write path is untouched.
 */
/** Lifecycle states a job moves through. Terminal: completed/failed/timed-out. */
export type JobStatus = "completed" | "failed" | "queued" | "received" | "running" | "timed-out";
/**
 * Pipeline progress, stored under the Sanity field names. The public API
 * remaps these to `{ step, current, total }` (see `jobs.ts`).
 */
export interface JobProgress {
    completedSteps?: number;
    currentStep?: string;
    totalSteps?: number;
}
/** Backend execution handle, populated once a job is dispatched. */
export interface JobExecution {
    backend?: string;
    runId?: string | null;
    runUrl?: string | null;
}
/** Terminal-state error detail. */
export interface JobError {
    message: string;
    step?: string;
}
/** Webhook callback target carried from the originating request. */
export interface JobCallback {
    headers?: Record<string, string>;
    url: string;
}
/** Fields shared by every `ailf.job` variant, independent of `kind`. */
export interface JobBase {
    apiKeyPrefix?: string;
    callback?: JobCallback | null;
    completedAt?: string | null;
    createdAt: string;
    deadlineAt?: string | null;
    error?: JobError | null;
    execution?: JobExecution | null;
    jobId: string;
    startedAt?: string | null;
    status: JobStatus;
}
/**
 * An evaluation-pipeline job dispatched to an execution backend. This is
 * the original variant; documents predating `kind` parse as this shape.
 */
export interface PipelineJob extends JobBase {
    config?: Record<string, unknown>;
    kind: "pipeline";
    progress?: JobProgress | null;
    reportId?: string | null;
}
/**
 * One retrieved context entry injected into an `ask` job's prompt.
 *
 * Deliberately minimal. Tier 0 leaves `context` empty; the rich
 * retrieval-result shape is owned by the `concepts.json`-first retrieval
 * milestone (`W-concepts-first-retrieval`), which may extend this entry.
 */
export interface AskJobContextEntry {
    /** Concept slug from `docs/concepts.json`, when matched via a concept. */
    concept?: string;
    /** Authoritative repo-relative file paths for this entry. */
    files?: string[];
    /** Why this entry was retrieved (free-text, optional). */
    reason?: string;
}
/**
 * A Framework Q&A question job.
 *
 * Carries the user's `question`, the resolved `context` slice that gets
 * injected into the agent prompt (empty for Tier 0), and the final
 * `answer` (present once `status` is `"completed"`). Corpus provenance
 * (corpus SHA / built-at, per D0068) is a Tier-1 concern and, if needed,
 * is added later as an additive sibling field rather than nesting here.
 */
export interface AskJob extends JobBase {
    answer?: string;
    context?: AskJobContextEntry[];
    kind: "ask";
    question: string;
}
/** The `ailf.job` contract — a discriminated union on `kind`. */
export type Job = AskJob | PipelineJob;
