@celerity-sdk/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,49 +1,195 @@
-import { Schema, Type, CelerityLayer, InjectionToken, ModuleMetadata, HandlerContext, HandlerResponse, HandlerMetadata, ServiceContainer, Provider, HttpRequest, HttpResponse, FunctionHandlerDefinition, HttpMethod, CelerityLogger } from '@celerity-sdk/types';
-export { CelerityLayer, FunctionHandlerDefinition, HandlerContext, HandlerMetadata, HandlerResponse, HttpMethod, HttpRequest, HttpResponse, InjectionToken, ModuleMetadata, Provider, Schema, ServiceContainer, Type } from '@celerity-sdk/types';
-import { Request, Response } from '@celerity-sdk/runtime';
+import { Schema, Type, CelerityLayer, InjectionToken, ModuleMetadata, WebSocketEventType, BaseHandlerContext, HandlerType, HandlerMetadata, ServiceContainer, Provider, HttpMethod, HttpRequest, HttpResponse, WebSocketMessage, ConsumerEventInput, EventResult, ScheduleEventInput as ScheduleEventInput$1, MessageAttributes, WebSocketMessageType, CelerityLogger, FunctionHandlerDefinition, GuardDefinition, WebSocketHandlerContext, ConsumerHandlerContext, ScheduleHandlerContext, WebSocketSender, WebSocketSendOptions } from '@celerity-sdk/types';
+export { BaseHandlerContext, BucketEvent, BucketEventType, CelerityLayer, CelerityLogger, ConsumerEventInput, ConsumerHandlerContext, ConsumerMessage, DatastoreEvent, DatastoreEventType, EventResult, FunctionHandlerDefinition, GuardDefinition, GuardHandlerContext, GuardHandlerRequest, HandlerMetadata, HandlerResponse, HandlerType, HttpHandlerContext, HttpMethod, HttpRequest, HttpResponse, InjectionToken, MessageProcessingFailure, ModuleMetadata, NextFunction, Provider, ScheduleEventInput, ScheduleHandlerContext, Schema, ServiceContainer, SourceType, Type, ValidatedConsumerMessage, WebSocketEventType, WebSocketHandlerContext, WebSocketMessage, WebSocketMessageType, WebSocketRequestContext, WebSocketSendOptions, WebSocketSender } from '@celerity-sdk/types';
+import { CoreWebSocketRegistry, JsConsumerEventInput, Request, JsScheduleEventInput, JsEventResult, Response, JsWebSocketMessageInfo } from '@celerity-sdk/runtime';
+export { CoreWebSocketRegistry, JsConsumerEventInput, JsEventResult, JsScheduleEventInput, JsWebSocketMessageInfo } from '@celerity-sdk/runtime';
+export { INJECT_METADATA, USE_RESOURCE_METADATA } from '@celerity-sdk/common';
 
 type ControllerMetadata = {
     prefix?: string;
 };
+/**
+ * Marks a class as a controller — the general-purpose class decorator for
+ * handler classes. The class becomes injectable and its decorated methods are
+ * registered as handler callbacks. A single controller can mix handler types:
+ *
+ * - **HTTP handlers** — `@Get()`, `@Post()`, `@Put()`, `@Patch()`, `@Delete()`,
+ *   `@Head()`, `@Options()` method decorators define HTTP routes.
+ * - **Schedule handlers** — `@ScheduleHandler()` is a cross-cutting method
+ *   decorator that works on any controller type, including `@Controller`.
+ * - **Custom / invocable handlers** — `@Invoke("name")` registers a method as
+ *   a programmatically invocable endpoint.
+ *
+ * @param prefix - Optional path prefix prepended to all HTTP route paths
+ *   defined by method decorators within this controller. Uses `{param}` format
+ *   for path parameters (matching blueprint conventions, not Express `:param`).
+ *   Has no effect on schedule or invocable handler methods.
+ *
+ * @example
+ * ```ts
+ * // HTTP controller
+ * @Controller("/users")
+ * class UserController {
+ *   @Get("/{id}")
+ *   async getUser(@Param("id") id: string): Promise<HandlerResponse> { ... }
+ * }
+ *
+ * // Schedule-only controller
+ * @Controller()
+ * class MaintenanceTasks {
+ *   @ScheduleHandler("daily-cleanup")
+ *   async cleanup(): Promise<EventResult> { ... }
+ * }
+ *
+ * // Mixed: HTTP routes + scheduled tasks + invocable methods
+ * @Controller("/admin")
+ * class AdminController {
+ *   @Get("/reports")
+ *   async listReports(): Promise<HandlerResponse> { ... }
+ *
+ *   @ScheduleHandler("weekly-report")
+ *   async generateWeeklyReport(): Promise<EventResult> { ... }
+ *
+ *   @Invoke("reprocessOrders")
+ *   async reprocess(@Payload() payload: unknown): Promise<unknown> { ... }
+ * }
+ * ```
+ */
 declare function Controller(prefix?: string): ClassDecorator;
 
+/**
+ * Registers an HTTP GET handler. The method should return `HandlerResponse`.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ *   Uses `{param}` format for path parameters.
+ */
 declare function Get(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP POST handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Post(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP PUT handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Put(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP PATCH handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Patch(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP DELETE handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Delete(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP HEAD handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Head(path?: string): MethodDecorator;
+/**
+ * Registers an HTTP OPTIONS handler.
+ *
+ * @param path - Route path relative to the controller prefix. Defaults to `/`.
+ */
 declare function Options(path?: string): MethodDecorator;
 
-type ParamType = "body" | "query" | "param" | "headers" | "auth" | "request" | "cookies" | "requestId";
+type ParamType = "body" | "query" | "param" | "headers" | "auth" | "token" | "request" | "cookies" | "requestId" | "connectionId" | "messageBody" | "messageId" | "requestContext" | "eventType" | "messages" | "consumerEvent" | "consumerVendor" | "consumerTraceContext" | "scheduleInput" | "scheduleId" | "scheduleExpression" | "scheduleEvent" | "payload" | "invokeContext";
 type ParamMetadata = {
     index: number;
     type: ParamType;
     key?: string;
     schema?: Schema;
 };
+/**
+ * Injects the parsed JSON request body into a handler parameter.
+ * The raw `textBody` is JSON-parsed automatically; returns `null` if empty.
+ *
+ * @param schema - Optional Zod-compatible schema (`{ parse(data): T }`) for
+ *   body validation. When provided, the parsed body is passed through
+ *   `schema.parse()` before injection.
+ */
 declare function Body(schema?: Schema): ParameterDecorator;
+/**
+ * Injects query string parameters into a handler parameter.
+ *
+ * - `@Query()` — injects the full query object (`Record<string, string | string[]>`)
+ * - `@Query("key")` — injects a single query parameter value
+ * - `@Query(schema)` — injects the full query object, validated through `schema.parse()`
+ * - `@Query("key", schema)` — injects a single value, validated through `schema.parse()`
+ */
 declare function Query(): ParameterDecorator;
 declare function Query(key: string): ParameterDecorator;
 declare function Query(schema: Schema): ParameterDecorator;
 declare function Query(key: string, schema: Schema): ParameterDecorator;
+/**
+ * Injects path parameters into a handler parameter. Path params use `{param}`
+ * format in route definitions (matching blueprint conventions).
+ *
+ * - `@Param()` — injects the full path params object (`Record<string, string>`)
+ * - `@Param("id")` — injects a single path parameter value
+ * - `@Param(schema)` — injects the full params object, validated through `schema.parse()`
+ * - `@Param("id", schema)` — injects a single value, validated through `schema.parse()`
+ */
 declare function Param(): ParameterDecorator;
 declare function Param(key: string): ParameterDecorator;
 declare function Param(schema: Schema): ParameterDecorator;
 declare function Param(key: string, schema: Schema): ParameterDecorator;
+/**
+ * Injects request headers into a handler parameter.
+ *
+ * - `@Headers()` — injects the full headers object (`Record<string, string | string[]>`)
+ * - `@Headers("content-type")` — injects a single header value
+ * - `@Headers(schema)` — injects the full headers object, validated through `schema.parse()`
+ * - `@Headers("key", schema)` — injects a single value, validated through `schema.parse()`
+ */
 declare function Headers(): ParameterDecorator;
 declare function Headers(key: string): ParameterDecorator;
 declare function Headers(schema: Schema): ParameterDecorator;
 declare function Headers(key: string, schema: Schema): ParameterDecorator;
+/**
+ * Injects the decoded auth payload from the request. This is the identity
+ * object populated by guards (e.g. decoded JWT claims), or `null` if the
+ * request is unauthenticated.
+ */
 declare function Auth(): ParameterDecorator;
+/**
+ * Injects the raw auth token string from the request (e.g. the Bearer token
+ * from the Authorization header). This is the unprocessed token before guard
+ * validation — use `@Auth()` for the decoded identity payload.
+ */
+declare function Token(): ParameterDecorator;
+/**
+ * Injects the full `HttpRequest` object into a handler parameter. Use this
+ * when you need access to the entire request beyond what individual param
+ * decorators provide.
+ */
 declare function Req(): ParameterDecorator;
+/**
+ * Injects request cookies into a handler parameter.
+ *
+ * - `@Cookies()` — injects the full cookies object (`Record<string, string>`)
+ * - `@Cookies("session")` — injects a single cookie value
+ */
 declare function Cookies(key?: string): ParameterDecorator;
+/**
+ * Injects the unique request ID assigned to this request by the runtime
+ * or API Gateway.
+ */
 declare function RequestId(): ParameterDecorator;
 
 /**
- * Marks a handler class as a custom guard implementation.
- * The handler IS the guard — in serverless it becomes a Lambda Authorizer,
- * in containers the Rust runtime invokes it before protected handlers.
+ * Marks a class as a custom guard implementation.
+ * The class must have a `check()` method that the runtime invokes before protected handlers.
+ *
+ * In serverless mode, the guard becomes a Lambda Authorizer.
+ * In container mode, the Rust runtime invokes it via `registerGuardHandler`.
  *
  * Other handlers reference this guard via `@ProtectedBy("name")`.
  */
@@ -60,26 +206,476 @@ declare function ProtectedBy(name: string): (target: object, propertyKey?: strin
  */
 declare function Public(): MethodDecorator;
 
+/**
+ * Attaches one or more layers to a controller class or individual method.
+ * Layers run in declaration order (top-to-bottom) as middleware around the
+ * handler, composing into the pipeline: `[system] → [app] → [handler layers]`.
+ *
+ * Can be applied at class level (all methods) or method level. Class-level
+ * layers run before method-level layers. Accepts both layer instances and
+ * layer classes (which are resolved from the DI container).
+ *
+ * @param layers - Layer instances or layer class constructors to attach.
+ *
+ * @example
+ * ```ts
+ * @Controller("/orders")
+ * @UseLayer(LoggingLayer, AuthLayer)
+ * class OrderController {
+ *   @Get("/{id}")
+ *   @UseLayer(new CacheLayer({ ttl: 60 }))
+ *   async getOrder(@Param("id") id: string) { ... }
+ * }
+ * ```
+ */
 declare function UseLayer(...layers: (Type<CelerityLayer> | CelerityLayer)[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Array-based variant of `@UseLayer()`. Accepts layers as an array instead
+ * of rest parameters — useful when layers are composed programmatically.
+ */
 declare function UseLayers(layers: (Type<CelerityLayer> | CelerityLayer)[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
 
+/**
+ * Declares that a handler or controller uses one or more blueprint-defined
+ * infrastructure resources. Used by the CLI extraction pipeline to emit
+ * `celerity.handler.resource.ref` annotations for handler-to-resource linking.
+ *
+ * When there is only one resource of a given type in the blueprint, the Go CLI
+ * can auto-link via DI inference. `@UseResource` is needed to disambiguate
+ * when multiple resources of the same type exist.
+ *
+ * Can be applied at class level (default for all methods) or method level
+ * (additional resources for that handler). Multiple decorators accumulate.
+ *
+ * @param resourceNames - One or more blueprint resource names.
+ *
+ * @example
+ * ```ts
+ * @Controller("/orders")
+ * @UseResource("ordersBucket")
+ * class OrderController {
+ *   @Get("/{id}")
+ *   @UseResource("ordersCache")
+ *   async getOrder(@Param("id") id: string) { ... }
+ *
+ *   @Post("/")
+ *   async createOrder(@Body() body: CreateOrderDto) { ... }
+ * }
+ * ```
+ */
+declare function UseResource(...resourceNames: string[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Array-based variant of `@UseResource()`. Accepts resource names as an array
+ * instead of rest parameters — useful when resource names are composed
+ * programmatically.
+ */
+declare function UseResources(resourceNames: string[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+
+/**
+ * Attaches custom key-value metadata to a controller class or method.
+ * Metadata is accessible to guards and layers via
+ * `context.metadata.get(key)` at runtime.
+ *
+ * Multiple `@SetMetadata` decorators accumulate on the same target.
+ * Method-level metadata is merged with (and overrides) class-level metadata.
+ *
+ * @param key - Metadata key.
+ * @param value - Metadata value (any serializable type).
+ *
+ * @example
+ * ```ts
+ * @Controller("/admin")
+ * @SetMetadata("roles", ["admin"])
+ * class AdminController {
+ *   @Get("/")
+ *   @SetMetadata("action", "admin:list")
+ *   async list() { ... }
+ * }
+ * ```
+ */
 declare function SetMetadata(key: string, value: unknown): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Shorthand for `@SetMetadata("action", value)`. Sets the `action` metadata
+ * key, commonly used by guards to determine authorization rules.
+ */
 declare function Action(value: unknown): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
 
+/**
+ * Marks a class as injectable into the DI container. Required for any class
+ * that should be resolved as a dependency — services, repositories, etc.
+ *
+ * Controller and handler decorators (`@Controller`, `@WebSocketController`,
+ * `@Consumer`, `@Guard`) set this automatically, so `@Injectable()` is only
+ * needed for non-handler service classes.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class OrderService {
+ *   constructor(private db: DatabaseClient) {}
+ * }
+ * ```
+ */
 declare function Injectable(): ClassDecorator;
+/**
+ * Overrides the DI token for a constructor parameter. By default the container
+ * resolves dependencies using the class type from `emitDecoratorMetadata`. Use
+ * `@Inject()` when you need to inject by a symbol, string token, or abstract
+ * class that differs from the declared parameter type.
+ *
+ * @param token - The DI token (class, symbol, or string) to resolve.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class OrderService {
+ *   constructor(@Inject(DB_TOKEN) private db: DatabaseClient) {}
+ * }
+ * ```
+ */
 declare function Inject(token: InjectionToken): ParameterDecorator;
 
+/**
+ * Declares a module — the organizational unit for grouping controllers,
+ * providers, function handlers, and sub-modules. The root module is the
+ * entry point for bootstrapping the application.
+ *
+ * @param metadata - Module configuration including:
+ *   - `imports` — sub-modules to compose into this module's scope
+ *   - `controllers` — handler classes (`@Controller`, `@WebSocketController`, `@Consumer`, etc.)
+ *   - `providers` — DI providers (classes, factories, or values)
+ *   - `functionHandlers` — function-based handler definitions
+ *   - `guards` — guard classes or definitions
+ *   - `layers` — application-level layers applied to all handlers in this module
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   imports: [DatabaseModule],
+ *   controllers: [UserController, OrderConsumer],
+ *   providers: [UserService, OrderService],
+ * })
+ * class AppModule {}
+ * ```
+ */
 declare function Module(metadata: ModuleMetadata): ClassDecorator;
 
+type WebSocketEventMetadata = {
+    eventType: WebSocketEventType;
+    route: string;
+};
+/**
+ * Marks a class as a WebSocket controller. The class becomes injectable and
+ * its `@OnConnect()`, `@OnMessage()`, and `@OnDisconnect()` methods are
+ * registered as WebSocket handler callbacks.
+ *
+ * @example
+ * ```ts
+ * @WebSocketController()
+ * class ChatHandler {
+ *   @OnMessage("chat")
+ *   async onChat(@ConnectionId() id: string, @MessageBody() body: unknown): Promise<void> { ... }
+ * }
+ * ```
+ */
+declare function WebSocketController(): ClassDecorator;
+/**
+ * Handles WebSocket connection events. Invoked when a client establishes a
+ * new WebSocket connection. Registered with the fixed route `$connect`.
+ */
+declare function OnConnect(): MethodDecorator;
+/**
+ * Handles WebSocket message events. Invoked when a connected client sends
+ * a message.
+ *
+ * @param route - Optional route key for message dispatching. Defaults to
+ *   `$default` which catches all messages not matched by a specific route.
+ *   Custom routes enable action-based routing (e.g. `"chat"`, `"ping"`).
+ */
+declare function OnMessage(route?: string): MethodDecorator;
+/**
+ * Handles WebSocket disconnection events. Invoked when a client disconnects.
+ * Registered with the fixed route `$disconnect`.
+ */
+declare function OnDisconnect(): MethodDecorator;
+
+/**
+ * Injects the WebSocket connection ID into a handler parameter.
+ * This is the unique identifier for the client's connection, used to send
+ * messages back via `WebSocketSender.sendMessage(connectionId, data)`.
+ */
+declare function ConnectionId(): ParameterDecorator;
+/**
+ * Injects the parsed message body from a WebSocket message event.
+ * Returns the `jsonBody` field from the `WebSocketMessage`.
+ *
+ * @param schema - Optional Zod-compatible schema (`{ parse(data): T }`) for
+ *   body validation. When provided, the body is passed through
+ *   `schema.parse()` before injection.
+ */
+declare function MessageBody(schema?: Schema): ParameterDecorator;
+/**
+ * Injects the unique message ID from a WebSocket message event.
+ */
+declare function MessageId(): ParameterDecorator;
+/**
+ * Injects the `WebSocketRequestContext` from the connection handshake.
+ * Contains request metadata from the initial HTTP upgrade: request ID,
+ * path, headers, query params, cookies, client IP, and auth payload.
+ */
+declare function RequestContext(): ParameterDecorator;
+/**
+ * Injects the WebSocket event type: `"connect"`, `"message"`, or
+ * `"disconnect"`. Useful when a single method handles multiple event types.
+ */
+declare function EventType(): ParameterDecorator;
+
+type ConsumerMetadata = {
+    sourceId?: string;
+};
+type ConsumerHandlerMetadata = {
+    route?: string;
+};
+/**
+ * Marks a class as a consumer controller that processes batches of messages
+ * from an event source (SQS, Kafka, Pub/Sub, etc.).
+ *
+ * The class becomes injectable and its `@MessageHandler()` methods are
+ * registered as consumer handler callbacks.
+ *
+ * @param sourceId - Optional annotation hint that tells the deploy engine
+ *   which blueprint-defined consumer source this handler should be wired to.
+ *   Does not create infrastructure — the blueprint defines the actual source.
+ *
+ * @example
+ * ```ts
+ * @Consumer("orders-queue")
+ * class OrderConsumer {
+ *   @MessageHandler()
+ *   async process(@Messages(OrderSchema) messages: ValidatedConsumerMessage<Order>[]): Promise<EventResult> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+declare function Consumer(sourceId?: string): ClassDecorator;
+/**
+ * Marks a method inside a `@Consumer()` class as a message handler.
+ *
+ * The method should return `Promise<EventResult>` with partial failure
+ * semantics — individual message failures are reported via `failures[]`
+ * without failing the entire batch.
+ *
+ * @param route - Optional routing key for message dispatching. The CLI
+ *   extracts this as `celerity.handler.consumer.route` and the deploy engine
+ *   merges it into the consumer source's routing configuration. The blueprint
+ *   can override. When omitted, the method name is used as the handler tag.
+ */
+declare function MessageHandler(route?: string): MethodDecorator;
+
+/**
+ * Injects the message batch into a `@MessageHandler()` method parameter.
+ *
+ * - **Without a schema:** injects `ConsumerMessage[]` with raw `body: string`
+ *   fields. The handler is responsible for parsing each message body.
+ * - **With a schema:** the pipeline JSON-parses each `msg.body` and runs
+ *   `schema.parse()`. Messages that pass validation are injected as
+ *   `ValidatedConsumerMessage<T>[]` with a typed `parsedBody` field. Messages
+ *   that fail JSON parsing or schema validation are excluded from the batch
+ *   and automatically reported as `MessageProcessingFailure` entries, merged
+ *   into the handler's returned `EventResult`.
+ *
+ * @param schema - Optional Zod-compatible schema (`{ parse(data): T }`) for
+ *   per-message body validation.
+ */
+declare function Messages(schema?: Schema): ParameterDecorator;
+/**
+ * Injects the full `ConsumerEventInput` envelope into a `@MessageHandler()`
+ * method parameter. This includes the raw message batch, handler tag, vendor
+ * metadata, and trace context.
+ *
+ * Use this when you need access to the entire event beyond just the messages —
+ * for example, to inspect `vendor` metadata or `traceContext`. Analogous to
+ * `@Req()` for HTTP handlers.
+ */
+declare function EventInput(): ParameterDecorator;
+/**
+ * Injects the vendor-specific metadata from the consumer event. This is the
+ * platform-specific envelope data (e.g. SQS event source ARN, Kafka topic
+ * metadata) — not the per-message vendor attributes.
+ *
+ * Equivalent to `event.vendor` from `@EventInput()`.
+ */
+declare function Vendor(): ParameterDecorator;
+/**
+ * Injects the trace context from the consumer event, if present.
+ *
+ * Returns `Record<string, string>` containing W3C Trace Context headers
+ * (e.g. `traceparent`) and platform-specific trace IDs, or `null` if no
+ * trace context was propagated.
+ */
+declare function ConsumerTraceContext(): ParameterDecorator;
+
+type ScheduleHandlerMetadata = {
+    scheduleId?: string;
+    schedule?: string;
+};
+type ScheduleHandlerOptions = {
+    scheduleId?: string;
+    schedule?: string;
+};
+/**
+ * Marks a method as a schedule handler — a task triggered by a time-based
+ * schedule (EventBridge rule, Cloud Scheduler, etc.).
+ *
+ * This is a **cross-cutting** method decorator that works on any controller
+ * type (`@Controller`, `@WebSocketController`, `@Consumer`). There is no
+ * `@ScheduleController` class decorator — schedule-only classes use
+ * `@Controller()`.
+ *
+ * The method should return `Promise<EventResult>` to report success/failure.
+ *
+ * @param arg - Optional string or options object. String parsing:
+ *   - No args → fully blueprint-driven (no annotations)
+ *   - String with `rate(` or `cron(` prefix → `schedule` expression annotation
+ *   - String without prefix → `scheduleId` annotation hint for deploy engine
+ *   - Object → explicit `{ scheduleId?, schedule? }`
+ *
+ * @example
+ * ```ts
+ * @Controller()
+ * class MaintenanceTasks {
+ *   @ScheduleHandler("daily-cleanup")
+ *   async cleanup(@ScheduleInput() input: unknown): Promise<EventResult> {
+ *     // scheduleId hint — blueprint defines the actual schedule
+ *   }
+ *
+ *   @ScheduleHandler("rate(1 day)")
+ *   async sync(): Promise<EventResult> {
+ *     // schedule expression annotation — blueprint can override
+ *   }
+ *
+ *   @ScheduleHandler({ scheduleId: "weekly-report", schedule: "cron(0 9 ? * MON *)" })
+ *   async report(): Promise<EventResult> {
+ *     // explicit object with both fields
+ *   }
+ * }
+ * ```
+ */
+declare function ScheduleHandler(): MethodDecorator;
+declare function ScheduleHandler(scheduleIdOrExpression: string): MethodDecorator;
+declare function ScheduleHandler(options: ScheduleHandlerOptions): MethodDecorator;
+
+/**
+ * Injects the schedule event's `input` payload into a `@ScheduleHandler()`
+ * method parameter.
+ *
+ * - **Without a schema:** injects the raw `event.input` as `unknown`.
+ * - **With a schema:** the pipeline validates `event.input` through
+ *   `schema.parse()` before the handler runs. If validation fails, the
+ *   handler is not invoked and the pipeline returns
+ *   `{ success: false, errorMessage }`.
+ *
+ * @param schema - Optional Zod-compatible schema (`{ parse(data): T }`) for
+ *   input validation.
+ */
+declare function ScheduleInput(schema?: Schema): ParameterDecorator;
+/**
+ * Injects the schedule ID from the event into a `@ScheduleHandler()`
+ * method parameter. This is the identifier of the schedule rule that
+ * triggered the handler (e.g. `"daily-cleanup"`).
+ */
+declare function ScheduleId(): ParameterDecorator;
+/**
+ * Injects the schedule expression from the event into a `@ScheduleHandler()`
+ * method parameter. This is the actual schedule expression that triggered
+ * the handler (e.g. `"rate(1 day)"` or `"cron(0 9 * * *)"`).
+ */
+declare function ScheduleExpression(): ParameterDecorator;
+/**
+ * Injects the full `ScheduleEventInput` envelope into a `@ScheduleHandler()`
+ * method parameter. This includes the schedule ID, expression, message ID,
+ * input payload, vendor metadata, and trace context.
+ *
+ * Use this when you need access to the entire event beyond just the input —
+ * analogous to `@Req()` for HTTP handlers or `@EventInput()` for consumers.
+ */
+declare function ScheduleEventInput(): ParameterDecorator;
+
+type InvokeMetadata = {
+    name: string;
+};
+/**
+ * Marks a method as a custom/invocable handler — a programmatic invocation
+ * endpoint identified by name, callable via `app.invokeHandler(name, payload)`
+ * or the runtime's `/runtime/handlers/invoke` endpoint.
+ *
+ * This is a **cross-cutting** method decorator that works on any controller
+ * type (`@Controller`, `@WebSocketController`, `@Consumer`). A single class
+ * can mix HTTP routes, scheduled tasks, and invocable methods.
+ *
+ * @param name - The handler name used for invocation lookup. Must be unique
+ *   across all registered custom handlers.
+ *
+ * @example
+ * ```ts
+ * // Standalone invocable handler
+ * @Controller()
+ * class PaymentHandlers {
+ *   @Invoke("processPayment")
+ *   async process(@Payload(PaymentSchema) payload: PaymentInput): Promise<PaymentResult> {
+ *     return this.paymentService.process(payload);
+ *   }
+ * }
+ *
+ * // Mixed: HTTP routes + invocable methods
+ * @Controller("/payments")
+ * class PaymentController {
+ *   @Get("/{id}")
+ *   async getPayment(@Param("id") id: string): Promise<HandlerResponse> { ... }
+ *
+ *   @Invoke("processPayment")
+ *   async processPayment(@Payload(PaymentSchema) payload: PaymentInput): Promise<PaymentResult> {
+ *     return this.paymentService.process(payload);
+ *   }
+ * }
+ * ```
+ */
+declare function Invoke(name: string): MethodDecorator;
+
+/**
+ * Injects the invocation payload into an `@Invoke()` method parameter.
+ *
+ * - **Without a schema:** injects the raw payload as `unknown`. The handler
+ *   is responsible for any validation.
+ * - **With a schema:** the pipeline validates the payload through
+ *   `schema.parse()` before the handler runs. If validation fails, the
+ *   error is re-thrown to the caller.
+ *
+ * @param schema - Optional Zod-compatible schema (`{ parse(data): T }`) for
+ *   payload validation.
+ */
+declare function Payload(schema?: Schema): ParameterDecorator;
+/**
+ * Injects the `BaseHandlerContext` into an `@Invoke()` method parameter.
+ * Provides access to the handler metadata store, DI container, and
+ * optional request-scoped logger.
+ */
+declare function InvokeContext(): ParameterDecorator;
+
 type ValidationSchemas = {
     body?: Schema;
     params?: Schema;
     query?: Schema;
     headers?: Schema;
+    wsMessageBody?: Schema;
+    consumerMessage?: Schema;
+    scheduleInput?: Schema;
+    customPayload?: Schema;
 };
-declare function validate(schemas: ValidationSchemas): CelerityLayer;
+declare function validate(schemas: ValidationSchemas): CelerityLayer<BaseHandlerContext>;
 
-declare function runLayerPipeline(layers: (CelerityLayer | Type<CelerityLayer>)[], context: HandlerContext, handler: () => Promise<HandlerResponse>): Promise<HandlerResponse>;
+declare function runLayerPipeline<TContext extends BaseHandlerContext>(layers: (CelerityLayer<TContext> | Type<CelerityLayer<TContext>>)[], context: TContext, handler: () => Promise<unknown>, handlerType?: HandlerType): Promise<unknown>;
 
 declare function createDefaultSystemLayers(): Promise<CelerityLayer[]>;
 
@@ -152,61 +748,78 @@ declare function getProviderDependencyTokens(provider: Provider<any>): Injection
 declare const APP_CONFIG: unique symbol;
 declare const RUNTIME_APP: unique symbol;
 
-type ResolvedHandler = {
+type ResolvedHandlerBase = {
     id?: string;
-    path?: string;
-    method?: string;
-    protectedBy: string[];
-    layers: (CelerityLayer | Type<CelerityLayer>)[];
-    isPublic: boolean;
-    paramMetadata: ParamMetadata[];
-    customMetadata: Record<string, unknown>;
     handlerFn: (...args: unknown[]) => unknown;
     handlerInstance?: object;
     isFunctionHandler?: boolean;
     injectTokens?: InjectionToken[];
+    layers: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    paramMetadata: ParamMetadata[];
+    customMetadata: Record<string, unknown>;
 };
-type PipelineOptions = {
-    container: ServiceContainer;
-    systemLayers?: (CelerityLayer | Type<CelerityLayer>)[];
-    appLayers?: (CelerityLayer | Type<CelerityLayer>)[];
+type GuardableFields = {
+    protectedBy: string[];
+    isPublic: boolean;
 };
-declare function executeHandlerPipeline(handler: ResolvedHandler, request: HttpRequest, options: PipelineOptions): Promise<HttpResponse>;
-
-type ModuleNode = {
-    moduleClass: Type;
-    ownTokens: Set<InjectionToken>;
-    exports: Set<InjectionToken>;
-    imports: Type[];
-    controllers: Type[];
-    functionHandlers: FunctionHandlerDefinition[];
-    providers: (Type | (Provider & {
-        provide: InjectionToken;
-    }))[];
+type ResolvedHttpHandler = ResolvedHandlerBase & GuardableFields & {
+    type: "http";
+    path?: string;
+    method?: HttpMethod;
+};
+type ResolvedWebSocketHandler = ResolvedHandlerBase & GuardableFields & {
+    type: "websocket";
+    route: string;
+};
+type ResolvedConsumerHandler = ResolvedHandlerBase & {
+    type: "consumer";
+    handlerTag: string;
+};
+type ResolvedScheduleHandler = ResolvedHandlerBase & {
+    type: "schedule";
+    handlerTag: string;
+};
+type ResolvedCustomHandler = ResolvedHandlerBase & {
+    type: "custom";
+    name: string;
+};
+type ResolvedHandler = ResolvedHttpHandler | ResolvedWebSocketHandler | ResolvedConsumerHandler | ResolvedScheduleHandler | ResolvedCustomHandler;
+type ResolvedGuard = {
+    name: string;
+    handlerFn: (...args: unknown[]) => unknown;
+    handlerInstance?: object;
+    paramMetadata: ParamMetadata[];
+    customMetadata: Record<string, unknown>;
+    injectTokens?: InjectionToken[];
+    isFunctionGuard?: boolean;
 };
-type ModuleGraph = Map<Type, ModuleNode>;
-/**
- * Builds a module graph by walking the module tree depth-first, collecting
- * all metadata into a graph structure without any side effects.
- *
- * Detects circular module imports and deduplicates visited modules.
- */
-declare function buildModuleGraph(rootModule: Type): ModuleGraph;
-/**
- * Registers all providers and controllers from the module graph into the
- * DI container.
- */
-declare function registerModuleGraph(graph: ModuleGraph, container: Container): void;
 
 declare class HandlerRegistry {
-    private handlers;
-    getHandler(path: string, method: string): ResolvedHandler | undefined;
-    getHandlerById(id: string): ResolvedHandler | undefined;
+    private byType;
+    private exactLookup;
+    private byId;
+    private guards;
+    register(handler: ResolvedHandler): void;
+    getHandler(type: "http", routingKey: string): ResolvedHttpHandler | undefined;
+    getHandler(type: "websocket", routingKey: string): ResolvedWebSocketHandler | undefined;
+    getHandler(type: "consumer", routingKey: string): ResolvedConsumerHandler | undefined;
+    getHandler(type: "schedule", routingKey: string): ResolvedScheduleHandler | undefined;
+    getHandler(type: "custom", routingKey: string): ResolvedCustomHandler | undefined;
+    getHandlerById<T extends HandlerType>(type: T, id: string): Extract<ResolvedHandler, {
+        type: T;
+    }> | undefined;
+    getHandlersByType<T extends HandlerType>(type: T): Extract<ResolvedHandler, {
+        type: T;
+    }>[];
     getAllHandlers(): ResolvedHandler[];
-    populateFromGraph(graph: ModuleGraph, container: Container): Promise<void>;
-    scanModule(moduleClass: Type, container: Container): Promise<void>;
-    private registerClassHandler;
-    private registerFunctionHandler;
+    registerGuard(guard: ResolvedGuard): void;
+    getGuard(name: string): ResolvedGuard | undefined;
+    getAllGuards(): ResolvedGuard[];
+    /**
+     * HTTP routing uses path-pattern matching: `"GET /items/{id}"` matches `"GET /items/42"`.
+     * The routing key format is `"METHOD path"` (e.g., `"GET /items/{id}"`).
+     */
+    private findHttpHandler;
 }
 
 declare class CelerityApplication {
@@ -224,9 +837,21 @@ declare class CelerityApplication {
     getAppLayers(): (CelerityLayer | Type<CelerityLayer>)[];
 }
 
+type PipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    appLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    handlerName?: string;
+};
+declare function executeHttpPipeline(handler: ResolvedHandlerBase, request: HttpRequest, options: PipelineOptions): Promise<HttpResponse>;
+
 type ServerlessHandler = (event: unknown, context: unknown) => Promise<unknown>;
 interface ServerlessAdapter {
-    createHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+    createHttpHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+    createWebSocketHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+    createConsumerHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+    createScheduleHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+    createCustomHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
 }
 
 declare class ServerlessApplication {
@@ -237,7 +862,8 @@ declare class ServerlessApplication {
     private appLayers;
     private handler;
     constructor(registry: HandlerRegistry, container: Container, adapter: ServerlessAdapter, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[], appLayers?: (CelerityLayer | Type<CelerityLayer>)[]);
-    start(): Promise<ServerlessHandler>;
+    createHandler(type: HandlerType): ServerlessHandler;
+    start(type?: HandlerType): Promise<ServerlessHandler>;
     close(): Promise<void>;
     getHandler(): ServerlessHandler;
     getContainer(): Container;
@@ -250,7 +876,11 @@ declare class TestingApplication {
     private systemLayers;
     private appLayers;
     constructor(registry: HandlerRegistry, container: Container, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[], appLayers?: (CelerityLayer | Type<CelerityLayer>)[]);
-    inject(request: HttpRequest): Promise<HttpResponse>;
+    injectHttp(request: HttpRequest): Promise<HttpResponse>;
+    injectWebSocket(route: string, message: WebSocketMessage): Promise<void>;
+    injectConsumer(handlerTag: string, event: ConsumerEventInput): Promise<EventResult>;
+    injectSchedule(handlerTag: string, event: ScheduleEventInput$1): Promise<EventResult>;
+    injectCustom(name: string, payload?: unknown): Promise<unknown>;
     getContainer(): Container;
     getRegistry(): HandlerRegistry;
 }
@@ -265,6 +895,39 @@ type MockRequestOptions = {
     clientIp?: string;
 };
 declare function mockRequest(method: HttpMethod, path: string, options?: MockRequestOptions): HttpRequest;
+type MockWebSocketMessageOptions = {
+    messageType?: WebSocketMessageType;
+    eventType?: WebSocketEventType;
+    connectionId?: string;
+    messageId?: string;
+    jsonBody?: unknown;
+    binaryBody?: Buffer;
+    traceContext?: Record<string, string> | null;
+};
+declare function mockWebSocketMessage(options?: MockWebSocketMessageOptions): WebSocketMessage;
+type MockConsumerMessage = {
+    messageId?: string;
+    body: string;
+    source?: string;
+    sourceType?: string;
+    sourceName?: string;
+    eventType?: string;
+    messageAttributes?: MessageAttributes;
+};
+type MockConsumerEventOptions = {
+    vendor?: unknown;
+    traceContext?: Record<string, string> | null;
+};
+declare function mockConsumerEvent(handlerTag: string, messages: MockConsumerMessage[], options?: MockConsumerEventOptions): ConsumerEventInput;
+type MockScheduleEventOptions = {
+    scheduleId?: string;
+    messageId?: string;
+    schedule?: string;
+    input?: unknown;
+    vendor?: unknown;
+    traceContext?: Record<string, string> | null;
+};
+declare function mockScheduleEvent(handlerTag: string, options?: MockScheduleEventOptions): ScheduleEventInput$1;
 
 type CreateOptions = {
     adapter?: ServerlessAdapter;
@@ -294,7 +957,7 @@ type HttpHandlerRequest<TBody = unknown> = {
     userAgent: string | null;
     contentType: string | null;
 };
-type HttpHandlerContext = {
+type HttpFunctionContext = {
     requestId: string;
     requestTime: string;
     metadata: HandlerMetadata;
@@ -318,7 +981,7 @@ type HttpHandlerConfig<TBody = unknown> = {
     metadata?: Record<string, unknown>;
 };
 type HttpHandlerOptions<TBody = unknown> = Omit<HttpHandlerConfig<TBody>, "path" | "method">;
-type HttpHandlerFn<TBody = unknown> = (req: HttpHandlerRequest<TBody>, ctx: HttpHandlerContext, ...deps: unknown[]) => unknown;
+type HttpHandlerFn<TBody = unknown> = (req: HttpHandlerRequest<TBody>, ctx: HttpFunctionContext, ...deps: unknown[]) => unknown;
 declare function createHttpHandler<TBody = unknown>(config: HttpHandlerConfig<TBody>, handler: HttpHandlerFn<TBody>): FunctionHandlerDefinition;
 declare function httpGet(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
 declare function httpGet(path: string, options: HttpHandlerOptions, handler: HttpHandlerFn): FunctionHandlerDefinition;
@@ -331,6 +994,145 @@ declare function httpPatch<TBody = unknown>(path: string, options: HttpHandlerOp
 declare function httpDelete(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
 declare function httpDelete(path: string, options: HttpHandlerOptions, handler: HttpHandlerFn): FunctionHandlerDefinition;
 
+type GuardConfig = {
+    name?: string;
+    inject?: InjectionToken[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * The request context provided to a guard handler.
+ * Mirrors the Rust runtime's `AuthGuardValidateInput` + `RequestInfo`.
+ */
+type GuardRequest = {
+    token: string;
+    headers: Record<string, string | string[]>;
+    query: Record<string, string | string[]>;
+    cookies: Record<string, string>;
+    body: unknown;
+    requestId: string;
+    clientIp: string;
+};
+type GuardContext = {
+    metadata: HandlerMetadata;
+    container: ServiceContainer;
+    logger?: CelerityLogger;
+    /**
+     * Claims accumulated from preceding guards in the chain.
+     * Keyed by guard name (e.g. `{ jwt: { sub: "user-1", ... } }`).
+     * Empty object for the first guard in the chain.
+     */
+    auth: Record<string, unknown>;
+};
+/**
+ * Guard handler function signature.
+ * Return the claims object to attach to `request.auth.<guardName>`,
+ * or throw `ForbiddenException`/`UnauthorizedException` to reject.
+ */
+type GuardHandlerFn = (req: GuardRequest, ctx: GuardContext, ...deps: unknown[]) => unknown;
+declare function createGuard(config: GuardConfig, handler: GuardHandlerFn): GuardDefinition;
+
+type WebSocketHandlerConfig = {
+    route?: string;
+    protectedBy?: string[];
+    schema?: Schema;
+    inject?: InjectionToken[];
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    metadata?: Record<string, unknown>;
+};
+type WebSocketHandlerFn = (message: WebSocketMessage, ctx: WebSocketHandlerContext, ...deps: unknown[]) => Promise<void> | void;
+declare function createWebSocketHandler(config: WebSocketHandlerConfig, handler: WebSocketHandlerFn): FunctionHandlerDefinition;
+
+type ConsumerHandlerConfig = {
+    route?: string;
+    messageSchema?: Schema;
+    inject?: InjectionToken[];
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    metadata?: Record<string, unknown>;
+};
+type ConsumerHandlerFn = (event: ConsumerEventInput, ctx: ConsumerHandlerContext, ...deps: unknown[]) => Promise<EventResult>;
+declare function createConsumerHandler(config: ConsumerHandlerConfig, handler: ConsumerHandlerFn): FunctionHandlerDefinition;
+
+type ScheduleHandlerConfig<T = unknown> = {
+    scheduleId?: string;
+    schedule?: string;
+    schema?: Schema<T>;
+    inject?: InjectionToken[];
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    metadata?: Record<string, unknown>;
+};
+type ScheduleHandlerFn = (event: ScheduleEventInput$1, ctx: ScheduleHandlerContext, ...deps: unknown[]) => Promise<EventResult>;
+/**
+ * Creates a function-based schedule handler definition.
+ *
+ * Function handlers are blueprint-first — the schedule expression, timezone,
+ * and handler binding are all defined in the blueprint. The handler declares
+ * its dependencies and provides the task logic.
+ *
+ * @example
+ * ```ts
+ * // Minimal — blueprint defines everything
+ * const dailyCleanup = createScheduleHandler(
+ *   { inject: [CleanupService] },
+ *   async (event, ctx, cleanupService: CleanupService) => {
+ *     await cleanupService.run();
+ *     return { success: true };
+ *   },
+ * );
+ *
+ * // With scheduleId hint for deploy engine auto-wiring
+ * const weeklyReport = createScheduleHandler("weekly-report", {
+ *   inject: [ReportService],
+ * }, async (event, ctx, reportService: ReportService) => {
+ *   await reportService.generate();
+ *   return { success: true };
+ * });
+ *
+ * // With expression for prototyping / single-environment apps
+ * const hourlySync = createScheduleHandler("rate(1 hour)", {
+ *   inject: [SyncService],
+ * }, async (event, ctx, syncService: SyncService) => {
+ *   await syncService.run();
+ *   return { success: true };
+ * });
+ * ```
+ */
+declare function createScheduleHandler(config: ScheduleHandlerConfig, handler: ScheduleHandlerFn): FunctionHandlerDefinition;
+declare function createScheduleHandler(scheduleIdOrExpression: string, config: ScheduleHandlerConfig, handler: ScheduleHandlerFn): FunctionHandlerDefinition;
+
+type CustomHandlerConfig<TInput = unknown> = {
+    name?: string;
+    schema?: Schema<TInput>;
+    inject?: InjectionToken[];
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    metadata?: Record<string, unknown>;
+};
+type CustomHandlerFn = (payload: unknown, ctx: BaseHandlerContext, ...deps: unknown[]) => Promise<unknown>;
+/**
+ * Creates a function-based custom/invocable handler definition.
+ *
+ * Function handlers are blueprint-first — the handler name and invocation
+ * binding come from the blueprint. The handler declares its dependencies,
+ * an optional schema for type-safe payload validation, and the implementation.
+ *
+ * @example
+ * ```ts
+ * // With schema — payload is validated and typed before the handler runs
+ * const processPayment = createCustomHandler(
+ *   { schema: PaymentSchema, inject: [PaymentService] },
+ *   async (payload, ctx, paymentService: PaymentService) => {
+ *     return paymentService.process(payload as PaymentInput);
+ *   },
+ * );
+ *
+ * // Without schema — payload is unknown
+ * const healthCheck = createCustomHandler(
+ *   {},
+ *   async () => ({ status: "ok" }),
+ * );
+ * ```
+ */
+declare function createCustomHandler(config: CustomHandlerConfig, handler: CustomHandlerFn): FunctionHandlerDefinition;
+
 declare class HttpException extends Error {
     readonly statusCode: number;
     readonly details?: unknown | undefined;
@@ -382,6 +1184,8 @@ declare class GatewayTimeoutException extends HttpException {
     constructor(message?: string, details?: unknown);
 }
 
+declare function routingKeyOf(handler: ResolvedHandler): string;
+
 /**
  * Resolve a handler ID as a module reference by dynamically importing
  * the module and matching the exported function against the registry.
@@ -399,7 +1203,159 @@ declare class GatewayTimeoutException extends HttpException {
  * - `"app.module"` — dotted module name: tries named export split first,
  *   falls back to default export from module `app.module`
  */
-declare function resolveHandlerByModuleRef(handlerId: string, registry: HandlerRegistry, baseDir: string): Promise<ResolvedHandler | null>;
+declare function resolveHandlerByModuleRef(handlerId: string, handlerType: HandlerType, registry: HandlerRegistry, baseDir: string): Promise<ResolvedHandler | null>;
+
+type ModuleNode = {
+    moduleClass: Type;
+    ownTokens: Set<InjectionToken>;
+    exports: Set<InjectionToken>;
+    imports: Type[];
+    controllers: Type[];
+    functionHandlers: FunctionHandlerDefinition[];
+    guards: (Type | GuardDefinition)[];
+    providers: (Type | (Provider & {
+        provide: InjectionToken;
+    }))[];
+};
+type ModuleGraph = Map<Type, ModuleNode>;
+/**
+ * Builds a module graph by walking the module tree depth-first, collecting
+ * all metadata into a graph structure without any side effects.
+ *
+ * Detects circular module imports and deduplicates visited modules.
+ */
+declare function buildModuleGraph(rootModule: Type): ModuleGraph;
+/**
+ * Registers all providers and controllers from the module graph into the
+ * DI container.
+ */
+declare function registerModuleGraph(graph: ModuleGraph, container: Container): void;
+
+/**
+ * Scans the module graph for HTTP class handlers and function handlers,
+ * registering them in the handler registry.
+ */
+declare function scanHttpHandlers(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+/**
+ * Scans the module graph for guard definitions (class-based and function-based),
+ * registering them in the handler registry.
+ */
+declare function scanHttpGuards(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+/**
+ * Convenience function that builds a module graph, registers providers,
+ * and scans for HTTP handlers and guards in a single call.
+ */
+declare function scanModule(moduleClass: Type, container: Container, registry: HandlerRegistry): Promise<void>;
+
+/**
+ * Scans the module graph for WebSocket class handlers and function handlers,
+ * registering them in the handler registry.
+ */
+declare function scanWebSocketHandlers(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+
+/**
+ * Scans the module graph for Consumer class handlers and function handlers,
+ * registering them in the handler registry.
+ */
+declare function scanConsumerHandlers(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+
+/**
+ * Scans the module graph for schedule handlers — a cross-cutting scan that
+ * walks ALL controllers (any class in `controllers`) looking for methods
+ * decorated with `@ScheduleHandler()`. Also scans function handlers with
+ * `type: "schedule"`.
+ */
+declare function scanScheduleHandlers(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+
+/**
+ * Scans the module graph for custom/invocable handlers — a cross-cutting scan
+ * that walks ALL controllers (any class in `controllers`) looking for methods
+ * decorated with `@Invoke()`. Also scans function handlers with
+ * `type: "custom"`.
+ */
+declare function scanCustomHandlers(graph: ModuleGraph, container: Container, registry: HandlerRegistry): Promise<void>;
+
+type WebSocketPipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    appLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    handlerName?: string;
+};
+declare function executeWebSocketPipeline(handler: ResolvedHandlerBase, message: WebSocketMessage, options: WebSocketPipelineOptions): Promise<void>;
+
+/**
+ * WebSocket sender implementation for local/container deployments.
+ * Wraps the NAPI runtime's CoreWebSocketRegistry.
+ */
+declare class RuntimeWebSocketSender implements WebSocketSender {
+    private registry;
+    constructor(registry: CoreWebSocketRegistry);
+    sendMessage(connectionId: string, data: unknown, options?: WebSocketSendOptions): Promise<void>;
+}
+
+type ConsumerPipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    appLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    handlerName?: string;
+};
+declare function executeConsumerPipeline(handler: ResolvedHandlerBase, event: ConsumerEventInput, options: ConsumerPipelineOptions): Promise<EventResult>;
+
+type SchedulePipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    appLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    handlerName?: string;
+};
+declare function executeSchedulePipeline(handler: ResolvedHandlerBase, event: ScheduleEventInput$1, options: SchedulePipelineOptions): Promise<EventResult>;
+
+type CustomPipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    appLayers?: (CelerityLayer<BaseHandlerContext> | Type<CelerityLayer<BaseHandlerContext>>)[];
+    handlerName?: string;
+};
+/**
+ * Execute a custom/invocable handler pipeline.
+ *
+ * Unlike consumer and schedule pipelines, custom handlers return raw results
+ * and errors are re-thrown to the caller (not wrapped in `EventResult`).
+ */
+declare function executeCustomPipeline(handler: ResolvedHandlerBase, payload: unknown, options: CustomPipelineOptions): Promise<unknown>;
+
+type GuardInput = {
+    token: string;
+    method: string;
+    path: string;
+    headers: Record<string, string | string[]>;
+    query: Record<string, string | string[]>;
+    cookies: Record<string, string>;
+    body: unknown;
+    requestId: string;
+    clientIp: string;
+    auth: Record<string, unknown>;
+    handlerName?: string;
+};
+type GuardPipelineOptions = {
+    container: ServiceContainer;
+    handlerMetadata?: Record<string, unknown>;
+};
+type GuardResult = {
+    allowed: true;
+    auth: Record<string, unknown>;
+} | {
+    allowed: false;
+    statusCode: number;
+    message: string;
+    details?: unknown;
+};
+/**
+ * Executes a guard handler and returns a result indicating whether access
+ * is allowed. On success, `auth` contains the data to store under
+ * `request.auth.<guardName>`. On failure, `statusCode` and `message`
+ * describe the rejection.
+ */
+declare function executeGuardPipeline(guard: ResolvedGuard, input: GuardInput, options: GuardPipelineOptions): Promise<GuardResult>;
 
 declare const CONTROLLER_METADATA: unique symbol;
 declare const HTTP_METHOD_METADATA: unique symbol;
@@ -408,9 +1364,14 @@ declare const GUARD_PROTECTEDBY_METADATA: unique symbol;
 declare const GUARD_CUSTOM_METADATA: unique symbol;
 declare const LAYER_METADATA: unique symbol;
 declare const MODULE_METADATA: unique symbol;
-declare const INJECT_METADATA: unique symbol;
 declare const PUBLIC_METADATA: unique symbol;
 declare const CUSTOM_METADATA: unique symbol;
+declare const WEBSOCKET_CONTROLLER_METADATA: unique symbol;
+declare const WEBSOCKET_EVENT_METADATA: unique symbol;
+declare const CONSUMER_METADATA: unique symbol;
+declare const CONSUMER_HANDLER_METADATA: unique symbol;
+declare const SCHEDULE_HANDLER_METADATA: unique symbol;
+declare const INVOKE_METADATA: unique symbol;
 
 type BootstrapResult = {
     container: Container;
@@ -428,26 +1389,35 @@ declare function flattenMultiValueRecord(record: Record<string, string[]>): Reco
 declare function mapRuntimeRequest(request: Request): HttpRequest;
 /** Convert SDK HttpResponse → NAPI runtime Response. */
 declare function mapToRuntimeResponse(response: HttpResponse): Response;
+/** Convert NAPI JsWebSocketMessageInfo → SDK WebSocketMessage. */
+declare function mapWebSocketMessage(info: JsWebSocketMessageInfo): WebSocketMessage;
+/** Convert NAPI JsConsumerEventInput → SDK ConsumerEventInput. */
+declare function mapConsumerEventInput(input: JsConsumerEventInput): ConsumerEventInput;
+/** Convert NAPI JsScheduleEventInput → SDK ScheduleEventInput. */
+declare function mapScheduleEventInput(input: JsScheduleEventInput): ScheduleEventInput$1;
+/** Convert SDK EventResult → NAPI JsEventResult. */
+declare function mapToNapiEventResult(result: EventResult): JsEventResult;
 
 type RuntimeCallback = (err: Error | null, request: Request) => Promise<Response>;
+type WebSocketCallback = (err: Error | null, info: JsWebSocketMessageInfo) => Promise<void>;
+type ConsumerCallback = (err: Error | null, input: JsConsumerEventInput) => Promise<JsEventResult>;
+type ScheduleCallback = (err: Error | null, input: JsScheduleEventInput) => Promise<JsEventResult>;
+type CustomCallback = (err: Error | null, payload: unknown) => Promise<unknown>;
+type GuardCallback = (input: GuardInput) => Promise<GuardResult>;
 type RuntimeBootstrapResult = {
     registry: HandlerRegistry;
     container: Container;
-    /** Create a runtime-compatible handler callback for a specific route. */
-    createRouteCallback(path: string, method: string): RuntimeCallback | null;
-    /**
-     * Create a runtime-compatible handler callback by handler ID.
-     * First tries a direct registry lookup. If that fails, resolves the handler ID
-     * as a module reference by dynamically importing the module and matching the
-     * exported function against the registry.
-     *
-     * Supported formats:
-     * - `"handlers.hello"` — named export `hello` from module `handlers`
-     * - `"handlers"` — default export from module `handlers`
-     * - `"app.module"` — dotted module name: tries named export split first,
-     *   falls back to default export from module `app.module`
-     */
-    createRouteCallbackById(handlerId: string, codeLocation?: string): Promise<RuntimeCallback | null>;
+    createRouteCallback(method: string, path: string, handlerName?: string): RuntimeCallback | null;
+    createRouteCallbackById(handlerId: string, codeLocation?: string, handlerName?: string): Promise<RuntimeCallback | null>;
+    createGuardCallback(guardName: string): GuardCallback | null;
+    createWebSocketCallback(route: string, handlerName?: string): WebSocketCallback | null;
+    createWebSocketCallbackById(handlerId: string, codeLocation?: string, handlerName?: string): Promise<WebSocketCallback | null>;
+    createConsumerCallback(handlerTag: string, handlerName?: string): ConsumerCallback | null;
+    createConsumerCallbackById(handlerId: string, codeLocation?: string, handlerName?: string): Promise<ConsumerCallback | null>;
+    createScheduleCallback(handlerTag: string, handlerName?: string): ScheduleCallback | null;
+    createScheduleCallbackById(handlerId: string, codeLocation?: string, handlerName?: string): Promise<ScheduleCallback | null>;
+    createCustomCallback(handlerName: string): CustomCallback | null;
+    createCustomCallbackById(handlerId: string, codeLocation?: string, handlerName?: string): Promise<CustomCallback | null>;
 };
 /**
  * Bootstrap the user's module and return an object with per-route callback creation.
@@ -465,4 +1435,4 @@ type StartRuntimeOptions = {
  */
 declare function startRuntime(options?: StartRuntimeOptions): Promise<void>;
 
-export { APP_CONFIG, Action, Auth, BadGatewayException, BadRequestException, Body, type BootstrapResult, CONTROLLER_METADATA, CUSTOM_METADATA, CelerityApplication, CelerityFactory, ConflictException, Container, Controller, type ControllerMetadata, Cookies, type CreateOptions, Delete, ForbiddenException, GUARD_CUSTOM_METADATA, GUARD_PROTECTEDBY_METADATA, GatewayTimeoutException, Get, GoneException, Guard, HTTP_METHOD_METADATA, HandlerMetadataStore, HandlerRegistry, Head, Headers, HttpException, type HttpHandlerConfig, type HttpHandlerContext, type HttpHandlerRequest, INJECT_METADATA, Inject, Injectable, InternalServerErrorException, LAYER_METADATA, MODULE_METADATA, MethodNotAllowedException, type MockRequestOptions, Module, type ModuleGraph, type ModuleNode, NotAcceptableException, NotFoundException, NotImplementedException, Options, PUBLIC_METADATA, Param, type ParamMetadata, type ParamType, Patch, type PipelineOptions, Post, ProtectedBy, Public, Put, Query, ROUTE_PATH_METADATA, RUNTIME_APP, Req, RequestId, type ResolvedHandler, type RuntimeBootstrapResult, type ServerlessAdapter, ServerlessApplication, type ServerlessHandler, ServiceUnavailableException, SetMetadata, type StartRuntimeOptions, TestingApplication, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UseLayer, UseLayers, type ValidationSchemas, bootstrap, bootstrapForRuntime, buildModuleGraph, createDefaultSystemLayers, createHttpHandler, discoverModule, disposeLayers, executeHandlerPipeline, flattenMultiValueRecord, getClassDependencyTokens, getProviderDependencyTokens, httpDelete, httpGet, httpPatch, httpPost, httpPut, mapRuntimeRequest, mapToRuntimeResponse, mockRequest, registerModuleGraph, resolveHandlerByModuleRef, runLayerPipeline, startRuntime, tokenToString, validate };
+export { APP_CONFIG, Action, Auth, BadGatewayException, BadRequestException, Body, type BootstrapResult, CONSUMER_HANDLER_METADATA, CONSUMER_METADATA, CONTROLLER_METADATA, CUSTOM_METADATA, CelerityApplication, CelerityFactory, ConflictException, ConnectionId, Consumer, type ConsumerHandlerConfig, type ConsumerHandlerMetadata, type ConsumerMetadata, type ConsumerPipelineOptions, ConsumerTraceContext, Container, Controller, type ControllerMetadata, Cookies, type CreateOptions, type CustomHandlerConfig, type CustomPipelineOptions, Delete, EventInput, EventType, ForbiddenException, GUARD_CUSTOM_METADATA, GUARD_PROTECTEDBY_METADATA, GatewayTimeoutException, Get, GoneException, Guard, type GuardConfig, type GuardContext, type GuardHandlerFn, type GuardInput, type GuardPipelineOptions, type GuardRequest, type GuardResult, HTTP_METHOD_METADATA, HandlerMetadataStore, HandlerRegistry, Head, Headers, HttpException, type HttpFunctionContext, type HttpHandlerConfig, type HttpHandlerRequest, INVOKE_METADATA, Inject, Injectable, InternalServerErrorException, Invoke, InvokeContext, type InvokeMetadata, LAYER_METADATA, MODULE_METADATA, MessageBody, MessageHandler, MessageId, Messages, MethodNotAllowedException, type MockConsumerEventOptions, type MockConsumerMessage, type MockRequestOptions, type MockScheduleEventOptions, type MockWebSocketMessageOptions, Module, type ModuleGraph, type ModuleNode, NotAcceptableException, NotFoundException, NotImplementedException, OnConnect, OnDisconnect, OnMessage, Options, PUBLIC_METADATA, Param, type ParamMetadata, type ParamType, Patch, Payload, type PipelineOptions, Post, ProtectedBy, Public, Put, Query, ROUTE_PATH_METADATA, RUNTIME_APP, Req, RequestContext, RequestId, type ResolvedConsumerHandler, type ResolvedCustomHandler, type ResolvedGuard, type ResolvedHandler, type ResolvedHandlerBase, type ResolvedHttpHandler, type ResolvedScheduleHandler, type ResolvedWebSocketHandler, type RuntimeBootstrapResult, RuntimeWebSocketSender, SCHEDULE_HANDLER_METADATA, ScheduleEventInput as ScheduleEventInputParam, ScheduleExpression, ScheduleHandler, type ScheduleHandlerConfig, type ScheduleHandlerMetadata, ScheduleId, ScheduleInput, type SchedulePipelineOptions, type ServerlessAdapter, ServerlessApplication, type ServerlessHandler, ServiceUnavailableException, SetMetadata, type StartRuntimeOptions, TestingApplication, Token, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UseLayer, UseLayers, UseResource, UseResources, type ValidationSchemas, Vendor, WEBSOCKET_CONTROLLER_METADATA, WEBSOCKET_EVENT_METADATA, WebSocketController, type WebSocketEventMetadata, type WebSocketHandlerConfig, type WebSocketPipelineOptions, bootstrap, bootstrapForRuntime, buildModuleGraph, createConsumerHandler, createCustomHandler, createDefaultSystemLayers, createGuard, createHttpHandler, createScheduleHandler, createWebSocketHandler, discoverModule, disposeLayers, executeConsumerPipeline, executeCustomPipeline, executeGuardPipeline, executeHttpPipeline, executeSchedulePipeline, executeWebSocketPipeline, flattenMultiValueRecord, getClassDependencyTokens, getProviderDependencyTokens, httpDelete, httpGet, httpPatch, httpPost, httpPut, mapConsumerEventInput, mapRuntimeRequest, mapScheduleEventInput, mapToNapiEventResult, mapToRuntimeResponse, mapWebSocketMessage, mockConsumerEvent, mockRequest, mockScheduleEvent, mockWebSocketMessage, registerModuleGraph, resolveHandlerByModuleRef, routingKeyOf, runLayerPipeline, scanConsumerHandlers, scanCustomHandlers, scanHttpGuards, scanHttpHandlers, scanModule, scanScheduleHandlers, scanWebSocketHandlers, startRuntime, tokenToString, validate };