/**
 * Shape of the kernel error surfaced by the napi-binding's `napi_err_from_kernel`.
 *
 * The Rust kernel's `kernel_error::Error` is exposed as a `JsError` whose
 * properties mirror the Rust struct: the `ErrorCode` variant name (as a string),
 * the message, and an optional SQLSTATE (either taken from the structured
 * server response or recovered via `extract_sqlstate_from_message`).
 */
export interface KernelErrorShape {
    /** Kernel `ErrorCode` variant name, e.g. `"Unauthenticated"`, `"SqlError"`. */
    code: string;
    /** Human-readable error message. */
    message: string;
    /** Optional SQLSTATE — five-char alphanumeric, when the kernel was able to surface it. */
    sqlstate?: string;
}
/**
 * Kernel `ErrorCode` variants — the 13 variants of the `#[non_exhaustive]` enum
 * defined in `src/kernel_error.rs:66-134`.
 *
 * Kept here as a literal type rather than an `enum` so test exhaustiveness checks
 * and runtime `code` strings are guaranteed to stay in lockstep with the kernel.
 */
export type KernelErrorCode = 'InvalidArgument' | 'Unauthenticated' | 'PermissionDenied' | 'NotFound' | 'ResourceExhausted' | 'Unavailable' | 'Timeout' | 'Cancelled' | 'DataLoss' | 'Internal' | 'InvalidStatementHandle' | 'NetworkError' | 'SqlError';
/**
 * Optional metadata fields the kernel may attach via the
 * `__databricks_error__:` envelope (per `native/kernel/src/error.rs:50-89`).
 *
 * `errorCode` is namespaced under `kernelMetadata` rather than placed at
 * the top level because `OperationStateError` already declares a top-level
 * `errorCode: enum` field, and `DBSQLOperation.ts` switches on it
 * (`err.errorCode === OperationStateErrorCode.Canceled`, around `:374`). Top-level
 * defineProperty would clobber that enum with a kernel string and break
 * cancel/close detection.
 */
export interface KernelMetadata {
    errorCode?: string;
    vendorCode?: number;
    httpStatus?: number;
    retryable?: boolean;
    queryId?: string;
    /**
     * Rich server-error diagnostics from the kernel terminal-error payload. These
     * mirror the fields the **Thrift** backend already surfaces via
     * `OperationStateError.response` (`TGetOperationStatusResp.displayMessage` /
     * `.errorMessage` / `.errorDetailsJson`) and that the Python `use_kernel`
     * connector forwards onto its exceptions — so kernel stays at parity rather
     * than dropping them. Kernel sources: `Error.display_message` /
     * `.diagnostic_info` / `.error_details_json`.
     */
    displayMessage?: string;
    diagnosticInfo?: string;
    errorDetailsJson?: string;
}
/**
 * An `Error` carrying optional kernel-side kernel context. `sqlState` is
 * exposed at the top level (no collision in the existing driver error
 * tree); the remaining envelope fields live under a `kernelMetadata`
 * namespace to avoid clobbering pre-existing `errorCode` semantics on
 * `OperationStateError`.
 */
export interface ErrorWithSqlState extends Error {
    sqlState?: string;
    kernelMetadata?: KernelMetadata;
}
/**
 * Map a kernel error (as surfaced by the napi-binding) to the appropriate JS
 * driver error class.
 *
 * M0 mapping table:
 *   Unauthenticated, PermissionDenied → AuthenticationError
 *   Cancelled                          → OperationStateError(Canceled)
 *   Timeout                            → OperationStateError(Timeout)
 *   InvalidArgument                    → ParameterError
 *   NetworkError, Unavailable,
 *   NotFound, ResourceExhausted,
 *   DataLoss, Internal,
 *   InvalidStatementHandle, SqlError   → HiveDriverError
 *
 * Unknown `code` values (e.g. if the kernel adds a new variant) fall through
 * to HiveDriverError so the driver never silently drops an error. The kernel's
 * `ErrorCode` is `#[non_exhaustive]` so this can legitimately happen.
 *
 * SQLSTATE, when present, is attached on `error.sqlState` regardless of which
 * class is returned.
 */
export declare function mapKernelErrorToJsError(kErr: KernelErrorShape): ErrorWithSqlState;
/**
 * Decode a napi-binding error into the typed JS error class.
 *
 * Two paths:
 *  - Structured kernel error: `Error.message` starts with
 *    {@link ERROR_SENTINEL} followed by a JSON envelope. We strip the
 *    sentinel, parse the JSON, route the {@link KernelErrorShape}
 *    through {@link mapKernelErrorToJsError}, and attach the remaining
 *    envelope fields under a single non-enumerable `kernelMetadata`
 *    namespace. Namespacing avoids the collision with
 *    `OperationStateError.errorCode` (an enum already switched on at the
 *    JS layer — see `DBSQLOperation.ts` around `:374`).
 *  - Binding-side error (e.g. `napi::Error::new(InvalidArg, "openSession:
 *    \`token\` is required for the requested auth mode")` produced by
 *    the binding's own validation): returned unchanged. These don't
 *    carry kernel `code` info, so we surface them as-is.
 *
 * Non-`Error` values (e.g. a `Promise.reject('string')`) pass through
 * wrapped in `HiveDriverError` so callers always see an `Error`
 * subclass.
 */
export declare function decodeNapiKernelError(err: unknown): Error;