import type { AuditLogger } from '../ops/audit-logger.js';
import type { MetricsCollector } from '../ops/metrics.js';
import { type RateLimiter } from '../ops/rate-limiter.js';
import type { RateLimitConfig } from '../types/config.js';
import type { ContinuedCallContext, LifecycleConfig, LifecycleStage, OperationDescriptor, OperationLifecycleLike, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, ProviderGate, ProviderHealthOutcome } from '../types/lifecycle.js';
import type { CallResidency, ResidencyDecision, ResidencyPolicy } from '../types/residency.js';
/** Every lifecycle stage, in the order an operation passes through them. */
export declare const LIFECYCLE_STAGES: readonly LifecycleStage[];
/** Raised when `lifecycle.authorize` refuses an operation, before any provider is called. */
export declare class OperationDeniedError extends Error {
    /** The operation that was refused. */
    readonly operation: OperationDescriptor;
    constructor(
    /** The operation that was refused. */
    operation: OperationDescriptor, reason?: string, options?: {
        cause?: unknown;
    });
}
/** Raised when an operation's estimated cost does not fit what is left of its budget. */
export declare class BudgetExceededError extends Error {
    /** The budget, such as a tenant. */
    readonly key: string;
    /** What the operation was estimated to cost, in US dollars. */
    readonly estimate: number;
    /** What was left of the budget, in US dollars. */
    readonly remaining: number;
    constructor(
    /** The budget, such as a tenant. */
    key: string, 
    /** What the operation was estimated to cost, in US dollars. */
    estimate: number, 
    /** What was left of the budget, in US dollars. */
    remaining: number);
}
/** What a lifecycle reports into. Every field is optional; a lifecycle with none records nothing. */
export interface LifecycleRuntime {
    /** Where metrics go. */
    metrics?: MetricsCollector;
    /** Where audit events go. */
    auditLogger?: AuditLogger;
    /** The rate limiter every family shares. */
    rateLimiter?: RateLimiter;
    /** The rate-limit policy. */
    rateLimit?: RateLimitConfig;
    /** Authorization, budget, and hooks. */
    config?: LifecycleConfig;
    /** Default milliseconds an operation may run before its signal aborts. */
    timeoutMs?: number;
    /** Where `reportHealth()` goes: the client's provider health and circuit breaker. */
    providerHealth?: {
        recordSuccess(provider: string, latencyMs: number): void;
        recordFailure(provider: string, error: unknown): void;
    };
}
/** The family's part of one operation: what each stage does for it. Every stage but `execute` is optional. */
export interface OperationPlan<T> {
    /** Checks the request before anything else happens. Runs before authorization, so it must not have side effects. */
    validate?(): void | Promise<void>;
    /** Applies input guardrails: security, safety policies, trimming. */
    inputPolicy?(context: ProviderCallContext): void | Promise<void>;
    /** Loads the assets the request refers to. */
    resolveAssets?(context: ProviderCallContext): void | Promise<void>;
    /** Chooses the provider and model, and reports them. */
    route?(): {
        provider?: string;
        model?: string;
    } | undefined | Promise<{
        provider?: string;
        model?: string;
    } | undefined>;
    /** What the operation is expected to cost in US dollars, held against the budget. */
    estimate?(): number | undefined;
    /** Runs the operation: a provider call, a cache read, or both. */
    execute(context: ProviderCallContext): Promise<T>;
    /** Applies output guardrails, and may replace the result. */
    outputPolicy?(result: T): T | Promise<T>;
    /** Stores what should outlive the call, such as a cache entry. */
    persist?(result: T): void | Promise<void>;
    /** What the result cost and whether a cache answered, for the budget, metrics, and audit. */
    settle?(result: T): OperationResultInfo;
}
/**
 * Runs operations of every family through the same stages: validate, authorize, input policy,
 * resolve assets, route, reserve budget, execute, output policy, persist, reconcile cost, and audit.
 *
 * Authorization, the rate limit, the budget, hooks, audit, and metrics live here once, so a family
 * supplies only what is its own: its checks, its routing, and its provider call. With nothing
 * configured, an operation pays for one request id and one abort signal.
 */
export declare class OperationLifecycle implements OperationLifecycleLike {
    private readonly runtime;
    constructor(runtime?: LifecycleRuntime);
    /**
     * Admits an operation: authorizes it, applies the rate limit, audits the request, and runs
     * `onStart`. Throws `OperationDeniedError` or `NexusRateLimitError` when it may not run.
     */
    start(input: Omit<OperationDescriptor, 'requestId'> & {
        requestId?: string;
    }, options?: OperationStartOptions & {
        audit?: Record<string, unknown>;
    }): Promise<OperationTicket>;
    /** Runs one operation through every stage and returns its result. */
    run<T>(input: Omit<OperationDescriptor, 'requestId'> & {
        requestId?: string;
    }, plan: OperationPlan<T>, options?: OperationStartOptions & {
        audit?: Record<string, unknown>;
    }): Promise<T>;
    /**
     * What a provider call that continues an operation admitted earlier is given, such as a video job
     * polled after a restart or a batch collected by another worker: its tenant's credentials, resolved
     * as `start()` resolves them, its residency, and a `scrub()` that keeps them out of its errors.
     * Nothing is authorized, budgeted, or audited: the operation it continues was.
     */
    callContext(input: Omit<OperationDescriptor, 'requestId'> & {
        requestId?: string;
    }): Promise<ContinuedCallContext>;
    /**
     * Which providers and models an operation may reach, under the residency policy and the provider
     * gate, or `undefined` when there is neither: what `start()` gives each operation's context, for
     * code that decides outside one.
     */
    access(descriptor: Pick<OperationDescriptor, 'tenantId'> & Partial<OperationDescriptor>): Promise<CallResidency | undefined>;
    /**
     * Reports how a provider answered a call a family made itself, such as a realtime connection, to the
     * client's provider health and circuit breaker.
     */
    reportHealth(provider: string, outcome: ProviderHealthOutcome): void;
    /** True when nothing is configured, so a caller may skip work that only feeds the lifecycle. */
    get inert(): boolean;
    private checkRateLimit;
    private authorize;
}
/** An operation's residency, as the families that call providers check it. */
export declare function callResidency(policy: ResidencyPolicy, decision: CallResidency['decision']): CallResidency;
/**
 * What an operation may reach: the providers its residency policy allows, and among them those the
 * provider gate admits, model by model.
 */
export declare function callAccess(descriptor: OperationDescriptor | undefined, policy: ResidencyPolicy | undefined, decision: ResidencyDecision | undefined, gate: ProviderGate | undefined): CallResidency;