@gravito/core 2.0.6 → 3.0.1

package/README.md

@@ -135,23 +135,7 @@ core.hooks.addAction('user_registered', async (userId: string) => {
 await core.hooks.doAction('user_registered', 'user_123');
 ```
 
-### 5. Reliability & Distributed Retries
-
-Built-in support for distributed retries via Bull Queue:
-
-```typescript
-import { RetryScheduler } from '@gravito/core';
-
-const scheduler = new RetryScheduler({
-  initialDelayMs: 1000,
-  multiplier: 2,
-  maxRetries: 5
-});
-
-core.hooks.setRetryScheduler(scheduler);
-```
-
-### 6. Mount an Orbit
+### 5. Mount an Orbit
 
 Orbits are just standard Photon applications that plug into the core.
 
@@ -165,14 +149,14 @@ blogOrbit.get('/posts', (c) => c.json({ posts: [] }));
 core.mountOrbit('/api/blog', blogOrbit);
 ```
 
-### 7. Liftoff! 🚀
+### 6. Liftoff! 🚀
 
 ```typescript
 // Export for Bun.serve
 export default core.liftoff(); // Automatically uses PORT from config/env
 ```
 
-### 8. Process-level Error Handling (Recommended)
+### 7. Process-level Error Handling (Recommended)
 
 Request-level errors are handled by `PlanetCore` automatically, but background jobs and startup code can still fail outside the request lifecycle.
 
@@ -301,15 +285,19 @@ const logger = container.make('logger'); // inferred as Logger
 ### `HookManager`
 
 - **`addFilter(hook, callback)`**: Register a filter.
-- **`applyFilters(hook, initialValue, ...args)`**: Execute filters sequentially.
-- **`addAction(hook, callback)`**: Register an action.
-- **`doAction(hook, ...args)`**: Execute actions.
+- **`applyFilters(hook, initialValue, ...args)`**: Apply all registered filters sequentially.
+- **`addAction(hook, callback, options?)`**: Register an action hook.
+- **`doAction(hook, args, options?)`**: Execute action hooks asynchronously.
+- **`doActionSync(hook, args)`**: Execute action hooks synchronously.
+- **`doActionAsync(hook, args, options)`**: Execute action hooks via priority queue.
 
 ### `EventManager`
 
-- **`emit(event, ...args)`**: Dispatch an event.
-- **`on(event, callback)`**: Listen to an event.
-- **`off(event, callback)`**: Remove a listener.
+- **`dispatch(event)`**: Dispatch an event asynchronously.
+- **`listen(event, listener, options?)`**: Register an event listener.
+- **`unlisten(event, listener)`**: Remove an event listener.
+- **`clear()`**: Remove all event listeners.
+- **`getListeners(event?)`**: Get registered listeners.
 
 ### `ConfigManager`
 
@@ -317,6 +305,57 @@ const logger = container.make('logger'); // inferred as Logger
 - **`set(key, value)`**: Set a config value.
 - **`has(key)`**: Check if a config key exists.
 
+## When to use orbit() vs register() vs use()
+
+### `orbit(orbitInstance)` — Infrastructure Plugins
+
+Use when integrating a **GravitoOrbit** that implements `install()`.
+Orbits are infrastructure-level plugins that extend core capabilities.
+
+```typescript
+import { OrbitDatabase } from '@gravito/atlas'
+import { OrbitAuth } from '@gravito/sentinel'
+
+const app = await PlanetCore.boot()
+await app.orbit(new OrbitDatabase({ connection: 'sqlite' }))
+await app.orbit(new OrbitAuth({ driver: 'session' }))
+```
+
+### `register(provider)` — Service Providers
+
+Use when adding a **ServiceProvider** to the IoC container.
+Providers register bindings and boot services synchronously.
+
+```typescript
+import { CacheServiceProvider } from './providers/CacheServiceProvider'
+
+const app = await PlanetCore.boot()
+app.register(new CacheServiceProvider())
+```
+
+### `use(satelliteOrFn)` — Satellites & Setup Functions
+
+Use when adding a **satellite module** or a **one-off setup function**.
+Accepts either a ServiceProvider (delegates to register()) or an async function.
+
+```typescript
+// Satellite module
+import { CartSatellite } from '@gravito/satellite-cart'
+await app.use(new CartSatellite())
+
+// Setup function
+await app.use(async (core) => {
+  core.register(new MyProvider())
+  await core.orbit(new MyOrbit())
+})
+```
+
+### Decision Tree
+
+1. Does it implement `GravitoOrbit.install()`? → Use `orbit()`
+2. Does it implement `ServiceProvider.register()`? → Use `register()`
+3. Is it a function or satellite module? → Use `use()`
+
 ## 🤝 Contributing
 
 Contributions, issues and feature requests are welcome!

package/dist/Application.d.ts

@@ -19,12 +19,13 @@ import { Container } from './Container';
 import type { EventManager } from './EventManager';
 import type { Logger } from './Logger';
 import { PlanetCore } from './PlanetCore';
+import type { GravitoConfig } from './PlanetCore';
 import type { ServiceProvider } from './ServiceProvider';
 /**
  * Application Config options for the Application class.
  * @public
  */
-export interface ApplicationConfig {
+export interface ApplicationConfig extends Pick<GravitoConfig, 'logger' | 'config'> {
     /**
      * Base path of the application
      */
@@ -43,14 +44,6 @@ export interface ApplicationConfig {
      * Environment (development, production, testing)
      */
     env?: 'development' | 'production' | 'testing';
-    /**
-     * Logger instance
-     */
-    logger?: Logger;
-    /**
-     * Initial configuration values
-     */
-    config?: Record<string, unknown>;
     /**
      * Service providers to register
      */

package/dist/Container.d.ts

@@ -17,7 +17,8 @@ export type Factory<T> = (container: Container) => T;
  * }
  * ```
  */
-export type ServiceMap = {};
+export interface ServiceMap {
+}
 /**
  * ServiceKey represents the allowed keys for service resolution.
  * Includes keys from ServiceMap, generic strings, or symbols.
@@ -85,6 +86,22 @@ export declare class Container {
      * ```
      */
     singleton<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Bind a shared service with a namespace prefix (e.g., 'inline:my-plugin:service').
+     * Used by Lite Satellites to prevent global namespace pollution.
+     *
+     * @template T - The type of the service being bound.
+     * @param namespace - The namespace for the service (e.g., plugin name).
+     * @param key - The unique identifier for the service within the namespace.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.singletonInline('ping', 'service', (c) => new PingService());
+     * // Resulting key: 'inline:ping:service'
+     * ```
+     */
+    singletonInline<T>(namespace: string, key: string, factory: Factory<T>): void;
     /**
      * Bind a request-scoped service to the container.
      *

package/dist/GravitoServer.d.ts

@@ -1,4 +1,4 @@
-import { type GravitoConfig, PlanetCore } from './PlanetCore';
+import { type GravitoConfig, type GravitoOrbit, PlanetCore } from './PlanetCore';
 /**
  * Manifest describing a Gravito application structure.
  * @public
@@ -13,16 +13,16 @@ export interface GravitoManifest {
  * Function type for asynchronous module resolution.
  * @public
  */
-export type ModuleResolver = () => Promise<any>;
+export type ModuleResolver = () => Promise<unknown>;
 /**
- * Gravito 核心啟動引擎 (已解耦)
+ * Gravito core boot engine (decoupled).
  */
 export declare class GravitoServer {
     /**
-     * 一鍵建立並組裝伺服器
-     * @param manifest 站點描述清單
-     * @param resolvers 模組解析器字典
-     * @param baseOrbits 基礎軌道模組 (例如 OrbitMonolith)
+     * Create and assemble a server in one step.
+     * @param manifest - Application manifest describing the site structure.
+     * @param resolvers - Dictionary of module resolvers.
+     * @param baseOrbits - Base orbit modules (e.g., OrbitMonolith).
      */
-    static create(manifest: GravitoManifest, resolvers: Record<string, ModuleResolver>, baseOrbits?: any[]): Promise<PlanetCore>;
+    static create(manifest: GravitoManifest, resolvers: Record<string, ModuleResolver>, baseOrbits?: (GravitoOrbit | (new () => GravitoOrbit))[]): Promise<PlanetCore>;
 }

package/dist/HookManager.d.ts

@@ -2,17 +2,18 @@ import { DeadLetterQueue } from './events/DeadLetterQueue';
 import type { EventBackend } from './events/EventBackend';
 import type { EventOptions } from './events/EventOptions';
 import { EventPriorityQueue } from './events/EventPriorityQueue';
+import type { EventStatus } from './events/MessageQueueBridge';
 import { DeadLetterQueueManager } from './reliability/DeadLetterQueueManager';
 export type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions, } from './hooks/types';
 import type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions } from './hooks/types';
 /**
  * Manager for WordPress-style hooks (actions and filters).
  *
- * 此為 facade 類別，將職責委派給專門的管理器：
- * - FilterManager：處理 filter hook 的登記與執行
- * - ActionManager：處理 action hook 的登記與執行
- * - AsyncDetector：非同步偵測快取
- * - MigrationWarner：遷移警告管理
+ * This is a facade class that delegates responsibilities to specialized managers:
+ * - FilterManager: handles filter hook registration and execution
+ * - ActionManager: handles action hook registration and execution
+ * - AsyncDetector: caches async detection results
+ * - MigrationWarner: manages migration warnings
  *
  * @public
  */
@@ -88,8 +89,9 @@ export declare class HookManager {
      * This method supports both synchronous and asynchronous dispatch based on configuration.
      * In hybrid mode, it auto-detects async listeners and uses async dispatch.
      *
-     * 注意：dispatch 模式決策在此層級完成，以確保子類別（如 ObservableHookManager）
-     * 可透過多型覆寫正確攔截 doActionSync / doActionAsync 的呼叫。
+     * Note: Dispatch mode decisions are made at this level to ensure that subclasses
+     * (e.g., ObservableHookManager) can correctly intercept doActionSync / doActionAsync
+     * calls via polymorphic overrides.
      *
      * @template TArgs - The type of arguments passed to the action.
      * @param hook - The name of the hook.
@@ -363,20 +365,20 @@ export declare class HookManager {
         failed: number;
     }>;
     /**
-     * Dispatch an event through Bull Queue（分佈式異步處理）.
+     * Dispatch an event through Bull Queue (distributed async processing).
      *
-     * 與 doActionAsync() 不同：
-     * - doActionAsync() 使用 EventPriorityQueue (Memory-based)
-     * - dispatchQueued() 使用 Bull Queue (Redis-backed, 分佈式)
+     * Unlike doActionAsync():
+     * - doActionAsync() uses EventPriorityQueue (memory-based)
+     * - dispatchQueued() uses Bull Queue (Redis-backed, distributed)
      *
-     * 適用於需要持久化和跨進程處理的事件。
+     * Use this for events that require persistence and cross-process handling.
      *
-     * @template TArgs - 事件參數類型
-     * @param event - 事件名稱
-     * @param args - 事件參數
-     * @param options - 事件選項（可選）
-     * @returns Job ID
-     * @throws 如果未配置 MessageQueueBridge 或沒有 listeners
+     * @template TArgs - The type of event arguments.
+     * @param event - Event name.
+     * @param args - Event arguments.
+     * @param options - Event options (optional).
+     * @returns Job ID.
+     * @throws If MessageQueueBridge is not configured or there are no listeners.
      *
      * @example
      * ```typescript
@@ -388,21 +390,21 @@ export declare class HookManager {
      *
      * @public
      */
-    dispatchQueued<TArgs = unknown>(event: string, args: TArgs, options?: any): Promise<string>;
+    dispatchQueued<TArgs = unknown>(event: string, args: TArgs, options?: EventOptions): Promise<string>;
     /**
-     * Dispatch an event through Bull Queue with delay（延遲隊列分發）.
+     * Dispatch an event through Bull Queue with a delay (deferred distributed dispatch).
      *
-     * @template TArgs - 事件參數類型
-     * @param event - 事件名稱
-     * @param args - 事件參數
-     * @param delay - 延遲時間（毫秒）
-     * @param options - 事件選項（可選）
-     * @returns Job ID
-     * @throws 如果未配置 MessageQueueBridge
+     * @template TArgs - The type of event arguments.
+     * @param event - Event name.
+     * @param args - Event arguments.
+     * @param delay - Delay in milliseconds.
+     * @param options - Event options (optional).
+     * @returns Job ID.
+     * @throws If MessageQueueBridge is not configured.
      *
      * @example
      * ```typescript
-     * // 延遲 5 秒後處理
+     * // Delay processing by 5 seconds
      * const jobId = await hookManager.dispatchDeferredQueued(
      *   'reminder:send',
      *   { userId: '123' },
@@ -412,19 +414,19 @@ export declare class HookManager {
      *
      * @public
      */
-    dispatchDeferredQueued<TArgs = unknown>(event: string, args: TArgs, delay: number, options?: any): Promise<string>;
+    dispatchDeferredQueued<TArgs = unknown>(event: string, args: TArgs, delay: number, options?: EventOptions): Promise<string>;
     /**
      * Get the execution status of an event.
      *
-     * 查詢事件執行狀態，支持查詢 Bull Queue 和 DLQ 中的事件。
+     * Queries event execution status from Bull Queue and DLQ.
      *
-     * @param eventId - 事件 ID (task.id 或 jobId)
-     * @returns 事件狀態信息
-     * @throws 如果未配置 MessageQueueBridge
+     * @param eventId - Event ID (task.id or jobId).
+     * @returns Event status information.
+     * @throws If MessageQueueBridge is not configured.
      *
      * @public
      */
-    getEventStatus(eventId: string): Promise<any>;
+    getEventStatus(eventId: string): Promise<EventStatus>;
     /**
      * Get persistent DLQ statistics.
      *

package/dist/PlanetCore.d.ts

@@ -61,6 +61,18 @@ export type ErrorHandlerContext = {
  * @public
  */
 export interface GravitoOrbit {
+    /**
+     * The unique name of the orbit.
+     * Required for Lite Satellites to enable namespaced service injection.
+     * @since 2.2.0
+     */
+    name?: string;
+    /**
+     * List of other orbit names this orbit depends on.
+     * Used for dependency graph generation.
+     * @since 2.2.0
+     */
+    dependencies?: string[];
     install(core: PlanetCore): void | Promise<void>;
 }
 /**
@@ -68,7 +80,17 @@ export interface GravitoOrbit {
  * @public
  */
 export type GravitoConfig = {
+    /**
+     * Logger instance for the application.
+     * Used by both PlanetCore and Application. Defaults to ConsoleLogger if not provided.
+     * @since 2.0.0
+     */
     logger?: Logger;
+    /**
+     * Initial configuration values, loaded into ConfigManager on boot.
+     * Accessible via `core.config` or `app.config` after booting.
+     * @since 2.0.0
+     */
     config?: Record<string, unknown>;
     orbits?: (new () => GravitoOrbit)[] | GravitoOrbit[];
     /**
@@ -174,6 +196,14 @@ export declare class PlanetCore {
     services: Map<string, unknown>;
     encrypter?: Encrypter;
     hasher: BunHasher;
+    /**
+     * Track installed orbits and their dependencies.
+     * @since 2.2.0
+     */
+    readonly installedOrbits: Array<{
+        name: string;
+        dependencies: string[];
+    }>;
     /**
      * Observability provider for distributed tracing and metrics.
      * @since 2.2.0
@@ -183,6 +213,12 @@ export declare class PlanetCore {
     private deferredProviders;
     private bootedProviders;
     private isShuttingDown;
+    /**
+     * Global shutdown timeout in milliseconds (D-10).
+     * If the entire shutdown sequence does not complete within this limit,
+     * a warning is logged and shutdown is force-completed so the process can exit.
+     */
+    private static readonly GLOBAL_SHUTDOWN_TIMEOUT;
     /**
      * Initialize observability asynchronously (metrics, tracing, Prometheus).
      * This is called from constructor but doesn't block initialization.
@@ -293,6 +329,24 @@ export declare class PlanetCore {
      * @internal
      */
     private setupSignalHandlers;
+    /**
+     * Register a Lite Satellite (Anonymous Plugin) as an object literal.
+     * This is a simplified alternative to full-featured Orbits.
+     *
+     * @param config - The plugin configuration object.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.plugin({
+     *   name: 'ping',
+     *   install(core) {
+     *     core.router.get('/ping', (c) => c.text('pong'))
+     *   }
+     * });
+     * ```
+     */
+    plugin(config: GravitoOrbit): Promise<this>;
     /**
      * Programmatically register an infrastructure module (Orbit).
      * @since 2.0.0

package/dist/Route.d.ts

@@ -15,6 +15,11 @@ export declare class Route {
      * Name the route
      */
     name(name: string): this;
+    /**
+     * Attach Zod schemas to the route for validation and OpenAPI generation.
+     * @since 2.2.0
+     */
+    schema(schemas: NonNullable<RouteOptions['schema']>): this;
     static get(path: string, handler: RouteHandler): Route;
     static get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
     static get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;

package/dist/Router.d.ts

@@ -5,7 +5,7 @@ import { Route } from './Route';
  * Type for Controller Class Constructor
  * @public
  */
-export type ControllerClass = new (core: PlanetCore) => any;
+export type ControllerClass = new (core: PlanetCore) => unknown;
 /**
  * Handler can be a function or [Class, 'methodName']
  * @public
@@ -54,6 +54,17 @@ export interface RouteOptions {
     domain?: string;
     /** Middleware stack for the route */
     middleware?: GravitoMiddleware[];
+    /**
+     * Zod schemas for request validation and response documentation.
+     * Used for OpenAPI generation.
+     * @since 2.2.0
+     */
+    schema?: {
+        body?: unknown;
+        params?: unknown;
+        query?: unknown;
+        response?: unknown;
+    };
 }
 /**
  * Common routing handler argument definition
@@ -140,6 +151,7 @@ export declare class Router {
         method: string;
         path: string;
         domain?: string;
+        options?: RouteOptions;
     }>;
     private dispatcher;
     private namedRoutes;
@@ -153,6 +165,7 @@ export declare class Router {
         path: string;
         name?: string;
         domain?: string | undefined;
+        schema?: RouteOptions["schema"];
     }[];
     /**
      * Register a named route

package/dist/adapters/bun/BunContext.d.ts

@@ -13,7 +13,7 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
     /**
      * URL generator helper
      */
-    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
+    route: (name: string, params?: Record<string, string | number>, query?: Record<string, string | number | boolean | null | undefined>) => string;
     private _status;
     private _headers;
     private _executionCtx?;

package/dist/adapters/bun/BunNativeAdapter.d.ts

@@ -1,6 +1,7 @@
 import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, HttpMethod } from '../../http/types';
 import type { HttpAdapter, RouteDefinition } from '../types';
 import type { WebSocketRouteHandlers } from './BunWebSocketHandler';
+import type { BunRouteOptions } from './types';
 /**
  * Native Bun-optimized HTTP Adapter for Gravito.
  * Uses Bun's standard Request/Response classes and efficient router.
@@ -10,7 +11,9 @@ export declare class BunNativeAdapter implements HttpAdapter {
     readonly name = "bun-native";
     readonly version = "0.0.1";
     get native(): unknown;
+    private isSnapshotLocked;
     private router;
+    private fastPathRegistry;
     private middlewares;
     private errorHandler;
     private notFoundHandler;
@@ -18,7 +21,8 @@ export declare class BunNativeAdapter implements HttpAdapter {
     private readonly maxPoolSize;
     private middlewareChainCache;
     private wsHandler;
-    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler | GravitoMiddleware)[]): void;
+    private checkLock;
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler | GravitoMiddleware | BunRouteOptions)[]): void;
     routes(routes: RouteDefinition[]): void;
     use(path: string, ...middleware: GravitoMiddleware[]): void;
     useGlobal(...middleware: GravitoMiddleware[]): void;
@@ -44,6 +48,12 @@ export declare class BunNativeAdapter implements HttpAdapter {
     createContext(request: Request): GravitoContext;
     onError(handler: GravitoErrorHandler): void;
     onNotFound(handler: GravitoNotFoundHandler): void;
+    registerFastPath(method: string, path: string, handler: (req: Request) => Response | Promise<Response>): void;
+    /**
+     * Generate configuration for Bun.serve().
+     * Offloads fast-path GET routes to Bun's native router.
+     */
+    serveConfig(baseConfig?: Record<string, unknown>): Record<string, unknown>;
     /**
      * 註冊 WebSocket 路由
      */

package/dist/adapters/bun/FastPathRegistry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * FastPathRegistry.ts
+ *
+ * Lightweight registry for ultra-low latency routes that bypass the Gravito engine.
+ * Matches routes using exact string comparison for maximum speed.
+ *
+ * @module @gravito/core/adapters/bun
+ * @since 2.2.0
+ */
+export declare class FastPathRegistry {
+    private routes;
+    /**
+     * Register a fast-path handler.
+     * @param method HTTP method (GET, POST, etc.)
+     * @param path Exact path string (e.g., '/health')
+     * @param handler Handler that takes raw Request and returns Response
+     */
+    register(method: string, path: string, handler: (req: Request) => Response | Promise<Response>): void;
+    /**
+     * Match a request to a registered fast-path handler.
+     * @param method HTTP method
+     * @param path Pathname
+     * @returns The handler if found, otherwise undefined
+     */
+    match(method: string, path: string): ((req: Request) => Response | Promise<Response>) | undefined;
+    /**
+     * Get all registered fast-path routes.
+     * Useful for Bun.serve routes integration.
+     */
+    getAll(): Map<string, Map<string, (req: Request) => Response | Promise<Response>>>;
+}

package/dist/adapters/bun/RadixNode.d.ts

@@ -1,5 +1,5 @@
 import type { HttpMethod } from '../../http/types';
-import { NodeType, type RouteHandler } from './types';
+import { NodeType, type RouteHandler, type BunRouteOptions } from './types';
 /**
  * Node in the Radix Router tree.
  * @internal
@@ -11,9 +11,10 @@ export declare class RadixNode {
     paramChild: RadixNode | null;
     wildcardChild: RadixNode | null;
     handlers: Map<HttpMethod, RouteHandler[]>;
+    options: Map<HttpMethod, BunRouteOptions>;
     paramName: string | null;
     regex: RegExp | null;
     constructor(segment?: string, type?: NodeType);
-    toJSON(): any;
-    static fromJSON(json: any): RadixNode;
+    toJSON(): Record<string, unknown>;
+    static fromJSON(json: Record<string, unknown>): RadixNode;
 }

package/dist/adapters/bun/RadixRouter.d.ts

@@ -1,5 +1,5 @@
 import type { HttpMethod } from '../../http/types';
-import { type RouteHandler, type RouteMatch } from './types';
+import { type RouteHandler, type RouteMatch, type BunRouteOptions } from './types';
 /**
  * High-performance Radix Tree Router for Bun
  */
@@ -14,7 +14,7 @@ export declare class RadixRouter {
     /**
      * Register a route
      */
-    add(method: HttpMethod, path: string, handlers: RouteHandler[]): void;
+    add(method: HttpMethod, path: string, handlers: RouteHandler[], options?: BunRouteOptions): void;
     /**
      * Match a request
      */

package/dist/adapters/bun/types.d.ts

@@ -9,6 +9,13 @@ export type RouteHandler = Function;
 export interface RouteMatch {
     handlers: RouteHandler[];
     params: Record<string, string>;
+    options?: BunRouteOptions;
+}
+/**
+ * Route Options (Metadata)
+ */
+export interface BunRouteOptions {
+    excludeMiddleware?: string[];
 }
 /**
  * Radix Node Type

package/dist/adapters/types.d.ts

@@ -224,6 +224,26 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @returns Gravito context
      */
     createContext(request: Request): GravitoContext<V>;
+    /**
+     * Register an ultra-low latency route that bypasses the Gravito engine.
+     *
+     * @param method - HTTP method
+     * @param path - Exact route path (no wildcards or parameters)
+     * @param handler - Native fetch handler (Request => Response)
+     * @since 2.2.0
+     */
+    registerFastPath?(method: string, path: string, handler: (req: Request) => Response | Promise<Response>): void;
+    /**
+     * Generate configuration for the native HTTP engine.
+     *
+     * This allows offloading fast-path routes to the runtime's native router
+     * (e.g., Bun.serve({ routes: { ... } })).
+     *
+     * @param baseConfig - Base configuration to merge
+     * @returns Optimized engine configuration
+     * @since 2.2.0
+     */
+    serveConfig?(baseConfig?: Record<string, unknown>): Record<string, unknown>;
 }
 /**
  * Factory function type for creating adapters

package/dist/compat/async-local-storage.d.ts

@@ -3,5 +3,9 @@
  * Automatically switches between node:async_hooks and a browser mock.
  */
 export declare const AsyncLocalStorage: {
-    new <_T>(): any;
+    new <T>(): {
+        run<R>(store: T, fn: () => R): R;
+        getStore(): T | undefined;
+        disable(): void;
+    };
 };