/** Provider-neutral async batch-jobs contract (plan 061 Task 7).
 *
 * Standalone contract — deliberately not coupled to the orchestration saga seam
 * in v1 (plan decision). Job ids are opaque strings; request payloads are
 * provider-native `JsonObject` bodies and inherit the provider's request caps;
 * polling is a plain exported utility (`pollBatch`), never loop-integrated into
 * core.
 */
import type { JsonObject, ModelCapabilities, ModelConfig } from "./content.js";
/** Neutral job state union. Adapters map provider states onto these:
 *  `queued` (submitted, not yet running), `cancelling`, and the three terminal
 *  states `completed` / `failed` / `cancelled` / `expired`. */
export type BatchJobState = "queued" | "running" | "cancelling" | "completed" | "failed" | "cancelled" | "expired";
export declare const BATCH_TERMINAL_STATES: readonly BatchJobState[];
export declare function isBatchJobTerminal(job: Pick<BatchJob, "state">): boolean;
export type BatchJobsErrorCode = "empty_requests" | "too_many_requests" | "unsupported_model" | "job_not_found" | "invalid_cursor" | "request_failed" | "response_malformed" | "unsupported_operation" | "job_failed" | "job_cancelled" | "job_expired";
export declare class BatchJobsError extends Error {
    readonly code: BatchJobsErrorCode;
    constructor(code: BatchJobsErrorCode, message: string);
}
export declare function modelSupportsBatchJobs(capabilities?: ModelCapabilities): boolean;
export declare function assertBatchJobsSupported(model: ModelConfig): void;
/** One batched request: provider-native body plus an optional caller-assigned
 *  correlation id echoed on results. Bodies are opaque to the contract. */
export interface BatchRequestItem {
    readonly customId?: string;
    readonly body: JsonObject;
}
export interface BatchSubmitRequest {
    readonly model: string;
    readonly requests: readonly BatchRequestItem[];
    /** Provider-native routing metadata (weights, priorities) — opaque passthrough. */
    readonly metadata?: JsonObject;
    readonly signal?: AbortSignal;
}
export interface BatchJob {
    /** Opaque provider job id — contract never parses or scopes it. */
    readonly id: string;
    readonly state: BatchJobState;
    readonly requestCounts?: {
        readonly total: number;
        readonly completed: number;
        readonly failed: number;
    };
    readonly createdAt?: string;
    readonly completedAt?: string;
    readonly expiresAt?: string;
    /** Provider-native job fields, unmodified, for host-side audits. */
    readonly raw?: JsonObject;
    /** Terminal failure detail when `state` is `failed`. */
    readonly error?: {
        readonly code?: string;
        readonly message?: string;
    };
}
export interface BatchResultItem {
    readonly customId: string;
    /** Provider-native per-request response (status + payload), when it succeeded. */
    readonly response?: JsonObject;
    /** Per-request failure detail (the job itself may still be `completed`). */
    readonly error?: {
        readonly code?: string;
        readonly message?: string;
    };
    /** Provider-native raw line for audits. */
    readonly raw?: JsonObject;
}
export interface BatchResultsPage {
    readonly job?: BatchJob;
    readonly items: readonly BatchResultItem[];
    /** Opaque continuation token; `null`/`undefined` when the page is last. */
    readonly nextCursor?: string | null;
}
export interface BatchResultsOptions {
    readonly cursor?: string | null;
    readonly pageSize?: number;
    readonly signal?: AbortSignal;
}
export interface BatchJobsProvider {
    readonly id: string;
    submit(request: BatchSubmitRequest): Promise<BatchJob>;
    status(jobId: string): Promise<BatchJob>;
    cancel(jobId: string): Promise<BatchJob>;
    results(jobId: string, options?: BatchResultsOptions): Promise<BatchResultsPage>;
}
export interface PollBatchOptions {
    readonly intervalMs?: number;
    /** Backoff multiplier applied per poll; caps at `maxIntervalMs`. */
    readonly backoffMultiplier?: number;
    readonly maxIntervalMs?: number;
    readonly maxAttempts?: number;
    readonly signal?: AbortSignal;
}
/** Poll a job until it reaches a terminal state. Plain utility — core never
 *  calls it. Terminal failure states surface typed `BatchJobsError`s
 *  (`job_failed` / `job_cancelled` / `job_expired`); only `completed` resolves. */
export declare function pollBatch(provider: BatchJobsProvider, jobId: string, options?: PollBatchOptions): Promise<BatchJob>;