/**
 * Closed enum of executor failure modes. The set is the *only* surface the
 * framework exposes about *why* a panel failed — it never widens to include
 * driver error strings, ZodError details, or any value derived from query
 * input or output.
 *
 * Adding a new category is a security-relevant change: the new value becomes
 * part of the bounded surface the LLM may see (via downstream consumers that
 * route categories into prompts), so each addition needs review against
 * Invariant 2 (no externally-sourced values in model-visible output).
 */
export type CarteExecutionErrorCategory = "unknown_query" | "invalid_params" | "query_failed" | "returns_mismatch" | "context_unauthorized";
/**
 * Sentinel `panelIndex` for `CarteExecutionError`s thrown during context
 * derivation — before any panel is associated with a query. The context
 * factory runs once per request, prior to plan execution; using `-1`
 * preserves the public `{ panelIndex, queryId, ... }` shape of
 * `CarteExecutionErrorPublic` (no schema change for downstream consumers)
 * while remaining recognisable as "not a real panel."
 *
 * Integration packages (e.g. `@usecarte/better-auth`) MUST use this constant
 * rather than the literal `-1` so contributors don't read it as a real
 * panel index.
 */
export declare const CONTEXT_PHASE_PANEL_INDEX = -1;
/**
 * Sentinel `queryId` paired with `CONTEXT_PHASE_PANEL_INDEX`. Same rationale:
 * keeps the projection shape stable; signals "this failure happened before
 * any query was selected." Integration packages MUST use this constant
 * rather than the literal string `"<context>"` so contributors don't read
 * it as a real query id.
 */
export declare const CONTEXT_PHASE_QUERY_ID = "<context>";
/**
 * Public, model-safe projection of a `CarteExecutionError`. This is the only
 * shape `@usecarte/*` will ever serialize to a model-visible surface (HTTP
 * response body, retry prompt, etc.) — `cause` and the underlying `Error.message`
 * are deliberately excluded.
 *
 * Consumers who want richer diagnostics should attach a `logger` to
 * `executePlan` and surface the full error server-side, never to the model.
 */
export interface CarteExecutionErrorPublic {
    category: CarteExecutionErrorCategory;
    panelIndex: number;
    queryId: string;
    correlationId: string;
}
/**
 * Sink for server-side observability. Receives the underlying `cause` (driver
 * error / ZodError / etc.) along with the framework-controlled metadata, so
 * consumers can write the full error to Sentry / Datadog / structured logs.
 *
 * The default is `console.error`. Wire a real sink in production; the model
 * never sees what the logger receives.
 */
export type CarteExecutionLogger = (event: {
    category: CarteExecutionErrorCategory;
    panelIndex: number;
    queryId: string;
    correlationId: string;
    cause: unknown;
}) => void;
/**
 * Default logger — prefixes the correlation ID so server-side log searches
 * line up with model-visible error references.
 */
export declare const defaultExecutionLogger: CarteExecutionLogger;
/**
 * Thrown by `executePlan` when a panel cannot be executed. The error's public
 * surface (`category`, `panelIndex`, `queryId`, `correlationId`) is bounded
 * and safe to surface to clients or feed into model-visible payloads via
 * `toModelSafeJSON()`. The original `cause` (driver error, ZodError) is
 * preserved on `Error.prototype.cause` for server-side debugging only —
 * `toModelSafeJSON()` deliberately excludes it.
 *
 * This is Invariant 2 in code form: nothing originating from query execution
 * (driver throws, returned rows, ZodError `received` values) reaches the
 * model-visible projection.
 */
export declare class CarteExecutionError extends Error {
    readonly panelIndex: number;
    readonly queryId: string;
    readonly category: CarteExecutionErrorCategory;
    readonly correlationId: string;
    constructor(options: {
        category: CarteExecutionErrorCategory;
        panelIndex: number;
        queryId: string;
        cause?: unknown;
        correlationId?: string;
    });
    /**
     * Closed-enum projection safe to serialize to clients or feed into
     * model-visible surfaces. Excludes `cause` and `message` (both can contain
     * externally-sourced values) by construction.
     */
    toModelSafeJSON(): CarteExecutionErrorPublic;
}
//# sourceMappingURL=errors.d.ts.map