import type { EnhancedRequest } from '@stacksjs/bun-router';
/**
 * Add a query to the recent queries list for error context.
 * Uses a circular buffer for O(1) insert instead of array.shift().
 *
 * Also runs N+1 detection: when the same query *shape* (with bound
 * values normalized away) repeats more than `N1_THRESHOLD` times within
 * a single request lifecycle, we warn once via `log.warn`. The signal
 * is highly correlated with missing eager loading.
 */
export declare function trackQuery(query: string, time?: number, connection?: string): void;
/**
 * Snapshot of query shape counts for the active request. Useful for
 * tests asserting that an action ran a single query for `posts`
 * instead of one-per-user.
 */
export declare function getQueryShapeCounts(): ReadonlyMap<string, number>;
/**
 * Reset query tracking for the active scope.
 *
 * Inside a request, this clears the per-request tracking object — but
 * the object is also auto-collected when the request goes out of scope,
 * so the explicit call is mainly useful for tests that re-use a single
 * request. Outside a request, this clears the process-wide fallback.
 */
export declare function clearTrackedQueries(): void;
/**
 * Create an Ignition-style error response for development
 */
export declare function createErrorResponse(error: Error, request: Request | EnhancedRequest, options?: {
    status?: number
    handlerPath?: string
    routingContext?: {
      controller?: string
      routeName?: string
      middleware?: string[]
    }
  }): Promise<Response>;
/**
 * Create a middleware error response (401, 403, etc.)
 *
 * Reads `statusCode` OR `status` off the error so both shapes are honored:
 * - middleware that throws `Object.assign(new Error('msg'), { statusCode: 401 })`
 * - framework HttpError instances where the field is named `status`
 *
 * Without the `status` fallback, every `HttpError(401, …)` throw from auth or
 * validation middleware leaks out as a 500 with an Ignition error page —
 * which is what we used to ship for `GET /api/me` without a token.
 */
export declare function createMiddlewareErrorResponse(error: Error & { statusCode?: number, status?: number, headers?: Record<string, string> }, request: Request | EnhancedRequest): Promise<Response>;
/**
 * Create a validation error response
 */
export declare function createValidationErrorResponse(errors: Record<string, string[]>, _request: Request | EnhancedRequest): Response;
/**
 * Create a 404 Not Found response
 */
export declare function createNotFoundResponse(path: string, request: Request | EnhancedRequest): Promise<Response>;
/**
 * Standard error response structure used across all JSON error responses.
 */
export declare interface ErrorResponseBody {
  error: string
  message: string
  status: number
  timestamp: string
  details?: Record<string, unknown>
}