@getstrata/bootstrap 2.0.9 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @getstrata/bootstrap changelog
 
+## 2.2.0
+
+Consistent model scopes.
+Changed-field model writes.
+Awaited provider startup.
+Shared cache correctness.
+Native HTTP controls and body limits.
+Graceful lifecycle.
+Validated async discovery.
+Stronger model input types.
+OpenTelemetry tracing.
+Distributed scheduler ownership.
+App-owned quota policy.
+Bounded memory throttling.
+
+## Unreleased
+
+- Provide shared tracing provider ownership and phased OpenTelemetry flush/shutdown without replacing application global tracer providers.
+
+- Breaking source contract: `discoverJobs()` and `discoverListeners()` now return promises. Await ESM discovery before queue construction or listener boot; malformed exports and duplicate discovered identities fail visibly. Add explicit job/listener/module manifests for bundles, preserve custom job factories, evict failed discovery loads and protect publication after reset. See `docs/DISCOVERY.md` before release/adoption.
+
+- Make provider startup awaited, register all providers before boot, and expose idempotent context disposal with failure cleanup. Direct startup helper callers must now await; appContext getters require completed startup.
+
+- Add awaited model discovery with nested exports, two-phase naming/boot, duplicate-name detection and startup error propagation.
+
+## 2.1.0
+
+- refactor(starter): reuse shared config and base repositories - fix(database): await password casts before model writes - fix(database): preserve concrete model types in query results
+
 ## 2.0.9
 
 - fix(starter): remove demo credentials from public login defaults

package/README.md

@@ -48,7 +48,7 @@ HTML apps should bind `createCookieSessionAuthManager` from `@getstrata/bootstra
 
 ## Queue
 
-`registerDefaultJobs()` registers `cache.invalidate-tags` and `audit.export` only. Outbound model webhooks are not a core job. Put a class with `static jobName` in `src/jobs/` (generated `--webhooks` uses `webhook.dispatch`) and call `discoverJobs()` on boot. `queue:work` already does that. There is no `registerWebhookJobs()` export.
+`registerDefaultJobs()` registers `cache.invalidate-tags` and `audit.export` only. Outbound model webhooks are not a core job. Put a class with `static jobName` in `src/jobs/` (generated `--webhooks` uses `webhook.dispatch`) and call `await discoverJobs()` on boot. `queue:work` already does that. There is no `registerWebhookJobs()` export.
 
 ## Not a starter API
 

package/dist/bootstrap/app.d.ts

@@ -1,6 +1,12 @@
+import { type ShutdownResult } from "@getstrata/core/lifecycle/gracefulShutdown";
 declare class App {
     private server?;
-    serve(): void;
+    private startup?;
+    private lifecycle?;
+    private uninstallSignals?;
+    serve(): Promise<void>;
+    private start;
+    shutdown(reason?: string): Promise<ShutdownResult>;
     stop(force?: boolean): void;
     private resolvePort;
 }

package/dist/bootstrap/config.d.ts

@@ -4,7 +4,7 @@ declare const CACHE_MAX_ENTRIES_CONFIG_KEY = "cache.maxEntries";
 declare const CACHE_DRIVER_CONFIG_KEY = "cache.driver";
 declare const REDIS_URL_CONFIG_KEY = "cache.redisUrl";
 declare const DATABASE_URL_CONFIG_KEY = "database.url";
-export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_QUEUE_TOKEN, CORE_TOKEN_SERVICE_TOKEN, } from "@getstrata/core/contracts/serviceTokens";
+export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_QUEUE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TOKEN_SERVICE_TOKEN, } from "@getstrata/core/contracts/serviceTokens";
 declare const AUTH_DEV_HEADERS_CONFIG_KEY = "auth.allowDevHeaders";
 declare const DEFAULT_APP_PORT = 3000;
 declare const DEFAULT_CACHE_TTL_MS = 3600000;

package/dist/bootstrap/context.d.ts

@@ -1,6 +1,12 @@
 import { type AppContext, type AppModule, type ProviderContext, type ServiceProvider } from "./contracts";
+type InitializedAppContext = AppContext & {
+    drain(): Promise<void>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+};
 declare function collectProviders(modules?: AppModule[]): ServiceProvider[];
-declare function runProviderPhase(providers: ServiceProvider[], phase: "register" | "boot", context: ProviderContext): void;
-declare function createAppContext(): AppContext;
+declare function runProviderPhase(providers: readonly ServiceProvider[], phase: "register" | "boot", context: ProviderContext): Promise<void>;
+declare function createAppContext(providers?: readonly ServiceProvider[]): Promise<InitializedAppContext>;
 declare const appContext: AppContext;
+export type { InitializedAppContext };
 export { appContext, collectProviders, createAppContext, runProviderPhase };

package/dist/bootstrap/contracts.d.ts

@@ -1,4 +1,4 @@
-export { ConfigStore, type ConfigStoreLike, ServiceContainer, type ServiceContainerLike, } from "@getstrata/core/contracts/container";
+export { ConfigStore, type ConfigStoreLike, createServiceToken, ServiceContainer, type ServiceContainerLike, type ServiceToken, } from "@getstrata/core/contracts/container";
 export type { AppContext, AppDependencies, AppRouteMap, CachedJson, MutableAppDependencies, ProviderContext, ServiceFactory, ServiceProvider, } from "@getstrata/core/contracts/di";
 export { assertAppDependenciesComplete, getRequiredDependency, resolveService, } from "@getstrata/core/contracts/di";
 import type { AppDependencies, AppRouteMap, CachedJson, ServiceProvider } from "@getstrata/core/contracts/di";

package/dist/bootstrap/dependencies.d.ts

@@ -1,4 +1,4 @@
 import { createAppContext } from "./context";
-declare function createAppDependencies(): import("./contracts").AppDependencies;
+declare function createAppDependencies(): Promise<import("./contracts").AppDependencies>;
 export type { AppContext, AppDependencies } from "./contracts";
 export { createAppContext, createAppDependencies };

package/dist/bootstrap/discoverJobs.d.ts

@@ -1,8 +1,16 @@
-import type { Job } from "@getstrata/core/queue";
+import { Job } from "@getstrata/core/queue";
+import { type InfrastructureDiscoveryOptions } from "./infrastructureDiscovery";
 type DiscoveredJobClass = (new () => Job) & {
     jobName: string;
 };
-declare function discoverJobs(): string[];
+type JobManifestEntry = DiscoveredJobClass | {
+    name: string;
+    create: () => Job;
+};
+interface DiscoverJobsOptions extends InfrastructureDiscoveryOptions {
+    manifest?: readonly JobManifestEntry[];
+}
+declare function discoverJobs(options?: DiscoverJobsOptions): Promise<string[]>;
 declare function resetDiscoverJobsForTests(): void;
-export type { DiscoveredJobClass };
+export type { DiscoveredJobClass, DiscoverJobsOptions, JobManifestEntry };
 export { discoverJobs, resetDiscoverJobsForTests };

package/dist/bootstrap/discoverListeners.d.ts

@@ -1,5 +1,9 @@
-type ListenerRegistrar = () => void;
-declare function discoverListeners(): ListenerRegistrar[];
+import { type InfrastructureDiscoveryOptions } from "./infrastructureDiscovery";
+type ListenerRegistrar = () => void | Promise<void>;
+interface DiscoverListenersOptions extends InfrastructureDiscoveryOptions {
+    manifest?: readonly ListenerRegistrar[];
+}
+declare function discoverListeners(options?: DiscoverListenersOptions): Promise<ListenerRegistrar[]>;
 declare function resetDiscoverListenersForTests(): void;
-export type { ListenerRegistrar };
+export type { DiscoverListenersOptions, ListenerRegistrar };
 export { discoverListeners, resetDiscoverListenersForTests };

package/dist/bootstrap/discoverModels.d.ts

@@ -0,0 +1,8 @@
+/** Import trusted application model modules, then bind and boot their exported classes. */
+interface DiscoverModelsOptions {
+    /** Startup orchestration files are not model modules; avoids importing the awaiting caller. */
+    exclude?: readonly string[];
+}
+declare function discoverModels(directory?: string, options?: DiscoverModelsOptions): Promise<object[]>;
+export type { DiscoverModelsOptions };
+export { discoverModels };

package/dist/bootstrap/discoverModules.d.ts

@@ -1,10 +1,13 @@
 import type { AppModule } from "./contracts";
 interface DiscoverModulesOptions {
     modulesDir?: string;
+    exclude?: readonly string[];
+    manifest?: readonly AppModule[];
 }
 declare function configureModulesDirectory(modulesDir: string): void;
+declare function configureModulesManifest(manifest: readonly AppModule[]): void;
 declare function ensureModulesLoaded(options?: DiscoverModulesOptions): Promise<AppModule[]>;
 declare function discoverModules(): AppModule[];
 declare function resetDiscoverModulesForTests(): void;
 export type { DiscoverModulesOptions };
-export { configureModulesDirectory, discoverModules, ensureModulesLoaded, resetDiscoverModulesForTests, };
+export { configureModulesDirectory, configureModulesManifest, discoverModules, ensureModulesLoaded, resetDiscoverModulesForTests, };

package/dist/bootstrap/httpKernel.d.ts

@@ -6,33 +6,38 @@ type MiddlewareGroupName = "api" | "authenticated" | "web";
 type WebGuestHome = string | ((user: AuthUser) => string | Promise<string>);
 declare class HttpKernel {
     private readonly dependencies;
+    private readonly ownedThrottles;
+    private disposed;
     constructor(dependencies: AppDependencies);
+    dispose(): void;
+    /** Own custom disposable throttle middleware until this application closes. */
+    ownThrottle<T extends Middleware>(throttle: T): T;
     globalMiddleware(errorFormat?: "json" | "web"): Middleware[];
     group(name: MiddlewareGroupName): Middleware[];
-    wrap(groups: MiddlewareGroupName | MiddlewareGroupName[], handler: RouteHandler): RouteHandler;
-    wrapApi(handler: RouteHandler): RouteHandler;
-    wrapWeb(handler: RouteHandler): RouteHandler;
+    wrap<TRequest extends Request = Request>(groups: MiddlewareGroupName | MiddlewareGroupName[], handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapApi<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapWeb<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
     /** Signed-in HTML users redirect to `home` instead of seeing guest pages. */
-    wrapWebGuest(handler: RouteHandler, home?: WebGuestHome): RouteHandler;
-    wrapWebPublicRead(handler: RouteHandler): RouteHandler;
-    wrapWebAuthenticated(handler: RouteHandler): RouteHandler;
+    wrapWebGuest<TRequest extends Request = Request>(handler: RouteHandler<TRequest>, home?: WebGuestHome): RouteHandler<TRequest>;
+    wrapWebPublicRead<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapWebAuthenticated<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
     /** Signed-in HTML without the email-verified gate (logout, verification notice). */
-    wrapWebAuthenticatedAllowUnverified(handler: RouteHandler): RouteHandler;
-    wrapWebVerified(handler: RouteHandler): RouteHandler;
+    wrapWebAuthenticatedAllowUnverified<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapWebVerified<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
     /** Requires a fresh signed password-confirmation cookie. */
-    wrapWebPasswordConfirm(handler: RouteHandler): RouteHandler;
-    wrapWebAbility(ability: string, handler: RouteHandler): RouteHandler;
-    wrapWebGlobalAdmin(handler: RouteHandler): RouteHandler;
-    wrapAuthenticated(handler: RouteHandler): RouteHandler;
+    wrapWebPasswordConfirm<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapWebAbility<TRequest extends Request = Request>(ability: string, handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapWebGlobalAdmin<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapAuthenticated<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
     /** JSON routes that require a verified email. No-op when `FEATURE_EMAIL_VERIFICATION` is off. */
-    wrapVerified(handler: RouteHandler): RouteHandler;
-    wrapPublicRead(handler: RouteHandler): RouteHandler;
-    wrapGlobalAdmin(handler: RouteHandler): RouteHandler;
-    wrapAbility(ability: string, handler: RouteHandler): RouteHandler;
-    wrapPolicy(resource: string, action: keyof Policy, handler: RouteHandler): RouteHandler;
-    wrapLogin(handler: RouteHandler): RouteHandler;
-    wrapSigned(handler: RouteHandler): RouteHandler;
-    wrapRegister(handler: RouteHandler): RouteHandler;
+    wrapVerified<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapPublicRead<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapGlobalAdmin<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapAbility<TRequest extends Request = Request>(ability: string, handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapPolicy<TRequest extends Request = Request>(resource: string, action: keyof Policy, handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapLogin<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapSigned<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
+    wrapRegister<TRequest extends Request = Request>(handler: RouteHandler<TRequest>): RouteHandler<TRequest>;
     private wrapWebAuth;
     private verifiedMiddleware;
     private wrapThrottle;

package/dist/bootstrap/inProcessCron.d.ts

@@ -1,4 +1,5 @@
 import "./schedule";
 declare function startInProcessCronIfEnabled(): void;
 declare function stopInProcessCron(): void;
-export { startInProcessCronIfEnabled, stopInProcessCron };
+declare function drainInProcessCron(): Promise<void>;
+export { drainInProcessCron, startInProcessCronIfEnabled, stopInProcessCron };

package/dist/bootstrap/infrastructureDiscovery.d.ts

@@ -0,0 +1,9 @@
+interface InfrastructureDiscoveryOptions {
+    directory?: string;
+    /** Relative paths or basenames; exclusions apply before importing. */
+    exclude?: readonly string[];
+}
+declare function infrastructureFiles(directory: string, exclude?: readonly string[]): Promise<string[]>;
+declare function importInfrastructure(file: string): Promise<Record<string, unknown>>;
+export type { InfrastructureDiscoveryOptions };
+export { importInfrastructure, infrastructureFiles };

package/dist/bootstrap/modules.d.ts

@@ -1 +1 @@
-export { configureModulesDirectory, discoverModules, ensureModulesLoaded, } from "./discoverModules";
+export { configureModulesDirectory, configureModulesManifest, discoverModules, ensureModulesLoaded, } from "./discoverModules";

package/dist/bootstrap/providers/tracing.d.ts

@@ -0,0 +1,3 @@
+import type { ServiceProvider } from "../contracts";
+declare const tracingProvider: ServiceProvider;
+export default tracingProvider;

package/dist/bootstrap/public-api.d.ts

@@ -1,8 +1,8 @@
 /**
  * @getstrata/bootstrap: application shell for Strata apps.
  */
-export type { ScheduledTask } from "@getstrata/core/scheduler/schedule";
-export { appSchedule, runDueScheduledTasks, Schedule } from "@getstrata/core/scheduler/schedule";
+export type { ScheduledTask, ScheduledTaskContext, SchedulerLease, SchedulerLeaseStore, SchedulerRunOptions, } from "@getstrata/core/scheduler/schedule";
+export { appSchedule, RedisSchedulerLeaseStore, runDueScheduledTasks, Schedule, SchedulerLeaseLostError, } from "@getstrata/core/scheduler/schedule";
 export { resolveApplicationAuth, resolveApplicationCache, resolveApplicationConfig, resolveApplicationDependencies, resolveApplicationEventBus, resolveApplicationLogger, resolveApplicationPolicyGate, resolveApplicationQueue, setActiveApplicationContext, } from "./applicationRegistry.ts";
 export type { BuildModuleRoutesOptions } from "./buildModuleRoutes.ts";
 export { buildModuleRoutes } from "./buildModuleRoutes.ts";
@@ -10,15 +10,19 @@ export type { BuildWebModuleRoutesOptions } from "./buildWebModuleRoutes.ts";
 export { buildWebModuleRoutes } from "./buildWebModuleRoutes.ts";
 export { cacheTagsForModelWrite, discoverModelTableNames } from "./cache/modelCacheTags.ts";
 export { APP_PORT_CONFIG_KEY, CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_QUEUE_TOKEN, CORE_TOKEN_SERVICE_TOKEN, DATABASE_URL_CONFIG_KEY, DEFAULT_APP_PORT, REDIS_URL_CONFIG_KEY, } from "./config.ts";
+export type { InitializedAppContext } from "./context.ts";
 export { collectProviders, createAppContext, runProviderPhase } from "./context.ts";
 export type { AppContext, AppDependencies, AppModule, AppRouteMap, CachedJson, ConfigStore, ModuleRouteContext, MutableAppDependencies, ProviderContext, ServiceFactory, ServiceProvider, } from "./contracts.ts";
 export { assertAppDependenciesComplete, getRequiredDependency, resolveService, ServiceContainer, } from "./contracts.ts";
 export type { CreateWebRoutesOptions } from "./createWebRoutes.ts";
 export { createWebRoutes, mergeWebRoutes } from "./createWebRoutes.ts";
 export { createAppDependencies } from "./dependencies.ts";
+export type { DiscoveredJobClass, DiscoverJobsOptions, JobManifestEntry } from "./discoverJobs.ts";
 export { discoverJobs, resetDiscoverJobsForTests } from "./discoverJobs.ts";
+export type { DiscoverModelsOptions } from "./discoverModels.ts";
+export { discoverModels } from "./discoverModels.ts";
 export type { DiscoverModulesOptions } from "./discoverModules.ts";
-export { configureModulesDirectory, discoverModules, ensureModulesLoaded, } from "./discoverModules.ts";
+export { configureModulesDirectory, configureModulesManifest, discoverModules, ensureModulesLoaded, } from "./discoverModules.ts";
 export type { CreateHealthRoutesOptions } from "./health.ts";
 export { checkDatabase, checkRedis, createHealthRoutes, pingDatabase } from "./health.ts";
 export { type RouteModelAuthorization, securedBindRouteModel, securedBindRouteModelByKey, } from "./http/securedRouteModelBinding.ts";
@@ -26,7 +30,8 @@ export { createHttpKernel, type HttpKernel, type MiddlewareGroupName } from "./h
 export { resolveMembershipService } from "./membershipService.ts";
 export { prefixRouteMap } from "./prefixRouteMap.ts";
 export { coreProviders } from "./providers/index.ts";
+export { default as tracingProvider } from "./providers/tracing.ts";
 export { registerDefaultJobs } from "./queue/defaultJobs.ts";
 export { RouteRegistry, routeRegistry } from "./routeRegistry.ts";
 export { assertProductionSecrets } from "./secretsGuard.ts";
-export { CookieSessionAuthManager, CookieSessionGuard, CookieSessionStore, createCookieSessionAuthManager, createCsrfProtection, createRouteKernel, createWebServer, type LoadSessionUser, type MapSessionUser, type ParsedForm, parseFormBody, routeParams, type SessionUser, slugify, toRouteRequest, type WebServerOptions, wrapSecuredRouteModelByKey, wrapWebLogin, wrapWebRegister, } from "./web/index.ts";
+export { CookieSessionAuthManager, CookieSessionGuard, CookieSessionStore, createCookieSessionAuthManager, createCsrfProtection, createRouteKernel, createWebServer, type LoadSessionUser, type MapSessionUser, type NativeServerOptions, type ParsedForm, parseFormBody, routeParams, type SessionUser, slugify, toRouteRequest, type WebServerOptions, wrapSecuredRouteModelByKey, wrapWebLogin, wrapWebRegister, } from "./web/index.ts";

package/dist/bootstrap/web/index.d.ts

@@ -3,6 +3,6 @@
  */
 export { createCsrfProtection, type ParsedForm, parseFormBody } from "./forms.ts";
 export { createRouteKernel, routeParams, toRouteRequest, wrapSecuredRouteModelByKey, wrapWebLogin, wrapWebRegister, } from "./routing.ts";
-export { convertAppRoutesToBunRoutes, createWebServer, type WebServerOptions } from "./server.ts";
+export { convertAppRoutesToBunRoutes, createWebServer, type NativeServerOptions, type WebServerOptions, } from "./server.ts";
 export { CookieSessionAuthManager, CookieSessionGuard, CookieSessionStore, createCookieSessionAuthManager, type LoadSessionUser, type MapSessionUser, type SessionUser, } from "./session.ts";
 export { slugify } from "./slug.ts";

package/dist/bootstrap/web/routing.d.ts

@@ -21,8 +21,8 @@ export declare function wrapSecuredRouteModelByKey<TParams extends Record<string
     etag?: boolean;
 }, handler: (request: RouteRequest<TParams>, model: TModel) => Response | Promise<Response>): RouteHandler;
 /** Web group (CSRF + flash + HTML errors) plus login throttle. Do not wrap with wrapWeb again. */
-export declare function wrapWebLogin(kernel: HttpKernel, handler: RouteHandler, onThrottled: (request: Request) => Response | Promise<Response>): RouteHandler;
+export declare function wrapWebLogin<TRequest extends Request = Request>(kernel: HttpKernel, handler: RouteHandler<TRequest>, onThrottled: (request: TRequest) => Response | Promise<Response>): RouteHandler<TRequest>;
 /** Web group (CSRF + flash + HTML errors) plus register throttle. Do not wrap with wrapWeb again. */
-export declare function wrapWebRegister(kernel: HttpKernel, handler: RouteHandler, onThrottled: (request: Request) => Response | Promise<Response>): RouteHandler;
+export declare function wrapWebRegister<TRequest extends Request = Request>(kernel: HttpKernel, handler: RouteHandler<TRequest>, onThrottled: (request: TRequest) => Response | Promise<Response>): RouteHandler<TRequest>;
 /** Convenience alias for `createHttpKernel`. */
 export declare function createRouteKernel(dependencies: AppDependencies): HttpKernel;

package/dist/bootstrap/web/server.d.ts

@@ -1,16 +1,24 @@
 import { type CorsOptions } from "@getstrata/core/http/corsMiddleware";
-import type { BunRequest, Server } from "bun";
+import type { LifecycleCoordinator } from "@getstrata/core/lifecycle/gracefulShutdown";
+import type { BunRequest, Serve, Server } from "bun";
 import type { AppRouteMap } from "../contracts.ts";
-export interface WebServerOptions {
+export type NativeServerOptions<T = unknown> = Omit<Serve.HostnamePortServeOptions<T>, "port"> & {
+    websocket?: Bun.WebSocketHandler<T>;
+};
+export interface WebServerOptions<T = unknown> {
     port: number;
-    handle?: (request: Request) => Promise<Response | null> | Response | null;
+    handle?: (request: Request, server: Server<T>) => Promise<Response | null | undefined> | Response | null | undefined;
+    /** Bun transport options. Framework dispatch and route composition remain owned here. */
+    native?: NativeServerOptions<T>;
+    lifecycle?: LifecycleCoordinator;
     routes?: AppRouteMap;
     publicDir?: string;
     /** Additional approved headers for synthesized route preflights; origins still use framework policy. */
     cors?: CorsOptions;
-    onRequest?: (request: Request) => Promise<void> | void;
+    onRequest?: (request: Request, server: Server<T>) => Promise<void | Response> | void | Response;
 }
-type BunRouteHandler = (request: BunRequest, server: Server<unknown>) => Response | Promise<Response>;
-declare function convertAppRoutesToBunRoutes(routes: AppRouteMap, cors?: CorsOptions): Record<string, Record<string, BunRouteHandler>>;
-export declare function createWebServer(options: WebServerOptions): Server<undefined>;
+type TrackRequest = <T>(work: () => Promise<T>) => Promise<T>;
+type BunRouteHandler<T = unknown> = (request: BunRequest, server: Server<T>) => Response | Promise<Response>;
+declare function convertAppRoutesToBunRoutes<T = unknown>(routes: AppRouteMap, cors?: CorsOptions, onRequest?: WebServerOptions<T>["onRequest"], track?: TrackRequest): Record<string, Record<string, BunRouteHandler<T>>>;
+export declare function createWebServer<T = unknown>(options: WebServerOptions<T>): Server<T>;
 export { convertAppRoutesToBunRoutes };