/**
 * Error surface for `@arki/http`.
 *
 * Two families, mirroring the DOT diagnostics doctrine:
 *
 *  - {@link HttpConfigError} — composition/lifecycle failures (duplicate
 *    routes, listen failures, drain timeouts). Thrown from `boot`/`start`/
 *    `stop`; the kernel wraps them and their `code`/`remediation`/`docsUrl`
 *    propagate into `app.diagnostics.issues`.
 *  - {@link HttpError} — per-request failures. Thrown from handlers,
 *    derivers, or validation; serialized onto the wire as the coded
 *    envelope `{ error: { code, message, remediation?, docsUrl? } }`.
 *
 * Every code is stable API. Match on codes, never parse messages.
 */
/**
 * Stable error codes for `@arki/http`. `E0NN` codes surface through the
 * DOT lifecycle (boot/start/stop failures); `E4xx`/`E5xx` codes surface
 * on the wire in the error envelope.
 */
export declare const HTTP_ERROR_CODES: {
    /** `start` could not bind the port. */
    readonly listenFailed: "ARKI_HTTP_E001";
    /** Two bindings claim the same method + path. */
    readonly duplicateRoute: "ARKI_HTTP_E002";
    /** `stop` exceeded `drainTimeoutMs` with requests still in flight. */
    readonly drainTimeout: "ARKI_HTTP_E005";
    /** A mount path is malformed. */
    readonly invalidMount: "ARKI_HTTP_E006";
    /** A deriver key duplicates an earlier deriver or a base context key. */
    readonly duplicateDeriverKey: "ARKI_HTTP_E007";
    /** A DOT HTTP action carries missing or incompatible projection metadata. */
    readonly invalidActionMeta: "ARKI_HTTP_E009";
    /** Request validation failed (query/body) or the body is not valid JSON. */
    readonly badRequest: "ARKI_HTTP_E400";
    /** A deriver rejected the request's credentials. */
    readonly unauthorized: "ARKI_HTTP_E401";
    /** A deriver rejected the request's permissions. */
    readonly forbidden: "ARKI_HTTP_E403";
    /** No route matches the request. */
    readonly notFound: "ARKI_HTTP_E404";
    /** Handler crash or output-schema violation. */
    readonly internal: "ARKI_HTTP_E500";
};
/**
 * A per-request failure with an HTTP status and a stable code. Throw from
 * a handler or deriver to short-circuit into the wire envelope:
 *
 * ```ts
 * throw new HttpError(401, HTTP_ERROR_CODES.unauthorized, 'missing or invalid credentials');
 * ```
 */
export declare class HttpError extends Error {
    readonly status: number;
    readonly code: string;
    readonly remediation: string | undefined;
    readonly docsUrl: string | undefined;
    /** Extra response headers — e.g. `www-authenticate` on a 401, `retry-after` on a 429. */
    readonly headers: Readonly<Record<string, string>> | undefined;
    constructor(status: number, code: string, message: string, options?: {
        readonly remediation?: string;
        readonly docsUrl?: string;
        readonly headers?: Readonly<Record<string, string>>;
        readonly cause?: unknown;
    });
}
/**
 * A composition or lifecycle failure. Carries the same code/remediation/
 * docsUrl fields the DOT kernel propagates into diagnostics when a hook
 * throws.
 */
export declare class HttpConfigError extends Error {
    readonly code: string;
    readonly remediation: string;
    readonly docsUrl: string;
    constructor(fields: {
        readonly code: string;
        readonly message: string;
        readonly remediation: string;
        readonly docsUrl?: string;
    });
}
/** The wire error envelope. Stable shape — agents parse this. */
export type HttpErrorEnvelope = {
    readonly error: {
        readonly code: string;
        readonly message: string;
        readonly remediation?: string;
        readonly docsUrl?: string;
    };
};
/**
 * Message for an unexpected (non-{@link HttpError}) failure: full detail
 * in development, redacted in production — internals never leak onto the
 * wire of a deployed app.
 */
export declare function describeInternalError(error: unknown): string;
/**
 * Map any thrown value to its wire envelope: {@link HttpError} keeps its
 * status and fields; everything else is a redacted-in-production 500.
 */
export declare function toErrorResponse(error: unknown): Response;
/** Build the envelope `Response` for a coded failure. */
export declare function errorResponse(status: number, code: string, message: string, options?: {
    readonly remediation?: string;
    readonly docsUrl?: string;
    readonly headers?: Readonly<Record<string, string>>;
}): Response;
//# sourceMappingURL=error.d.ts.map