@nextrush/class 1.0.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,2306 @@
+import { HttpMethod, Context, RouteHandler, Middleware, MetadataContribution } from '@nextrush/types';
+import { Token, Constructor as Constructor$1, Scope, Container } from '@nextrush/di';
+export { Container, Repository, Service, container, createContainer, inject } from '@nextrush/di';
+import { Application } from '@nextrush/core';
+import { InternalServerError, HttpErrorOptions, ForbiddenError, BadRequestError } from '@nextrush/errors';
+export { HttpError } from '@nextrush/errors';
+
+/**
+ * @nextrush/decorators - Controller Type Definitions
+ *
+ * Metadata and options shapes for the @Controller decorator, plus the shared
+ * middleware reference type used by both controller- and route-level metadata.
+ */
+/**
+ * Reference to middleware - can be a class token or function
+ */
+type MiddlewareRef = symbol | string | ((...args: unknown[]) => unknown);
+/**
+ * Controller metadata stored by @Controller decorator
+ */
+interface ControllerMetadata {
+    /** Base path prefix for all routes in this controller */
+    readonly path: string;
+    /** Optional controller version for API versioning */
+    readonly version?: string;
+    /** Middleware to apply to all routes in this controller */
+    readonly middleware?: MiddlewareRef[];
+    /** Controller-level tags for documentation/grouping */
+    readonly tags?: string[];
+}
+/**
+ * Options for @Controller decorator
+ */
+interface ControllerOptions {
+    /** Base path prefix for all routes */
+    path?: string;
+    /** API version prefix (e.g., 'v1' → '/v1/users') */
+    version?: string;
+    /** Middleware to apply to all routes */
+    middleware?: MiddlewareRef[];
+    /** Tags for documentation grouping */
+    tags?: string[];
+}
+
+/**
+ * @nextrush/decorators - Route Type Definitions
+ *
+ * Metadata and options shapes for route decorators (@Get, @Post, etc.) and the
+ * response-shaping decorators (@SetHeader, @Redirect).
+ */
+
+/**
+ * Supported HTTP methods for route decorators.
+ *
+ * `'ALL'` is a decorator-metadata-only sentinel produced exclusively by
+ * `@All()` (T016) — it means "every standard method," not a literal HTTP
+ * verb, and never reaches the wire. It is intentionally NOT a member of
+ * `@nextrush/router`'s `HttpMethod` (a real, on-the-wire method set that the
+ * matching engine and static-route hash keys are built around) — widening
+ * that frozen core type for a class-package decorator concern would ripple
+ * into router internals with no benefit. The registrar's dispatch
+ * (`route.method.toLowerCase()` → `router['all']`) already resolves this
+ * value correctly since `Router.all()` exists with that exact name.
+ */
+type RouteMethods = Extract<HttpMethod, 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'> | 'ALL';
+/**
+ * Route metadata stored by @Get, @Post, etc. decorators
+ */
+interface ControllerRouteMetadata {
+    /** HTTP method for this route */
+    readonly method: RouteMethods;
+    /** Path pattern for this route (relative to controller path) */
+    readonly path: string;
+    /** Method name on the controller class */
+    readonly methodName: string | symbol;
+    /** Parameter index in the prototype */
+    readonly propertyKey: string | symbol;
+    /** Route-specific middleware */
+    readonly middleware?: MiddlewareRef[];
+    /** Response status code (default: 200 for GET, 201 for POST) */
+    readonly statusCode?: number;
+    /** Route description for documentation */
+    readonly description?: string;
+    /** Whether this route is deprecated */
+    readonly deprecated?: boolean;
+}
+/**
+ * @deprecated Use {@link ControllerRouteMetadata}. `RouteMetadata` collided with the
+ * unrelated, renderer-facing `RouteMetadata` contract exported from `@nextrush/types` (and
+ * re-exported via `nextrush`'s `.` entry) — the two shapes are structurally incompatible
+ * despite sharing a name. This alias will be removed in the next major; migrate now.
+ * See docs/RFC/framework-composition/020-framework-composition-integrity.md.
+ */
+type RouteMetadata = ControllerRouteMetadata;
+/**
+ * Options for route decorators (@Get, @Post, etc.)
+ */
+interface RouteOptions {
+    /** Route path (alternative to string argument) */
+    path?: string;
+    /** Route-specific middleware */
+    middleware?: MiddlewareRef[];
+    /** Response status code */
+    statusCode?: number;
+    /** Route description */
+    description?: string;
+    /** Mark route as deprecated */
+    deprecated?: boolean;
+}
+/**
+ * Metadata for @SetHeader decorator — stored per method.
+ */
+interface ResponseHeaderMetadata {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * Metadata for @Redirect decorator — stored per method.
+ */
+interface RedirectMetadata {
+    readonly url: string;
+    readonly statusCode: number;
+}
+
+/**
+ * @nextrush/decorators - Parameter Type Definitions
+ *
+ * Metadata and options shapes for parameter decorators (@Body, @Param, @Query,
+ * @Header, and custom param decorators), plus their transform/extractor types.
+ */
+
+/**
+ * Parameter source types for parameter decorators
+ */
+type ParamSource = 'body' | 'query' | 'param' | 'header' | 'ctx' | 'req' | 'res' | 'custom';
+/**
+ * Transform function for parameter value transformation.
+ * Supports both sync and async transforms.
+ */
+type TransformFn<TInput = unknown, TOutput = unknown> = ((value: TInput) => TOutput) | ((value: TInput) => Promise<TOutput>);
+/**
+ * Custom parameter extractor function.
+ *
+ * Receives the context object and returns the extracted value.
+ * Supports both sync and async extraction.
+ */
+type CustomParamExtractor<T = unknown> = ((ctx: Context) => T) | ((ctx: Context) => Promise<T>);
+/**
+ * Parameter metadata stored by @Body, @Param, etc. decorators
+ */
+interface ParamMetadata {
+    /** Source of the parameter value */
+    readonly source: ParamSource;
+    /** Parameter index in method signature */
+    readonly index: number;
+    /** Property name to extract (e.g., 'id' from params.id) */
+    readonly name?: string;
+    /** Whether the parameter is required (default: true for body/param) */
+    readonly required?: boolean;
+    /** Default value if not provided */
+    readonly defaultValue?: unknown;
+    /** Validation pipe or transform function */
+    readonly transform?: TransformFn;
+    /** Custom extractor function for user-defined param decorators */
+    readonly customExtractor?: CustomParamExtractor;
+}
+/**
+ * Options for @Body decorator
+ */
+interface BodyOptions {
+    /** Whether the body is required (default: true) */
+    required?: boolean;
+    /** Transform function to apply */
+    transform?: TransformFn;
+}
+/**
+ * Options for @Param decorator
+ */
+interface ParamOptions {
+    /** Whether the param is required (default: true) */
+    required?: boolean;
+    /** Default value if not provided */
+    defaultValue?: unknown;
+    /** Transform function (e.g., parseInt for numeric IDs) */
+    transform?: TransformFn;
+}
+/**
+ * Options for @Query decorator
+ */
+interface QueryOptions {
+    /** Whether the query param is required (default: false) */
+    required?: boolean;
+    /** Default value if not provided */
+    defaultValue?: unknown;
+    /** Transform function */
+    transform?: TransformFn;
+}
+/**
+ * Options for @Header decorator
+ */
+interface HeaderOptions {
+    /** Whether the header is required (default: false) */
+    required?: boolean;
+    /** Default value if not provided */
+    defaultValue?: unknown;
+}
+
+/**
+ * @nextrush/decorators - Guard Type Definitions
+ *
+ * Types for the @UseGuard decorator: the guard context, function and
+ * class-based guard contracts, and the stored guard metadata. Also home to the
+ * generic Constructor primitive shared with exception-filter types.
+ */
+/**
+ * Constructor type for class-based guards
+ */
+type Constructor<T = unknown> = new (...args: unknown[]) => T;
+/**
+ * Minimal context interface for guards (avoids circular dependency)
+ */
+interface GuardContext {
+    readonly method: string;
+    readonly path: string;
+    readonly params: Record<string, string>;
+    readonly query: Record<string, string | string[] | undefined>;
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly body: unknown;
+    readonly state: Record<string, unknown>;
+    get(name: string): string | undefined;
+}
+/**
+ * Guard function type.
+ *
+ * Guards determine if a request should proceed to the handler.
+ * Return true to allow, false to reject, or throw an error for custom handling.
+ */
+type GuardFn = (ctx: GuardContext) => boolean | Promise<boolean>;
+/**
+ * Interface for class-based guards with dependency injection support.
+ *
+ * Implement this interface to create guards that can be:
+ * - Resolved from the DI container
+ * - Injected with dependencies
+ * - Unit tested with mock dependencies
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import type { CanActivate, GuardContext } from 'nextrush/class';
+ *
+ * @Service()
+ * class AuthGuard implements CanActivate {
+ *   constructor(private authService: AuthService) {}
+ *
+ *   async canActivate(ctx: GuardContext): Promise<boolean> {
+ *     const token = ctx.get('authorization');
+ *     if (!token) return false;
+ *
+ *     const user = await this.authService.verify(token);
+ *     ctx.state.user = user;
+ *     return Boolean(user);
+ *   }
+ * }
+ * ```
+ */
+interface CanActivate {
+    canActivate(ctx: GuardContext): boolean | Promise<boolean>;
+}
+/**
+ * Guard type that can be either a function or a class implementing CanActivate.
+ * Used by @UseGuard decorator to accept both patterns.
+ */
+type Guard = GuardFn | Constructor<CanActivate>;
+/**
+ * Guard metadata stored by @UseGuard decorator
+ */
+interface GuardMetadata {
+    /** Array of guards (can be functions or class constructors) */
+    readonly guards: Guard[];
+    /** Whether this is a class or method level guard */
+    readonly target: 'class' | 'method';
+    /** Method name (only for method-level guards) */
+    readonly methodName?: string | symbol;
+}
+
+/**
+ * @nextrush/decorators - Exception Filter Type Definitions
+ *
+ * Types for the @UseFilter / @Catch decorators: the filter contract, its class
+ * constructor alias, and the stored filter metadata.
+ */
+
+/**
+ * Interface for class-based exception filters with dependency injection support.
+ *
+ * A filter catches errors thrown by a controller route (guards, parameter
+ * resolution, or the handler method) and produces the response by mutating
+ * `ctx` (status, headers, body). Filters are resolved from the DI container,
+ * so they may inject services (loggers, metrics, error mappers).
+ *
+ * Which errors a filter handles is declared with {@link Catch}. A filter is
+ * only invoked when attached to a controller/route via {@link UseFilter}.
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import { Catch, type ExceptionFilter } from 'nextrush/class';
+ * import { NotFoundError } from '@nextrush/errors';
+ * import type { Context } from '@nextrush/types';
+ *
+ * @Service()
+ * @Catch(EntityNotFoundError)
+ * class NotFoundFilter implements ExceptionFilter {
+ *   catch(error: unknown, ctx: Context): void {
+ *     ctx.status = 404;
+ *     ctx.json({ error: 'Resource not found' });
+ *   }
+ * }
+ * ```
+ */
+interface ExceptionFilter {
+    catch(error: unknown, ctx: Context): void | Promise<void>;
+}
+/**
+ * Constructor type for a class-based exception filter.
+ * Accepted by {@link UseFilter}; resolved from the DI container at catch time.
+ */
+type ExceptionFilterClass = Constructor<ExceptionFilter>;
+/**
+ * Exception filter metadata stored by the @UseFilter decorator.
+ */
+interface FilterMetadata {
+    /** Filter classes applied at this target */
+    readonly filters: ExceptionFilterClass[];
+    /** Whether this is a class or method level filter */
+    readonly target: 'class' | 'method';
+    /** Method name (only for method-level filters) */
+    readonly methodName?: string | symbol;
+}
+
+/**
+ * @nextrush/decorators - Interceptor Type Definitions
+ *
+ * Types for the @UseInterceptor decorator: the interceptor contract, its class
+ * constructor alias, and the stored interceptor metadata.
+ *
+ * An interceptor wraps the controller-method call (onion / around advice): it
+ * runs code before calling `next()`, awaits the result, and may transform or
+ * replace it — the returned value becomes the new result flowing into response
+ * handling. Interceptors are Promise-based (not Observable) and resolved from
+ * the DI container, so they may inject services (loggers, metrics, mappers).
+ */
+
+/**
+ * Interface for class-based interceptors with dependency injection support.
+ *
+ * `intercept` receives the request {@link Context} and a `next` callback that
+ * invokes the rest of the chain (inner interceptors, ultimately the controller
+ * method) and resolves to its result. Call `next()` to proceed; the value you
+ * return becomes the result — return `next()`'s value unchanged to pass through,
+ * or return a different value to transform the response. Wrap `next()` in
+ * try/catch to observe or recover from handler errors; rethrow to propagate.
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import type { Interceptor } from 'nextrush/class';
+ * import type { Context } from '@nextrush/types';
+ *
+ * @Service()
+ * class WrapInterceptor implements Interceptor {
+ *   async intercept(ctx: Context, next: () => Promise<unknown>): Promise<unknown> {
+ *     const data = await next();
+ *     return { data, timestamp: Date.now() };
+ *   }
+ * }
+ * ```
+ */
+interface Interceptor {
+    intercept(ctx: Context, next: () => Promise<unknown>): Promise<unknown>;
+}
+/**
+ * Constructor type for a class-based interceptor.
+ * Accepted by {@link UseInterceptor}; resolved from the DI container per request.
+ */
+type InterceptorClass = Constructor<Interceptor>;
+/**
+ * Interceptor metadata stored by the @UseInterceptor decorator.
+ */
+interface InterceptorMetadata {
+    /** Interceptor classes applied at this target */
+    readonly interceptors: InterceptorClass[];
+    /** Whether this is a class or method level interceptor */
+    readonly target: 'class' | 'method';
+    /** Method name (only for method-level interceptors) */
+    readonly methodName?: string | symbol;
+}
+
+/**
+ * @nextrush/decorators - Service Lifecycle Hook Type Definitions
+ *
+ * Two duck-typed behavioral interfaces — `OnInit` and `OnShutdown` — that a
+ * `@Service`/`@Repository`/`@Config` (or any DI-managed instance) may implement
+ * to participate in the application lifecycle. There is intentionally **no
+ * decorator**: a service opts in purely by declaring the method, and the
+ * controllers registrar detects it by presence via the guards below.
+ *
+ * Unlike {@link isGuardClass} (which inspects a class *constructor*'s prototype),
+ * these guards operate on resolved *instances*, because the registrar has
+ * already resolved each service from the container before deciding whether it
+ * takes part in the lifecycle.
+ *
+ * @see `@nextrush/controllers` `registerControllers` — bridges these hooks into
+ *   `app.ready()` (calls `onInit`) and `app.close()` (calls `onShutdown`).
+ */
+/**
+ * Implemented by a service that needs to run initialization logic once, when the
+ * application boots (`app.ready()`), after all controllers and their service
+ * graph have been registered and resolved.
+ *
+ * `onInit` runs in dependency order — a service's dependencies initialize before
+ * the service that depends on them (a reverse-BFS approximation of the graph).
+ * An async `onInit` is awaited, so boot does not complete until every hook has
+ * settled. Registration must happen before `serve()`/`ready()`.
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import type { OnInit } from 'nextrush/class';
+ *
+ * @Service()
+ * class Database implements OnInit {
+ *   async onInit(): Promise<void> {
+ *     await this.pool.connect();
+ *   }
+ * }
+ * ```
+ */
+interface OnInit {
+    onInit(): void | Promise<void>;
+}
+/**
+ * Implemented by a service that needs to release resources when the application
+ * shuts down (`app.close()`).
+ *
+ * `onShutdown` runs in the **reverse** of the `onInit` order (dependents tear
+ * down before their dependencies), and an async `onShutdown` is awaited.
+ *
+ * @example
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import type { OnShutdown } from 'nextrush/class';
+ *
+ * @Service()
+ * class Database implements OnShutdown {
+ *   async onShutdown(): Promise<void> {
+ *     await this.pool.end();
+ *   }
+ * }
+ * ```
+ */
+interface OnShutdown {
+    onShutdown(): void | Promise<void>;
+}
+/**
+ * Narrow an arbitrary value to {@link OnInit} by detecting a callable `onInit`
+ * member. Traverses the prototype chain, so both object literals and class
+ * instances are detected. Returns `false` for `null`, non-objects, and values
+ * whose `onInit` is not a function.
+ */
+declare function isOnInit(value: unknown): value is OnInit;
+/**
+ * Narrow an arbitrary value to {@link OnShutdown} by detecting a callable
+ * `onShutdown` member. Same semantics as {@link isOnInit}.
+ */
+declare function isOnShutdown(value: unknown): value is OnShutdown;
+
+/**
+ * @nextrush/decorators - Metadata Keys & Runtime Helpers
+ *
+ * The reflect-metadata storage keys plus the runtime type-guard helpers that
+ * back the decorator implementations. These are the only runtime values in the
+ * type layer — everything else in the sibling *-types modules is type-only.
+ */
+
+/**
+ * Metadata keys used for decorator storage
+ */
+declare const DECORATOR_METADATA_KEYS: {
+    readonly CONTROLLER: symbol;
+    readonly MODULE: symbol;
+    readonly ROUTES: symbol;
+    readonly PARAMS: symbol;
+    readonly MIDDLEWARE: symbol;
+    readonly GUARDS: symbol;
+    readonly INTERCEPTORS: symbol;
+    readonly FILTERS: symbol;
+    readonly CATCH: symbol;
+    readonly RESPONSE_HEADERS: symbol;
+    readonly REDIRECT: symbol;
+    readonly HTTP_CODE: symbol;
+};
+/**
+ * Type guard to check if a value is a valid HTTP method (decorator-metadata
+ * sense — includes `'ALL'`, the `@All()` any-method sentinel; T016).
+ */
+declare function isValidHttpMethod(method: string): method is RouteMethods;
+/**
+ * Type guard to check if a value is a valid param source
+ */
+declare function isValidParamSource(source: string): source is ParamSource;
+/**
+ * Type guard to check if a guard is a class (constructor) rather than a function.
+ *
+ * This checks if the guard has a prototype with the canActivate method defined,
+ * which indicates it's a class implementing CanActivate rather than a function.
+ */
+declare function isGuardClass(guard: Guard): guard is Constructor<CanActivate>;
+
+/**
+ * @nextrush/decorators - Class Decorators
+ *
+ * Controller decorator that marks a class as an HTTP controller.
+ * Makes the class injectable for DI via @nextrush/di abstraction.
+ * Lifecycle management (singleton/transient) is deferred to the
+ * controllers plugin registry, enabling proper test isolation.
+ * Uses legacy decorators for compatibility with parameter decorators.
+ */
+
+/**
+ * Marks a class as an HTTP controller with DI support.
+ *
+ * This decorator:
+ * 1. Registers the class as an HTTP controller with route metadata
+ * 2. Makes the class injectable (resolvable by the DI container)
+ *
+ * Lifecycle is managed by the controllers plugin, not the decorator.
+ * You do NOT need to add @Service() when using @Controller() - it's included!
+ *
+ * @param pathOrOptions - Base path string or controller options
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * // Simple path - DI is automatic!
+ * @Controller('/users')
+ * class UserController {
+ *   constructor(private userService: UserService) {}  // Auto-injected
+ * }
+ *
+ * // With options
+ * @Controller({ path: '/users', version: 'v1' })
+ * class UserController { }
+ *
+ * // Default path (uses class name)
+ * @Controller()
+ * class UserController { }  // → '/user'
+ * ```
+ */
+declare function Controller(pathOrOptions?: string | ControllerOptions): ClassDecorator;
+
+/**
+ * @nextrush/decorators - Module Type Definitions
+ *
+ * Metadata and options shapes for the @Module decorator. A module groups a
+ * feature's imports, controllers, and providers behind one registration entry
+ * point. `exports` is captured for future per-module encapsulation (see
+ * RFC-NEXTRUSH-MODULES §5) and is not enforced today.
+ */
+
+/**
+ * A provider config: register `provide` using one of `useClass` / `useValue` /
+ * `useFactory`. Exactly one of the three `use*` forms should be set.
+ *
+ * - `useClass` — construct the given class (DI-injected).
+ * - `useValue` — bind a constant value (scope is ignored).
+ * - `useFactory` — call the factory; `inject` lists tokens resolved and passed
+ *   to it as arguments (in order).
+ *
+ * `scope` defaults to `'singleton'` for class/factory providers.
+ */
+interface ModuleProviderConfig {
+    /** Token the provider is registered under (class, string, or symbol). */
+    provide: Token;
+    /** Construct this class to satisfy the token. */
+    useClass?: Constructor$1;
+    /** Bind this constant value to the token. */
+    useValue?: unknown;
+    /** Call this factory to produce the value. */
+    useFactory?: (...args: unknown[]) => unknown;
+    /** Tokens resolved and passed (in order) as arguments to `useFactory`. */
+    inject?: Token[];
+    /** Lifecycle scope. Defaults to `'singleton'` for class/factory providers. */
+    scope?: Scope;
+}
+/**
+ * A module provider is either a bare class constructor (registered with its
+ * declared `@Service` scope, or `singleton` if undecorated) or a full provider
+ * config.
+ */
+type ModuleProvider = Function | ModuleProviderConfig;
+/**
+ * Options for the @Module decorator.
+ */
+interface ModuleOptions {
+    /** Other `@Module` classes this module composes. */
+    imports?: Function[];
+    /** `@Controller` classes owned by this module. */
+    controllers?: Function[];
+    /** Providers (services/values/factories) this module registers. */
+    providers?: ModuleProvider[];
+    /**
+     * Providers this module makes visible to importers. Recorded now for future
+     * per-module encapsulation; not enforced yet (see RFC-NEXTRUSH-MODULES §5).
+     */
+    exports?: Function[];
+}
+/**
+ * Normalized module metadata stored by @Module. Every field is defaulted to an
+ * empty array so readers never return `undefined` collections.
+ */
+interface ModuleMetadata {
+    readonly imports: Function[];
+    readonly controllers: Function[];
+    readonly providers: ModuleProvider[];
+    readonly exports: Function[];
+}
+
+/**
+ * @nextrush/decorators - Module Decorator
+ *
+ * `@Module` records a feature's composition — its imported modules, controllers,
+ * providers, and exports — as reflect-metadata. It is a grouping/composition
+ * unit; the `@nextrush/controllers` `registerModule` registrar reads this
+ * metadata to wire the whole module graph in one call.
+ *
+ * This layer stores metadata only. Provider registration, route building, and
+ * (future) encapsulation live in the controllers layer — see
+ * RFC-NEXTRUSH-MODULES.
+ */
+
+/**
+ * Marks a class as a NextRush module.
+ *
+ * @param options - The module's imports, controllers, providers, and exports.
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [BillingModule],
+ *   controllers: [UserController],
+ *   providers: [UserService, { provide: 'CONFIG', useValue: cfg }],
+ *   exports: [UserService],
+ * })
+ * class UserModule {}
+ * ```
+ */
+declare function Module(options?: ModuleOptions): ClassDecorator;
+/**
+ * Check if a class carries `@Module` metadata.
+ */
+declare function isModule(target: Function): boolean;
+/**
+ * Read a module's metadata. Returns a defensive copy (fresh arrays) so callers
+ * cannot mutate the stored record. Returns `undefined` when `target` is not a
+ * module.
+ */
+declare function getModuleMetadata(target: Function): ModuleMetadata | undefined;
+
+/**
+ * @nextrush/decorators - @HttpCode Decorator
+ *
+ * Sets the HTTP status code returned when a controller method resolves with a
+ * value. Lives in its own module because `routes.ts` is already at the
+ * file-size ceiling.
+ */
+/**
+ * Set the HTTP status code for the response when the decorated method returns.
+ *
+ * Takes precedence over the route decorator's `statusCode` option (e.g.
+ * `@Post('/x', { statusCode: 200 })`) when both are present. Does not affect
+ * responses produced by a thrown `HttpError` (those keep the error's status)
+ * or by `@Redirect` (the redirect status wins).
+ *
+ * @param statusCode - HTTP status code to apply (e.g. 201, 202, 204)
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Post()
+ *   @HttpCode(201)
+ *   create(@Body() data: CreateUserDto) {
+ *     return this.users.create(data); // → 201 Created
+ *   }
+ * }
+ * ```
+ */
+declare function HttpCode(statusCode: number): MethodDecorator;
+
+/**
+ * @nextrush/decorators - Response Decorators
+ *
+ * Method decorators that shape the HTTP response: @SetHeader attaches response
+ * headers and @Redirect declares a redirect. Stored as reflect-metadata read by
+ * the controllers handler builder.
+ */
+/**
+ * Set a response header on the decorated method.
+ *
+ * Multiple `@SetHeader()` decorators can be stacked on the same method.
+ *
+ * @param name  - Header name (e.g., 'Cache-Control')
+ * @param value - Header value (e.g., 'no-cache')
+ *
+ * @example
+ * ```typescript
+ * @Controller('/files')
+ * class FileController {
+ *   @Get('/:id')
+ *   @SetHeader('Cache-Control', 'max-age=3600')
+ *   @SetHeader('X-Custom', 'value')
+ *   getFile(@Param('id') id: string) {
+ *     return { id };
+ *   }
+ * }
+ * ```
+ */
+declare function SetHeader(name: string, value: string): MethodDecorator;
+/**
+ * Redirect the response when the decorated method is called.
+ *
+ * If the method returns a string, it overrides the decorator's URL.
+ * If the method returns an object with `url` and/or `statusCode`, those override as well.
+ *
+ * @param url        - Default redirect URL
+ * @param statusCode - HTTP status code (default: 302)
+ *
+ * @example
+ * ```typescript
+ * @Controller('/legacy')
+ * class LegacyController {
+ *   @Get('/old-page')
+ *   @Redirect('/new-page', 301)
+ *   redirectOld() {
+ *     // Optional: return a string to override the URL
+ *   }
+ *
+ *   @Get('/dynamic')
+ *   @Redirect('/fallback')
+ *   dynamicRedirect() {
+ *     // Return a string to redirect elsewhere
+ *     return '/actual-destination';
+ *   }
+ * }
+ * ```
+ */
+declare function Redirect(url: string, statusCode?: number): MethodDecorator;
+
+/**
+ * @nextrush/decorators - Route Decorators
+ *
+ * HTTP method decorators for controller methods.
+ * Uses legacy decorators for compatibility with parameter decorators.
+ */
+
+/**
+ * @Get decorator - Marks a method as handling HTTP GET requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get()
+ *   findAll() { }
+ *
+ *   @Get('/:id')
+ *   findOne(@Param('id') id: string) { }
+ *
+ *   @Get('/search', { description: 'Search users' })
+ *   search(@Query('q') query: string) { }
+ * }
+ * ```
+ */
+declare const Get: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Post decorator - Marks a method as handling HTTP POST requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Post()
+ *   create(@Body() data: CreateUserDto) { }
+ *
+ *   @Post('/bulk', { statusCode: 201 })
+ *   createMany(@Body() users: CreateUserDto[]) { }
+ * }
+ * ```
+ */
+declare const Post: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Put decorator - Marks a method as handling HTTP PUT requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Put('/:id')
+ *   update(@Param('id') id: string, @Body() data: UpdateUserDto) { }
+ * }
+ * ```
+ */
+declare const Put: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Delete decorator - Marks a method as handling HTTP DELETE requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Delete('/:id')
+ *   remove(@Param('id') id: string) { }
+ * }
+ * ```
+ */
+declare const Delete: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Patch decorator - Marks a method as handling HTTP PATCH requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Patch('/:id')
+ *   partialUpdate(@Param('id') id: string, @Body() data: Partial<User>) { }
+ * }
+ * ```
+ */
+declare const Patch: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Head decorator - Marks a method as handling HTTP HEAD requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/files')
+ * class FileController {
+ *   @Head('/:id')
+ *   checkExists(@Param('id') id: string) { }
+ * }
+ * ```
+ */
+declare const Head: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @Options decorator - Marks a method as handling HTTP OPTIONS requests.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * class ApiController {
+ *   @Options()
+ *   cors() { }
+ * }
+ * ```
+ */
+declare const Options: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+/**
+ * @All decorator - Marks a method as handling all HTTP methods.
+ * Registers a single any-method route entry (T016) — matched by every
+ * standard HTTP method via the router's own `Router.all()`/`GroupRouter.all()`
+ * ANY-method registration, rather than one explicit RouteMetadata entry per
+ * enumerated method. `getRoutes()`/route introspection sees one row for an
+ * `@All()` route, consistent with how it was actually authored.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/proxy')
+ * class ProxyController {
+ *   @All('/*')
+ *   handle(@Ctx() ctx: Context) { }
+ * }
+ * ```
+ */
+declare const All: (pathOrOptions?: string | RouteOptions, options?: RouteOptions) => MethodDecorator;
+
+/**
+ * @nextrush/decorators - Standard Parameter Decorators
+ *
+ * Parameter decorators for injecting request data into controller method parameters.
+ * Uses legacy decorators (parameter decorators not supported in Stage 3).
+ */
+
+/**
+ * @Body decorator - Injects the request body into the parameter.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   // Inject entire body
+ *   @Post()
+ *   create(@Body() data: CreateUserDto) { }
+ *
+ *   // Inject specific property from body
+ *   @Post('/email')
+ *   updateEmail(@Body('email') email: string) { }
+ *
+ *   // With transform
+ *   @Post()
+ *   create(@Body({ transform: validateCreateUser }) data: CreateUserDto) { }
+ * }
+ * ```
+ */
+declare const Body: {
+    (): ParameterDecorator;
+    (property: string): ParameterDecorator;
+    (options: BodyOptions): ParameterDecorator;
+    (property: string, options: BodyOptions): ParameterDecorator;
+};
+/**
+ * @Param decorator - Injects route parameters into the parameter.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   // Inject all params
+ *   @Get('/:id')
+ *   findOne(@Param() params: { id: string }) { }
+ *
+ *   // Inject specific param
+ *   @Get('/:id')
+ *   findOne(@Param('id') id: string) { }
+ *
+ *   // With transform (e.g., parse to number)
+ *   @Get('/:id')
+ *   findOne(@Param('id', { transform: Number }) id: number) { }
+ * }
+ * ```
+ */
+declare const Param: {
+    (): ParameterDecorator;
+    (name: string): ParameterDecorator;
+    (options: ParamOptions): ParameterDecorator;
+    (name: string, options: ParamOptions): ParameterDecorator;
+};
+/**
+ * @Query decorator - Injects query parameters into the parameter.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   // Inject all query params
+ *   @Get()
+ *   findAll(@Query() query: { page?: number; limit?: number }) { }
+ *
+ *   // Inject specific query param
+ *   @Get()
+ *   findAll(@Query('page') page: string) { }
+ *
+ *   // With default value
+ *   @Get()
+ *   findAll(@Query('limit', { defaultValue: 10, transform: Number }) limit: number) { }
+ * }
+ * ```
+ */
+declare const Query: {
+    (): ParameterDecorator;
+    (name: string): ParameterDecorator;
+    (options: QueryOptions): ParameterDecorator;
+    (name: string, options: QueryOptions): ParameterDecorator;
+};
+/**
+ * @Header decorator - Injects request headers into the parameter.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * class ApiController {
+ *   // Inject all headers
+ *   @Get()
+ *   handle(@Header() headers: Record<string, string>) { }
+ *
+ *   // Inject specific header
+ *   @Get()
+ *   handle(@Header('authorization') auth: string) { }
+ *
+ *   // With default value
+ *   @Get()
+ *   handle(@Header('x-api-version', { defaultValue: 'v1' }) version: string) { }
+ * }
+ * ```
+ */
+declare const Header: {
+    (): ParameterDecorator;
+    (name: string): ParameterDecorator;
+    (options: HeaderOptions): ParameterDecorator;
+    (name: string, options: HeaderOptions): ParameterDecorator;
+};
+/**
+ * @Ctx decorator - Injects the full NextRush Context object.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/:id')
+ *   findOne(@Ctx() ctx: Context) {
+ *     const id = ctx.params.id;
+ *     ctx.json({ id });
+ *   }
+ * }
+ * ```
+ */
+declare function Ctx(): ParameterDecorator;
+/**
+ * @Req decorator - Injects the raw request object (adapter-specific).
+ *
+ * @example
+ * ```typescript
+ * @Controller('/files')
+ * class FileController {
+ *   @Post('/upload')
+ *   upload(@Req() req: IncomingMessage) {
+ *     // Access raw Node.js request for streaming
+ *   }
+ * }
+ * ```
+ */
+declare function Req(): ParameterDecorator;
+/**
+ * @Res decorator - Injects the raw response object (adapter-specific).
+ *
+ * @example
+ * ```typescript
+ * @Controller('/files')
+ * class FileController {
+ *   @Get('/download/:id')
+ *   download(@Res() res: ServerResponse) {
+ *     // Access raw Node.js response for streaming
+ *   }
+ * }
+ * ```
+ */
+declare function Res(): ParameterDecorator;
+
+/**
+ * @nextrush/decorators - Custom Parameter Decorator Factory
+ *
+ * User-defined parameter extractors for custom injection patterns.
+ */
+
+/**
+ * Create a custom parameter decorator with a user-defined extraction function.
+ *
+ * The extractor receives the request context and returns the value to inject
+ * into the handler parameter. Supports both sync and async extractors.
+ *
+ * @param extractor - Function that extracts the parameter value from context
+ * @param options - Optional transform and required settings
+ *
+ * @example
+ * ```typescript
+ * // Extract the authenticated user from state
+ * const CurrentUser = createCustomParamDecorator(
+ *   (ctx) => ctx.state.user
+ * );
+ *
+ * // Extract a specific cookie
+ * const Cookie = (name: string) => createCustomParamDecorator(
+ *   (ctx) => ctx.get('cookie')?.split(';')
+ *     .find(c => c.trim().startsWith(name + '='))
+ *     ?.split('=')[1]
+ * );
+ *
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/me')
+ *   getProfile(@CurrentUser user: User) {
+ *     return user;
+ *   }
+ * }
+ * ```
+ */
+declare function createCustomParamDecorator(extractor: CustomParamExtractor, options?: {
+    transform?: TransformFn;
+    required?: boolean;
+}): ParameterDecorator;
+
+/**
+ * @nextrush/decorators - Guard Decorators
+ *
+ * Guards are functions or classes that determine if a request should be handled.
+ * They run BEFORE the route handler and can prevent execution.
+ *
+ * Use guards for:
+ * - Authentication checks
+ * - Authorization/permission checks
+ * - Rate limiting
+ * - Feature flags
+ */
+
+/**
+ * Apply guards to a controller or route.
+ *
+ * Guards run in order and must all pass for the request to proceed.
+ * If any guard returns false or throws, the request is rejected.
+ *
+ * Supports both function-based and class-based guards:
+ * - Function guards: Simple functions that receive GuardContext
+ * - Class guards: Classes implementing CanActivate interface (resolved from DI)
+ *
+ * @param guards - Guard functions or classes to apply
+ *
+ * @example Controller-level guard (applies to all routes)
+ * ```typescript
+ * @UseGuard(AuthGuard)
+ * @Controller('/users')
+ * class UserController {
+ *   @Get()
+ *   findAll() { }  // Protected by AuthGuard
+ * }
+ * ```
+ *
+ * @example Route-level guard (applies to specific route)
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get()
+ *   findAll() { }  // Public
+ *
+ *   @UseGuard(AdminGuard)
+ *   @Delete('/:id')
+ *   remove(@Param('id') id: string) { }  // Admin only
+ * }
+ * ```
+ *
+ * @example Multiple guards (all must pass)
+ * ```typescript
+ * @UseGuard(AuthGuard, RoleGuard('admin'), RateLimitGuard)
+ * @Controller('/admin')
+ * class AdminController { }
+ * ```
+ *
+ * @example Function-based guard
+ * ```typescript
+ * const AuthGuard: GuardFn = async (ctx) => {
+ *   const token = ctx.get('authorization');
+ *   if (!token) return false;  // Reject
+ *
+ *   const user = await verifyToken(token);
+ *   ctx.state.user = user;  // Attach user to context
+ *   return true;  // Allow
+ * };
+ * ```
+ *
+ * @example Guard factory for dynamic configuration
+ * ```typescript
+ * const RoleGuard = (role: string): GuardFn => async (ctx) => {
+ *   return ctx.state.user?.role === role;
+ * };
+ * ```
+ *
+ * @example Class-based guard with DI
+ * ```typescript
+ * import { Service } from '@nextrush/di';
+ * import type { CanActivate, GuardContext } from 'nextrush/class';
+ *
+ * @Service()
+ * class AuthGuard implements CanActivate {
+ *   constructor(private authService: AuthService) {}
+ *
+ *   async canActivate(ctx: GuardContext): Promise<boolean> {
+ *     const token = ctx.get('authorization');
+ *     if (!token) return false;
+ *
+ *     const user = await this.authService.verify(token);
+ *     ctx.state.user = user;
+ *     return Boolean(user);
+ *   }
+ * }
+ *
+ * // Usage - class guard is resolved from DI container
+ * @UseGuard(AuthGuard)
+ * @Controller('/protected')
+ * class ProtectedController { }
+ * ```
+ */
+declare function UseGuard(...guards: Guard[]): ClassDecorator & MethodDecorator;
+/**
+ * Get all guards for a controller class.
+ *
+ * Guards are returned in bottom-to-top decorator application order,
+ * matching TypeScript's native decorator execution semantics.
+ *
+ * @param target - Controller class
+ * @returns Array of guards (functions or class constructors)
+ */
+declare function getClassGuards(target: Function): Guard[];
+/**
+ * Get guards for a specific method.
+ *
+ * Guards are returned in bottom-to-top decorator application order.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Array of guards (functions or class constructors)
+ */
+declare function getMethodGuards(target: Function, methodName: string | symbol): Guard[];
+/**
+ * Get all guards for a route (class + method guards combined).
+ *
+ * Class guards run first, then method guards.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Array of guards in execution order
+ */
+declare function getAllGuards(target: Function, methodName: string | symbol): Guard[];
+
+/**
+ * @nextrush/decorators - Exception Filter Decorators
+ *
+ * Exception filters localize error handling to a controller or route. A filter
+ * is a class implementing {@link ExceptionFilter}; it declares which errors it
+ * handles with `@Catch(...)` and turns a thrown error into a response.
+ *
+ * Filters are opt-in and non-breaking: a controller/route with no `@UseFilter`
+ * behaves exactly as before — errors propagate to the global error middleware.
+ */
+
+/**
+ * Declare which error constructors an exception filter handles.
+ *
+ * `@Catch(NotFoundError)` matches `NotFoundError` and its subclasses (via
+ * `instanceof`). `@Catch()` with no arguments is a **catch-all** — it matches
+ * any thrown value. A filter with no `@Catch` at all is also treated as
+ * catch-all.
+ *
+ * @param errorTypes - Error constructors this filter handles (empty = catch-all)
+ *
+ * @example
+ * ```typescript
+ * @Catch(EntityNotFoundError)
+ * class NotFoundFilter implements ExceptionFilter {
+ *   catch(error: unknown, ctx: Context) {
+ *     ctx.status = 404;
+ *     ctx.json({ error: 'Not found' });
+ *   }
+ * }
+ * ```
+ */
+declare function Catch(...errorTypes: Function[]): ClassDecorator;
+/**
+ * Apply exception filters to a controller or route.
+ *
+ * Works as both a class decorator (covers every route on the controller) and a
+ * method decorator (covers that route only), mirroring {@link UseGuard}.
+ * Method-level filters take precedence over class-level filters; within a
+ * level, the first matching filter wins.
+ *
+ * @param filters - Exception filter classes to apply
+ *
+ * @example Controller-level (applies to all routes)
+ * ```typescript
+ * @UseFilter(DomainErrorFilter)
+ * @Controller('/users')
+ * class UserController {}
+ * ```
+ *
+ * @example Method-level (higher precedence)
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @UseFilter(ConflictFilter)
+ *   @Post()
+ *   create() {}
+ * }
+ * ```
+ */
+declare function UseFilter(...filters: ExceptionFilterClass[]): ClassDecorator & MethodDecorator;
+/**
+ * Get the error constructors an exception filter handles.
+ *
+ * @param target - Filter class
+ * @returns Error constructors from `@Catch` (empty array = catch-all)
+ */
+declare function getCatchTypes(target: Function): Function[];
+/**
+ * Get all class-level filters for a controller.
+ *
+ * @param target - Controller class
+ * @returns Filter classes in decorator application order
+ */
+declare function getClassFilters(target: Function): ExceptionFilterClass[];
+/**
+ * Get method-level filters for a specific route.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Filter classes in decorator application order
+ */
+declare function getMethodFilters(target: Function, methodName: string | symbol): ExceptionFilterClass[];
+/**
+ * Get all filters applicable to a route, in resolution/precedence order.
+ *
+ * Method-level filters come first (higher precedence), then class-level
+ * filters. The controllers runtime walks this list and invokes the first
+ * filter whose `@Catch` types match the thrown error.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Filter classes: method filters first, then class filters
+ */
+declare function getAllFilters(target: Function, methodName: string | symbol): ExceptionFilterClass[];
+
+/**
+ * @nextrush/decorators - Interceptor Decorators
+ *
+ * Interceptors wrap the controller-method call (onion / around advice). An
+ * interceptor runs code before calling `next()`, awaits the downstream result,
+ * and may transform or replace it before it flows into response handling.
+ *
+ * Interceptors are opt-in and non-breaking: a controller/route with no
+ * `@UseInterceptor` behaves exactly as before — the method result flows
+ * straight into response handling.
+ *
+ * Use interceptors for:
+ * - Response shaping / envelope wrapping
+ * - Timing, logging, and metrics around the handler
+ * - Caching (short-circuit `next()` and return a cached value)
+ * - Cross-cutting error mapping (try/catch around `next()`)
+ */
+
+/**
+ * Apply interceptors to a controller or route.
+ *
+ * Works as both a class decorator (wraps every route on the controller) and a
+ * method decorator (wraps that route only), mirroring {@link UseGuard}. Class
+ * interceptors are the outermost layers of the onion; method interceptors are
+ * inner, closest to the handler. Interceptor classes are resolved from the DI
+ * container at request time.
+ *
+ * @param interceptors - Interceptor classes to apply
+ *
+ * @example Controller-level (wraps all routes)
+ * ```typescript
+ * @UseInterceptor(TimingInterceptor)
+ * @Controller('/users')
+ * class UserController {}
+ * ```
+ *
+ * @example Method-level (inner layer, closest to the handler)
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @UseInterceptor(CacheInterceptor)
+ *   @Get()
+ *   findAll() {}
+ * }
+ * ```
+ */
+declare function UseInterceptor(...interceptors: InterceptorClass[]): ClassDecorator & MethodDecorator;
+/**
+ * Get all class-level interceptors for a controller.
+ *
+ * Interceptors are returned in bottom-to-top decorator application order,
+ * matching TypeScript's native decorator execution semantics.
+ *
+ * @param target - Controller class
+ * @returns Interceptor classes in decorator application order
+ */
+declare function getClassInterceptors(target: Function): InterceptorClass[];
+/**
+ * Get method-level interceptors for a specific route.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Interceptor classes in decorator application order
+ */
+declare function getMethodInterceptors(target: Function, methodName: string | symbol): InterceptorClass[];
+/**
+ * Get all interceptors applicable to a route, in onion (outer-to-inner) order.
+ *
+ * Class interceptors come first (outermost layers), then method interceptors
+ * (inner, closest to the handler). The controllers runtime builds the chain so
+ * the first entry runs first and returns last.
+ *
+ * @param target - Controller class
+ * @param methodName - Method name
+ * @returns Interceptor classes: class interceptors first, then method
+ */
+declare function getAllInterceptors(target: Function, methodName: string | symbol): InterceptorClass[];
+
+/**
+ * @nextrush/decorators - Metadata Readers
+ *
+ * Utility functions to read decorator metadata from controller classes.
+ * Used by @nextrush/controllers' registrar to build routes.
+ */
+
+/**
+ * Check if a class has @Controller decorator.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController { }
+ *
+ * isController(UserController); // true
+ * isController(SomeService);    // false
+ * ```
+ */
+declare function isController(target: Function): boolean;
+/**
+ * Get controller metadata from a class.
+ * Returns undefined if class doesn't have @Controller decorator.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController { }
+ *
+ * const meta = getControllerMetadata(UserController);
+ * // { path: '/users', version: undefined, middleware: undefined, tags: undefined }
+ * ```
+ */
+declare function getControllerMetadata(target: Function): ControllerMetadata | undefined;
+/**
+ * Get all route metadata from a controller class.
+ * Returns empty array if no routes are defined.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get()
+ *   findAll() { }
+ *
+ *   @Get('/:id')
+ *   findOne() { }
+ * }
+ *
+ * const routes = getRouteMetadata(UserController);
+ * // [{ method: 'GET', path: '/', ... }, { method: 'GET', path: '/:id', ... }]
+ * ```
+ */
+declare function getRouteMetadata(target: Function): ControllerRouteMetadata[];
+/**
+ * Get parameter metadata for a specific method.
+ * Returns empty array if no parameters have decorators.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * class UserController {
+ *   @Get('/:id')
+ *   findOne(@Param('id') id: string, @Query('include') include: string) { }
+ * }
+ *
+ * const params = getParamMetadata(UserController, 'findOne');
+ * // [{ source: 'param', index: 0, name: 'id' }, { source: 'query', index: 1, name: 'include' }]
+ * ```
+ */
+declare function getParamMetadata(target: Function, methodName: string | symbol): ParamMetadata[];
+/**
+ * Get all parameter metadata for all methods in a controller.
+ * Returns a Map where keys are method names.
+ *
+ * @example
+ * ```typescript
+ * const allParams = getAllParamMetadata(UserController);
+ * // Map { 'findOne' => [...], 'create' => [...] }
+ * ```
+ */
+declare function getAllParamMetadata(target: Function): Map<string, ParamMetadata[]>;
+/**
+ * Get full controller definition including metadata, routes, and params.
+ * Returns undefined if class is not a controller.
+ *
+ * @example
+ * ```typescript
+ * const def = getControllerDefinition(UserController);
+ * // {
+ * //   controller: { path: '/users', ... },
+ * //   routes: [{ method: 'GET', path: '/', ... }],
+ * //   params: Map { 'findOne' => [...] }
+ * // }
+ * ```
+ */
+declare function getControllerDefinition(target: Function): ControllerDefinition | undefined;
+/**
+ * Full controller definition with all metadata
+ */
+interface ControllerDefinition {
+    /** Controller class constructor */
+    readonly target: Function;
+    /** Controller-level metadata */
+    readonly controller: ControllerMetadata;
+    /** All route metadata */
+    readonly routes: ControllerRouteMetadata[];
+    /** Parameter metadata keyed by method name */
+    readonly params: Map<string, ParamMetadata[]>;
+}
+/**
+ * Get response headers metadata for a controller method.
+ *
+ * Returns the list of `@SetHeader()` entries for the given method,
+ * or an empty array if none are defined.
+ */
+declare function getResponseHeaders(target: Function, methodName: string): ResponseHeaderMetadata[];
+/**
+ * Get redirect metadata for a controller method.
+ *
+ * Returns the `@Redirect()` configuration for the given method,
+ * or `undefined` if not decorated.
+ */
+declare function getRedirectMetadata(target: Function, methodName: string): RedirectMetadata | undefined;
+/**
+ * Get the `@HttpCode()` status code for a controller method.
+ *
+ * Returns the status code stored by `@HttpCode(code)`, or `undefined` if the
+ * method is not decorated.
+ */
+declare function getHttpCode(target: Function, methodName: string): number | undefined;
+
+/**
+ * @nextrush/decorators - Reflection API Isolation
+ *
+ * Single point of contact for all Reflect.getMetadata, Reflect.defineMetadata,
+ * and design:paramtypes reads. Isolates reflection plumbing from business logic.
+ */
+/**
+ * Read the constructor parameter types emitted by TypeScript's `emitDecoratorMetadata`.
+ * Returns an empty array if metadata is not present (e.g., under esbuild/tsx without
+ * the metadata plugin).
+ *
+ * This is the ONLY place in the package that reads `design:paramtypes` directly.
+ * All other code requests parameter types through this helper.
+ *
+ * @internal For cross-package DI use, re-export from index.ts as getConstructorParamTypes.
+ */
+declare function getConstructorParamTypes(target: Function): unknown[];
+
+/**
+ * @nextrush/controllers - Error Classes
+ *
+ * Production-grade error classes with actionable messages.
+ * Client errors (4xx) extend HttpError for proper status codes.
+ */
+
+/**
+ * Base error class for controller-related server errors.
+ * These are 500-level errors that indicate server-side issues.
+ *
+ * Note: We use `declare` for name/message to help TypeScript's declaration
+ * emitter recognize that these are inherited from Error via @nextrush/errors.
+ */
+declare class ControllerError extends InternalServerError {
+    name: string;
+    message: string;
+    constructor(message: string, code: string, options?: HttpErrorOptions);
+}
+/**
+ * Error thrown when a class is not a valid controller.
+ * This is a server configuration error (500).
+ */
+declare class NotAControllerError extends ControllerError {
+    constructor(className: string);
+}
+/**
+ * Error thrown when controller has no routes defined.
+ * This is a server configuration error (500).
+ */
+declare class NoRoutesError extends ControllerError {
+    constructor(className: string);
+}
+/**
+ * Error thrown when file discovery fails.
+ * This is a server configuration error (500).
+ */
+declare class DiscoveryError extends ControllerError {
+    readonly filePath: string;
+    constructor(filePath: string, reason: string, cause?: Error);
+}
+/**
+ * Error thrown when DI resolution fails for a controller.
+ * This is a server configuration error (500).
+ */
+declare class ControllerResolutionError extends ControllerError {
+    readonly controllerName: string;
+    constructor(controllerName: string, cause?: Error);
+}
+/**
+ * Error thrown when parameter injection fails.
+ * This is a CLIENT error (400) - the request is malformed.
+ */
+declare class ParameterInjectionError extends BadRequestError {
+    name: string;
+    message: string;
+    readonly controllerName: string;
+    readonly methodName: string;
+    readonly paramIndex: number;
+    constructor(controllerName: string, methodName: string, paramIndex: number, reason: string);
+}
+/**
+ * Error thrown when a required parameter is missing.
+ * This is a CLIENT error (400) - the request is incomplete.
+ *
+ * `messageOverride` lets callers replace the generic
+ * `Required <source> parameter "<name>" is missing` text with a more
+ * specific message (e.g. `@Body()` appends a body-parser remediation hint
+ * in `resolveParametersFromPlan` — see `binding/param-resolver.ts`) while
+ * keeping `code`/`details`/`instanceof MissingParameterError` unchanged, so
+ * existing error-handling code that switches on the error type is
+ * unaffected.
+ */
+declare class MissingParameterError extends BadRequestError {
+    name: string;
+    message: string;
+    readonly controllerName: string;
+    readonly methodName: string;
+    readonly paramName: string;
+    readonly source: string;
+    constructor(controllerName: string, methodName: string, paramName: string, source: string, messageOverride?: string);
+}
+/**
+ * Error thrown when route registration fails.
+ * This is a server configuration error (500).
+ */
+declare class RouteRegistrationError extends ControllerError {
+    readonly controllerName: string;
+    readonly method: string;
+    readonly path: string;
+    constructor(controllerName: string, method: string, path: string, reason: string, cause?: Error);
+}
+/**
+ * Error thrown when a guard rejects the request.
+ * This is a CLIENT error (403) - access denied.
+ */
+declare class GuardRejectionError extends ForbiddenError {
+    name: string;
+    message: string;
+    readonly guardName: string;
+    constructor(guardName: string, message?: string);
+}
+/**
+ * Error thrown when a class passed where a module is expected is not a valid
+ * module. This is a server configuration error (500).
+ */
+declare class NotAModuleError extends ControllerError {
+    constructor(className: string);
+}
+
+/**
+ * DiscoverySource: Abstraction for controller class discovery.
+ *
+ * Two implementations:
+ * - FilesystemSource: Scans the filesystem for controller files (default)
+ * - MemorySource: Uses an explicit list of controller classes (programmatic/test)
+ */
+/**
+ * Discovers controller classes. Called by the discover stage.
+ */
+interface DiscoverySource {
+    discover(): ClassRef[] | Promise<ClassRef[]>;
+}
+/**
+ * A controller class reference. Always a constructor function.
+ */
+type ClassRef = Function;
+/**
+ * FilesystemSource: Wraps the existing filesystem discovery logic.
+ *
+ * Scans a directory tree for controller files matching include/exclude patterns,
+ * imports them, and returns the discovered controller classes.
+ */
+declare class FilesystemSource implements DiscoverySource {
+    private root;
+    private include;
+    private exclude;
+    private debug;
+    private _discoveryErrors;
+    constructor(root: string, include: string[], exclude: string[], debug: boolean);
+    discover(): Promise<ClassRef[]>;
+    /**
+     * Access discovery errors, if any, after discover() completes.
+     * @internal
+     */
+    getDiscoveryErrors(): unknown[];
+}
+/**
+ * MemorySource: Uses an explicit list of controller classes.
+ *
+ * For programmatic/test use cases where controller classes are already known
+ * and no filesystem scan is needed.
+ */
+declare class MemorySource implements DiscoverySource {
+    private controllers;
+    constructor(controllers: ClassRef[]);
+    discover(): ClassRef[];
+}
+
+/**
+ * @nextrush/controllers - Type Definitions
+ *
+ * Types for the controller registrar.
+ */
+
+/**
+ * Options for the controllers registrar
+ *
+ * Supports two modes:
+ * 1. Auto-discovery (recommended): Scan directories for @Controller classes
+ * 2. Manual: Explicitly provide controller classes
+ */
+interface ControllersOptions {
+    /**
+     * Root directory to scan for controllers
+     * When provided, enables auto-discovery mode
+     * @example './src'
+     */
+    root?: string;
+    /**
+     * Glob patterns to include in auto-discovery.
+     *
+     * Defaults to the `*.controller.*` naming convention, so only files named
+     * like `user.controller.ts` are imported. Non-controller modules (services,
+     * guards, repositories) still load transitively via the controllers that
+     * import them, so their `@Service`/`@Repository` side-effects still fire.
+     *
+     * To scan every source file instead (the pre-v3.2 behavior), pass the
+     * scan-all escape hatch: `['**‍/*.ts', '**‍/*.js']`.
+     *
+     * Side-effect: each matched file is dynamically `import()`ed, which runs its
+     * top-level module code.
+     *
+     * @default `['**‍/*.controller.ts', '**‍/*.controller.js']`
+     */
+    include?: string[];
+    /**
+     * Glob patterns to exclude from auto-discovery
+     * @default `['**‍/*.test.ts', '**‍/*.spec.ts', '**‍/node_modules/**', '**‍/dist/**']`
+     */
+    exclude?: string[];
+    /**
+     * Explicit list of controller classes to register.
+     *
+     * A first-class alternative to `root`-based auto-discovery — not deprecated.
+     * Prefer it when explicit wiring reads better than convention: greppable
+     * registration, a deterministic registration order, or no filesystem scan at
+     * all (tests, bundled or serverless builds where dynamically `import()`ing a
+     * source tree is unavailable). Merged with any `root`-discovered controllers.
+     */
+    controllers?: Function[];
+    /**
+     * Custom discovery source for controller discovery.
+     *
+     * For programmatic/test use: supply a `DiscoverySource` that returns
+     * controller classes instead of using filesystem scanning or the `controllers`
+     * list. Advanced option; typically used with `MemorySource` in tests.
+     *
+     * Takes precedence over `root` and is incompatible with `controllers`.
+     */
+    source?: DiscoverySource;
+    /**
+     * Custom DI container to use.
+     * If not provided, falls back to `app.container`, then the global container.
+     */
+    container?: Container;
+    /**
+     * Give this registration call its **own** isolated DI container so two apps in
+     * the same process do not share service singletons.
+     *
+     * `@Service`/`@Repository`/`@Config` register their classes into the global
+     * `@nextrush/di` container at import time, so by default every app that falls
+     * back to the global container shares one instance of each service. With
+     * `isolate: true`, `registerControllers` creates a fresh container via
+     * `createContainer()` and re-registers the reachable service graph (each
+     * controller's constructor dependency classes, transitively) into it with each
+     * class's declared scope. Each isolated app then owns its own service
+     * singletons; the controllers, their handlers, and boot-time validation all
+     * resolve from this container.
+     *
+     * When `options.container` is provided it always wins — even under
+     * `isolate: true` — because the caller has taken explicit ownership; the
+     * service graph is registered into that container instead of a fresh one.
+     *
+     * String/symbol `@inject('TOKEN')` dependencies and any value/factory providers
+     * carry no class metadata, so the graph walk cannot auto-register them. Register
+     * them on the container you pass **before** calling `registerControllers` (see
+     * the README). `@Optional()` dependencies that stay unregistered resolve to
+     * `undefined` as usual.
+     *
+     * Non-breaking: defaults to `false`, preserving the current shared-container
+     * behavior for every existing caller.
+     *
+     * @default false
+     */
+    isolate?: boolean;
+    /**
+     * Global middleware to apply to all controllers
+     */
+    middleware?: Middleware[];
+    /**
+     * Whether to enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Custom route prefix to apply to all controllers
+     * @example '/api' or '/api/v1'
+     */
+    prefix?: string;
+    /**
+     * Whether to throw on discovery errors
+     * @default false - logs warnings instead
+     */
+    strict?: boolean;
+    /**
+     * Whether to eagerly resolve every registered controller once at the end of
+     * registration, so unsatisfiable or circular constructor dependencies fail at
+     * boot (throwing {@link ControllerResolutionError}) instead of surfacing as a
+     * 500 on the first HTTP request.
+     * @default true
+     */
+    validate?: boolean;
+    /**
+     * Enable opt-in diagnostics collection from the ApplicationGraph IR.
+     *
+     * When true, collects routes, providers, duplicate routes, circular
+     * dependencies, and bootstrap stage timings. Call getClassDiagnostics(app)
+     * to retrieve the report after registration completes.
+     *
+     * Zero-cost when disabled: no timing measurement, no report collection,
+     * no WeakMap storage. Use this for introspection, debugging, and dev tooling.
+     *
+     * @default false
+     */
+    diagnostics?: boolean;
+}
+/**
+ * Resolved options with defaults applied
+ */
+interface ResolvedOptions {
+    readonly root: string | null;
+    readonly include: string[];
+    readonly exclude: string[];
+    readonly controllers: Function[];
+    readonly container: Container;
+    readonly middleware: Middleware[];
+    readonly debug: boolean;
+    readonly prefix: string;
+    readonly strict: boolean;
+    readonly validate: boolean;
+    readonly isolate: boolean;
+    readonly diagnostics: boolean;
+}
+/**
+ * Built route ready for registration
+ */
+interface BuiltRoute {
+    /** HTTP method */
+    readonly method: string;
+    /** Full path including controller prefix */
+    readonly path: string;
+    /** Route handler function */
+    readonly handler: RouteHandler;
+    /** Combined middleware (controller + route level) */
+    readonly middleware: Middleware[];
+    /** Controller class constructor */
+    readonly controller: Function;
+    /** Method name on controller */
+    readonly methodName: string;
+    /**
+     * Route metadata contributed from decorators (@Controller tags, @Get/@Post
+     * description/deprecated). Consumed by the router's RouteDefinition so
+     * class-based routes are documented by renderers like @nextrush/openapi.
+     * Undefined when the route carries no documentation.
+     */
+    readonly metadata?: MetadataContribution;
+}
+/**
+ * Registered controller info
+ */
+interface RegisteredController {
+    /** Controller class */
+    readonly target: Function;
+    /** Controller definition with metadata */
+    readonly definition: ControllerDefinition;
+    /** Built routes */
+    readonly routes: BuiltRoute[];
+}
+/**
+ * Discovery result from file scanning
+ */
+interface DiscoveryResult {
+    /** Path to the source file */
+    readonly filePath: string;
+    /** Discovered controller classes */
+    readonly controllers: Function[];
+    /** Any errors during discovery */
+    readonly errors: DiscoveryError[];
+}
+/**
+ * Options for the discoverControllers function
+ */
+interface DiscoveryOptions {
+    /** Root directory to scan */
+    readonly root: string;
+    /** Glob patterns to include */
+    readonly include?: string[];
+    /** Glob patterns to exclude */
+    readonly exclude?: string[];
+    /** Enable debug logging */
+    readonly debug?: boolean;
+}
+
+/**
+ * @nextrush/controllers - Controller registration
+ *
+ * `registerControllers(app, options)` is a **registrar**: it scans for
+ * `@Controller` classes (or takes them explicitly), builds their routes, and
+ * registers them on the app's router. It reads `app.router` and `app.container`
+ * — no plugin lifecycle, no ignored app. Call it (awaited) before `serve()`.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp();
+ * await registerControllers(app, { root: './src', prefix: '/api' });
+ * await serve(app, { port: 8080 });
+ * ```
+ */
+
+/**
+ * Discover and register decorator-based controllers on an application.
+ *
+ * Reads `app.router` (required) and `app.container` (falls back to a custom
+ * container in options, then the global container). Supports auto-discovery
+ * (`root`) and/or explicit `controllers`.
+ *
+ * @param app - The application (must have a router — use `createApp()` from `nextrush`)
+ * @param options - Discovery/registration options
+ */
+declare function registerControllers(app: Application, options?: ControllersOptions): Promise<void>;
+
+/**
+ * @nextrush/controllers - Module registrar
+ *
+ * `registerModule(app, RootModule, options?)` wires a whole `@Module` graph in
+ * one call: it walks `imports`, registers every module's providers into the DI
+ * container, then hands the flattened controller list to the existing
+ * `registerControllers` pipeline (route building, eager validation, guard
+ * validation, lifecycle-hook bridging, isolate/request-scope). It duplicates
+ * none of that machinery. See RFC-NEXTRUSH-MODULES.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp();
+ * await registerModule(app, AppModule, { prefix: '/api' });
+ * await serve(app, { port: 8080 });
+ * ```
+ */
+
+/**
+ * Options for {@link registerModule}. Mirrors the subset of
+ * {@link ControllersOptions} that applies to module registration — module
+ * composition replaces `root`/`controllers` discovery.
+ */
+type ModuleRegistrationOptions = Pick<ControllersOptions, 'prefix' | 'middleware' | 'container' | 'isolate' | 'validate' | 'debug'>;
+/**
+ * Register a module graph on an application.
+ *
+ * Selects the DI container once (an explicit `options.container` wins, else
+ * `isolate` gets a fresh container, else `app.container` → the global
+ * container), registers every module's providers into it, then registers all
+ * controllers across the graph through {@link registerControllers}. The chosen
+ * container is passed explicitly so it wins inside `registerControllers` even
+ * under `isolate: true`, keeping providers and controllers on one container.
+ *
+ * @param app - The application (must have a router — use `createApp()`).
+ * @param rootModule - The root `@Module` class.
+ * @param options - Registration options (prefix, middleware, container, etc.).
+ * @throws {NotAModuleError} if `rootModule` or any imported class is not a module.
+ */
+declare function registerModule(app: Application, rootModule: Function, options?: ModuleRegistrationOptions): Promise<void>;
+
+/**
+ * @nextrush/controllers - Module graph traversal
+ *
+ * Walks a module's `imports` into a flat, ordered, deduplicated list. The walk
+ * is post-order (imported feature modules before their importer), dedupes
+ * diamond/duplicate imports, and guards import cycles. See RFC-NEXTRUSH-MODULES.
+ */
+/**
+ * Collect the full module graph reachable from `root` via `imports`.
+ *
+ * - **Post-order**: an imported module appears before the module that imports
+ *   it, so a feature module's providers/controllers register before the root's.
+ * - **Dedupe**: a module reached through multiple paths (diamond) or listed
+ *   twice is included exactly once (first-completed wins).
+ * - **Cycle guard**: a back-edge to an in-progress module is skipped, so a
+ *   mutual import (`A imports B imports A`) terminates instead of recursing
+ *   forever.
+ *
+ * @throws {NotAModuleError} if `root` or any imported class lacks `@Module`.
+ */
+declare function collectModuleGraph(root: Function): Function[];
+/**
+ * Collect every controller declared across an ordered module list, preserving
+ * order and deduplicating a controller declared in more than one module.
+ */
+declare function collectModuleControllers(modules: Function[]): Function[];
+
+/**
+ * @nextrush/controllers - Controller Discovery
+ *
+ * Automatic controller discovery by scanning directories.
+ * Uses glob patterns to find files and imports them to discover controllers.
+ *
+ * ## Import side-effect (important)
+ *
+ * Discovery works by **dynamically `import()`ing every matched module**, then
+ * inspecting its exports for `@Controller` classes. Importing a module runs its
+ * top-level code — so any side-effects at module scope (DI registration via
+ * `@Service`/`@Repository`, singleton construction, connection setup) execute
+ * during discovery. This is load-bearing: services and guards register with the
+ * DI container as a side-effect of being imported (transitively via the
+ * controllers that import them, or directly when matched).
+ */
+
+/**
+ * Discover all controllers in a directory.
+ *
+ * Scans `root` for files matching `include` (default: the `*.controller.*`
+ * convention) and dynamically imports each match to find `@Controller` classes.
+ *
+ * @remarks
+ * **Side-effect:** every matched module is `import()`ed, which runs its
+ * top-level code (including DI registration). See the module-level docs. Only
+ * files matching the convention are imported by default; pass
+ * `include: ['**‍/*.ts', '**‍/*.js']` to scan every source file instead.
+ *
+ * Imports run in parallel with a bounded concurrency cap
+ * ({@link IMPORT_CONCURRENCY}); results are aggregated deterministically in
+ * scan order regardless of import completion order.
+ *
+ * @param options - Discovery options
+ * @returns Array of discovery results (one per scanned file), in scan order
+ *
+ * @example
+ * ```typescript
+ * // Imports only *.controller.ts / *.controller.js files
+ * const controllers = await discoverControllers({
+ *   root: './src',
+ * });
+ * ```
+ */
+declare function discoverControllers(options: DiscoveryOptions): Promise<DiscoveryResult[]>;
+/**
+ * Get all controllers from discovery results
+ */
+declare function getControllersFromResults(results: DiscoveryResult[]): Function[];
+/**
+ * Get all errors from discovery results
+ */
+declare function getErrorsFromResults(results: DiscoveryResult[]): DiscoveryError[];
+
+/**
+ * @nextrush/controllers - ApplicationGraph IR (Immutable Intermediate Representation)
+ *
+ * RFC-NEXTRUSH-CLASS-CONSOLIDATION P3.4: Immutable IR that documents the
+ * bootstrap read-once, freeze-then-execute pattern.
+ *
+ * CRITICAL PROPERTY: All metadata is read ONCE at bootstrap time via Reflect
+ * and baked into the ApplicationGraph. The request-time handler execution path
+ * performs ZERO Reflect metadata reads — metadata is captured in the handler
+ * closure and precomputed data structures at build time.
+ *
+ * The graph captures per-controller:
+ * - Route metadata (method/path/params/guards/filters/interceptors/httpCode/headers)
+ * - Effective scope (singleton vs request-scoped) after dependency bubbling
+ * - Middleware and provider graph nodes
+ */
+
+/**
+ * ApplicationGraph IR: The immutable plan built once at bootstrap by reading
+ * Reflect metadata. Request-time execution reads ONLY from this graph.
+ *
+ * The graph is deep-frozen to enforce immutability and prevent accidental
+ * mutations that would break the boot-once guarantee.
+ *
+ * Structure:
+ * - routes: All BuiltRoute objects with precomputed handler closures
+ * - providers: DI provider metadata for request-scope bubble detection
+ * - requestScopedTokens: Set of provider tokens with request scope
+ */
+interface ApplicationGraph {
+    /** All built routes (precomputed at bootstrap, frozen) */
+    readonly routes: ReadonlyArray<BuiltRoute>;
+    /** Provider dependency map (Function → Function[]) */
+    readonly providers: ReadonlyMap<Function, ReadonlyArray<Function>>;
+    /** Tokens marked as request-scoped (require child container per request) */
+    readonly requestScopedTokens: ReadonlySet<Function>;
+}
+
+/**
+ * Diagnostics Report Types
+ *
+ * Opt-in diagnostics for @nextrush/class that capture ApplicationGraph IR
+ * metadata (routes, providers, duplicates, cycles, timings) for introspection
+ * and debugging.
+ *
+ * Zero-cost when disabled: no timing measurement, no report collection,
+ * no WeakMap storage when diagnostics: false (default).
+ */
+/**
+ * A single timing measurement from a bootstrap stage.
+ */
+interface TimingEntry {
+    /** Bootstrap stage name */
+    readonly stage: string;
+    /** Duration in milliseconds */
+    readonly ms: number;
+}
+/**
+ * A single route entry in the diagnostics report.
+ */
+interface RouteEntry {
+    /** HTTP method (GET, POST, etc.) */
+    readonly method: string;
+    /** Route path (with prefix applied) */
+    readonly path: string;
+    /** Controller class constructor */
+    readonly controller: Function;
+}
+/**
+ * A single provider entry in the diagnostics report.
+ */
+interface ProviderEntry {
+    /** Provider token (class constructor or symbol) */
+    readonly token: Function | Symbol;
+    /** Dependency tokens this provider depends on */
+    readonly dependencies: (Function | Symbol)[];
+}
+/**
+ * A duplicate route flagged during detection.
+ */
+interface DuplicateRoute {
+    /** HTTP method */
+    readonly method: string;
+    /** Route path */
+    readonly path: string;
+    /** Number of controllers registering this route */
+    readonly count: number;
+}
+/**
+ * A circular dependency cycle detected in the provider graph.
+ */
+interface CircularDependency {
+    /** Cycle path as array of provider tokens */
+    readonly cycle: ReadonlyArray<Function | Symbol>;
+}
+/**
+ * Diagnostics Report
+ *
+ * Captures ApplicationGraph IR state (routes, providers, duplicates, cycles)
+ * and bootstrap timings. Populated by collectDiagnostics() when
+ * options.diagnostics === true.
+ */
+interface DiagnosticsReport {
+    /** All registered routes */
+    readonly routes: ReadonlyArray<RouteEntry>;
+    /** All providers in the DI graph */
+    readonly providers: ReadonlyArray<ProviderEntry>;
+    /** Routes registered more than once (method + path collision) */
+    readonly duplicateRoutes: ReadonlyArray<DuplicateRoute>;
+    /** Circular dependencies detected in provider graph */
+    readonly circularDependencies: ReadonlyArray<CircularDependency>;
+    /** Bootstrap stage timings */
+    readonly timings: ReadonlyArray<TimingEntry>;
+}
+
+/**
+ * Public API for retrieving diagnostics reports
+ *
+ * Wrapper over the internal WeakMap storage to provide a clean public interface.
+ */
+
+/**
+ * Retrieve the diagnostics report for an application.
+ *
+ * Returns undefined if diagnostics were not enabled during registration
+ * (diagnostics: false or not specified in options).
+ *
+ * @param app The application instance
+ * @returns Diagnostics report if enabled, undefined otherwise
+ */
+declare function getClassDiagnostics(app: Application): DiagnosticsReport | undefined;
+
+/**
+ * @nextrush/controllers - Controller Registry
+ *
+ * Manages registration and tracking of controllers.
+ */
+
+/**
+ * Registry for tracking and building controller routes
+ */
+declare class ControllerRegistry {
+    private readonly controllers;
+    private readonly container;
+    private readonly globalPrefix;
+    private readonly globalMiddleware;
+    private readonly debug;
+    /**
+     * Classes whose effective DI scope is `'request'` (self or dependency graph
+     * declares `scope: 'request'`). A request-scoped controller is registered with
+     * the request lifecycle and resolved from a per-request child on every request
+     * instead of being memoized. Empty by default (pure singleton/transient graph).
+     */
+    private readonly requestScopedClasses;
+    /**
+     * Shared controller-instance cache, keyed by controller class.
+     *
+     * Owned by the registry so a single resolved singleton is reused across the
+     * boot-time eager validation (`validateControllers`) and the per-request
+     * handlers built by {@link buildRoutes}. Without a shared cache, `validate: true`
+     * resolves each controller twice: once at boot and again on the first request.
+     *
+     * A failed resolve is never stored, so resolution retries on each request until
+     * it succeeds (see `createRouteHandler` in `builder.ts`).
+     */
+    private readonly instanceCache;
+    constructor(container: Container, globalPrefix: string, globalMiddleware: Middleware[], debug: boolean, requestScopedClasses?: ReadonlySet<Function>);
+    /**
+     * Register a controller class
+     */
+    register(controllerClass: Function): RegisteredController;
+    /**
+     * The shared controller-instance cache.
+     *
+     * Exposed so `registerControllers` can pre-seed it during eager validation
+     * (`validate: true`), making the boot-time resolve and the per-request handler
+     * share one singleton instead of resolving the same controller twice.
+     */
+    get instances(): Map<Function, unknown>;
+    /**
+     * Register multiple controllers
+     */
+    registerAll(controllers: Function[]): RegisteredController[];
+    /**
+     * Get all registered controllers
+     */
+    getAll(): RegisteredController[];
+    /**
+     * Get all built routes from all controllers
+     */
+    getAllRoutes(): BuiltRoute[];
+    /**
+     * Get total route count
+     */
+    get routeCount(): number;
+    /**
+     * Check if a controller is registered
+     */
+    has(controllerClass: Function): boolean;
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+    /**
+     * Register the controller in the DI container with its effective scope: a
+     * request-effective controller (self or dependency graph declares
+     * `scope: 'request'`) uses the request (ContainerScoped) lifecycle so a fresh
+     * instance is built per request; every other controller stays a singleton.
+     */
+    private registerInContainer;
+    /**
+     * Log controller registration details
+     */
+    private logRegistration;
+}
+
+/**
+ * @nextrush/controllers - Handler Builder
+ *
+ * Builds route handlers from controller methods with parameter injection.
+ * Orchestrates path construction, middleware resolution, and route metadata,
+ * delegating per-route handler creation to {@link createRouteHandler}.
+ */
+
+/**
+ * Build route handlers for a controller.
+ *
+ * @param instanceCache - Shared controller-instance cache (keyed by controller
+ *   class). Handlers read-or-populate it so a controller singleton is resolved
+ *   exactly once across boot-time validation and all requests. Defaults to a
+ *   fresh per-call map when omitted (standalone use), preserving lazy resolution.
+ */
+declare function buildRoutes(definition: ControllerDefinition, container: Container, globalPrefix: string, globalMiddleware: Middleware[], instanceCache?: Map<Function, unknown>, isRequestScoped?: boolean): BuiltRoute[];
+
+export { All, type ApplicationGraph, Body, type BodyOptions, type BuiltRoute, type CanActivate, Catch, type CircularDependency, type Constructor, Controller, type ControllerDefinition, ControllerError, type ControllerMetadata, type ControllerOptions, ControllerRegistry, ControllerResolutionError, type ControllerRouteMetadata, type ControllersOptions, Ctx, type CustomParamExtractor, DECORATOR_METADATA_KEYS, Delete, type DiagnosticsReport, DiscoveryError, type DiscoveryOptions, type DiscoveryResult, type DiscoverySource, type DuplicateRoute, type ExceptionFilter, type ExceptionFilterClass, FilesystemSource, type FilterMetadata, Get, type Guard, type GuardContext, type GuardFn, type GuardMetadata, GuardRejectionError, Head, Header, type HeaderOptions, HttpCode, type Interceptor, type InterceptorClass, type InterceptorMetadata, MemorySource, type MiddlewareRef, MissingParameterError, Module, type ModuleMetadata, type ModuleOptions, type ModuleProvider, type ModuleProviderConfig, type ModuleRegistrationOptions, NoRoutesError, NotAControllerError, NotAModuleError, type OnInit, type OnShutdown, Options, Param, type ParamMetadata, type ParamOptions, type ParamSource, ParameterInjectionError, Patch, Post, type ProviderEntry, Put, Query, type QueryOptions, Redirect, type RedirectMetadata, type RegisteredController, Req, Res, type ResolvedOptions, type ResponseHeaderMetadata, type RouteEntry, type RouteMetadata, type RouteMethods, type RouteOptions, RouteRegistrationError, SetHeader, type TimingEntry, type TransformFn, UseFilter, UseGuard, UseInterceptor, buildRoutes, collectModuleControllers, collectModuleGraph, createCustomParamDecorator, discoverControllers, getAllFilters, getAllGuards, getAllInterceptors, getAllParamMetadata, getCatchTypes, getClassDiagnostics, getClassFilters, getClassGuards, getClassInterceptors, getConstructorParamTypes, getControllerDefinition, getControllerMetadata, getControllersFromResults, getErrorsFromResults, getHttpCode, getMethodFilters, getMethodGuards, getMethodInterceptors, getModuleMetadata, getParamMetadata, getRedirectMetadata, getResponseHeaders, getRouteMetadata, isController, isGuardClass, isModule, isOnInit, isOnShutdown, isValidHttpMethod, isValidParamSource, registerControllers, registerModule };