@kurdel/runtime 0.1.0-beta.1

package/lib/app/runtime-application.js

@@ -0,0 +1,97 @@
+import { IoCContainer } from '@kurdel/ioc';
+import { TOKENS } from '@kurdel/core/tokens';
+import { ModuleLoader } from '../app/module-loader.js';
+import { LifecycleManager } from '../app/lifecycle-manager.js';
+import { ServerRunner } from '../app/server-runner.js';
+import { RuntimeComposer } from '../app/runtime-composer.js';
+/**
+ * kurdel runtime application.
+ *
+ * Coordinates module initialization, dependency registration,
+ * and server lifecycle within a single runtime instance.
+ *
+ * Responsibilities:
+ * - Aggregate declarations from user modules (controllers, middlewares, models)
+ * - Compose built-in runtime modules (server/router/middleware/model/database/lifecycle)
+ * - Initialize all modules via ModuleLoader and register providers in IoC
+ * - Manage application lifecycle (OnStart / OnShutdown)
+ * - Start and stop the HTTP server via ServerAdapter (no Node.js types leak)
+ *
+ * Design notes:
+ * - Lives entirely in runtime; consumers interact only through the public Application API
+ * - “IoC first”: every dependency is resolved via tokens and interfaces
+ * - Request scope creation is delegated to ServerModule (per-request)
+ */
+export class RuntimeApplication {
+    /** Read-only accessor exposing the underlying IoC container. */
+    get container() {
+        return this.ioc;
+    }
+    /**
+     * Construct a new runtime application.
+     *
+     * Steps performed:
+     *  - Store runtime configuration
+     *  - Compose the module pipeline (built-ins + user modules) via RuntimeComposer
+     */
+    constructor(config) {
+        /** Root IoC container — central registry for all runtime providers. */
+        this.ioc = new IoCContainer();
+        /** Handles lifecycle hook execution (OnStart / OnShutdown). */
+        this.lifecycle = new LifecycleManager();
+        this.config = config;
+        this.modules = RuntimeComposer.compose(config);
+    }
+    /**
+     * Add extra modules programmatically before bootstrap.
+     * Useful for integration tests or dynamic composition in code.
+     */
+    use(...modules) {
+        this.modules.push(...modules);
+    }
+    /**
+     * Bootstrap the runtime:
+     *  - Validate and initialize all modules
+     *  - Register declared providers into the IoC container
+     *  - Execute each module’s optional `register()` hook
+     *
+     * Must be called before `listen()`.
+     */
+    async bootstrap() {
+        const loader = new ModuleLoader(this.ioc);
+        await loader.init(this.modules, this.config);
+    }
+    /**
+     * Start the HTTP server via the registered ServerAdapter and return a handle.
+     *
+     * Lifecycle sequence:
+     *  1) Resolve ServerAdapter from IoC
+     *  2) Gather OnStart / OnShutdown hooks (LifecycleModule ensures their presence)
+     *  3) Delegate to ServerRunner to handle listen/close mechanics
+     *
+     * Supports both overloads:
+     *   - listen(port, callback)
+     *   - listen(port, host, callback)
+     */
+    listen(port, hostOrCb, cb) {
+        const adapter = this.ioc.get(TOKENS.ServerAdapter);
+        const onStart = this.ioc.has(TOKENS.OnStart)
+            ? this.ioc.get(TOKENS.OnStart)
+            : [];
+        const onShutdown = this.ioc.has(TOKENS.OnShutdown)
+            ? this.ioc.get(TOKENS.OnShutdown)
+            : [];
+        const runner = new ServerRunner(adapter, this.lifecycle);
+        return runner.listen(onStart, onShutdown, port, hostOrCb, cb);
+    }
+    /**
+     * Expose the underlying IoC container for advanced scenarios:
+     * diagnostics, module introspection, or test overrides.
+     *
+     * Prefer resolving dependencies via typed tokens in normal app code.
+     */
+    getContainer() {
+        return this.container;
+    }
+}
+//# sourceMappingURL=runtime-application.js.map

package/lib/app/runtime-application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-application.js","sourceRoot":"","sources":["../../src/app/runtime-application.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,kBAAkB;IAa7B,gEAAgE;IAChE,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,YAAY,MAAiB;QArB7B,uEAAuE;QACtD,QAAG,GAAG,IAAI,YAAY,EAAE,CAAC;QAK1C,+DAA+D;QAC9C,cAAS,GAAG,IAAI,gBAAgB,EAAE,CAAC;QAelD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,GAAG,OAAoB;QACzB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAY,EAAE,QAAgC,EAAE,EAAe;QACpE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAgB,MAAM,CAAC,aAAa,CAAC,CAAC;QAElE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;YAC1C,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAA0B,MAAM,CAAC,OAAO,CAAC;YACvD,CAAC,CAAC,EAAE,CAAC;QAEP,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC;YAChD,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAA0B,MAAM,CAAC,UAAU,CAAC;YAC1D,CAAC,CAAC,EAAE,CAAC;QAEP,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}

package/lib/app/runtime-composer.d.ts

@@ -0,0 +1,25 @@
+import { type AppConfig, type AppModule } from '@kurdel/core/app';
+/**
+ * ## RuntimeComposer
+ *
+ * Builds the deterministic runtime module chain for a Kurdel application.
+ * Responsible for aggregating user-defined HTTP modules and assembling
+ * framework modules in a well-defined initialization order.
+ */
+export declare class RuntimeComposer {
+    /** Default priority map for built-in modules. */
+    private static readonly DEFAULT_PRIORITIES;
+    /**
+     * Main composition entrypoint.
+     * @returns Ordered list of AppModules ready for initialization.
+     */
+    static compose(config: AppConfig): AppModule[];
+    /** Selects only modules exposing HTTP artifacts. */
+    private static extractHttpModules;
+    /** Aggregates HTTP declarations across all HttpModules. */
+    private static collectHttpArtifacts;
+    /** Sorts modules deterministically by priority. */
+    private static sortByPriority;
+    /** Ensures that no two modules register the same provider token. */
+    private static validateUniqueProviders;
+}

package/lib/app/runtime-composer.js

@@ -0,0 +1,100 @@
+import { ModulePriority } from '@kurdel/core/app';
+import { LifecycleModule } from '../modules/lifecycle-module.js';
+import { DatabaseModule } from '../modules/database-module.js';
+import { ModelModule } from '../modules/model-module.js';
+import { MiddlewareModule } from '../modules/middleware-module.js';
+import { ControllerModule } from '../modules/controller-module.js';
+import { ServerModule } from '../modules/server-module.js';
+import { ModuleValidationError } from '../app/errors/module-validation-error.js';
+/**
+ * ## RuntimeComposer
+ *
+ * Builds the deterministic runtime module chain for a Kurdel application.
+ * Responsible for aggregating user-defined HTTP modules and assembling
+ * framework modules in a well-defined initialization order.
+ */
+export class RuntimeComposer {
+    /**
+     * Main composition entrypoint.
+     * @returns Ordered list of AppModules ready for initialization.
+     */
+    static compose(config) {
+        const modules = config.modules ?? [];
+        const httpModules = this.extractHttpModules(modules);
+        const { models, controllers, middlewares } = this.collectHttpArtifacts(httpModules);
+        const unsorted = [
+            new LifecycleModule(),
+            new DatabaseModule(),
+            new ModelModule(models),
+            new MiddlewareModule(middlewares),
+            new ControllerModule(controllers),
+            new ServerModule(),
+            ...modules,
+        ];
+        const pipeline = this.sortByPriority(unsorted);
+        this.validateUniqueProviders(pipeline);
+        return pipeline;
+    }
+    // ------------------------------------------------------------
+    // Extraction helpers
+    // ------------------------------------------------------------
+    /** Selects only modules exposing HTTP artifacts. */
+    static extractHttpModules(modules) {
+        return modules.filter((m) => 'models' in m || 'controllers' in m || 'middlewares' in m);
+    }
+    /** Aggregates HTTP declarations across all HttpModules. */
+    static collectHttpArtifacts(httpModules) {
+        const models = httpModules.flatMap(m => m.models ?? []);
+        const controllers = httpModules.flatMap(m => m.controllers ?? []);
+        const middlewares = httpModules.flatMap(m => (m.middlewares ?? []).map((mw) => typeof mw === 'function'
+            ? { use: mw, zone: 'pre', priority: 0 }
+            : {
+                use: mw.use,
+                zone: mw.zone ?? 'pre',
+                priority: mw.priority ?? 0,
+                action: mw.action,
+            }));
+        return { models, controllers, middlewares };
+    }
+    // ------------------------------------------------------------
+    // Sorting and validation
+    // ------------------------------------------------------------
+    /** Sorts modules deterministically by priority. */
+    static sortByPriority(modules) {
+        return modules
+            .map((m, index) => ({
+            mod: m,
+            order: index,
+            prio: m.priority ??
+                RuntimeComposer.DEFAULT_PRIORITIES.get(m.constructor.name) ??
+                ModulePriority.User,
+        }))
+            .sort((a, b) => (a.prio === b.prio ? a.order - b.order : a.prio - b.prio))
+            .map(e => e.mod);
+    }
+    /** Ensures that no two modules register the same provider token. */
+    static validateUniqueProviders(modules) {
+        const tokenToModule = new Map();
+        for (const mod of modules) {
+            const moduleName = mod.constructor?.name ?? 'AnonymousModule';
+            for (const provider of mod.providers ?? []) {
+                const token = provider.provide;
+                const owner = tokenToModule.get(token);
+                if (owner) {
+                    throw new ModuleValidationError(`Duplicate provider for token "${String(token)}" between modules "${owner}" and "${moduleName}".`);
+                }
+                tokenToModule.set(token, moduleName);
+            }
+        }
+    }
+}
+/** Default priority map for built-in modules. */
+RuntimeComposer.DEFAULT_PRIORITIES = new Map([
+    ['LifecycleModule', ModulePriority.Lifecycle],
+    ['DatabaseModule', ModulePriority.Database],
+    ['ModelModule', ModulePriority.Model],
+    ['MiddlewareModule', ModulePriority.Middleware],
+    ['ControllerModule', ModulePriority.Controller],
+    ['ServerModule', ModulePriority.Server],
+]);
+//# sourceMappingURL=runtime-composer.js.map

package/lib/app/runtime-composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-composer.js","sourceRoot":"","sources":["../../src/app/runtime-composer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAkC,MAAM,kBAAkB,CAAC;AAUlF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAW1B;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,MAAiB;QAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;QAErC,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAEpF,MAAM,QAAQ,GAAgB;YAC5B,IAAI,eAAe,EAAE;YACrB,IAAI,cAAc,EAAE;YACpB,IAAI,WAAW,CAAC,MAAM,CAAC;YACvB,IAAI,gBAAgB,CAAC,WAAW,CAAC;YACjC,IAAI,gBAAgB,CAAC,WAAW,CAAC;YACjC,IAAI,YAAY,EAAE;YAClB,GAAG,OAAO;SACX,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QAEvC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,+DAA+D;IAC/D,qBAAqB;IACrB,+DAA+D;IAE/D,oDAAoD;IAC5C,MAAM,CAAC,kBAAkB,CAAC,OAAoB;QACpD,OAAO,OAAO,CAAC,MAAM,CACnB,CAAC,CAAC,EAAmB,EAAE,CAAC,QAAQ,IAAI,CAAC,IAAI,aAAa,IAAI,CAAC,IAAI,aAAa,IAAI,CAAC,CAClF,CAAC;IACJ,CAAC;IAED,2DAA2D;IACnD,MAAM,CAAC,oBAAoB,CAAC,WAAyB;QAC3D,MAAM,MAAM,GAAc,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QACnE,MAAM,WAAW,GAAuB,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QAEtF,MAAM,WAAW,GAA6B,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACpE,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAuC,EAAE,EAAE,CACpE,OAAO,EAAE,KAAK,UAAU;YACtB,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE;YACvC,CAAC,CAAC;gBACE,GAAG,EAAE,EAAE,CAAC,GAAG;gBACX,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,KAAK;gBACtB,QAAQ,EAAE,EAAE,CAAC,QAAQ,IAAI,CAAC;gBAC1B,MAAM,EAAE,EAAE,CAAC,MAAM;aAClB,CACN,CACF,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;IAC9C,CAAC;IAED,+DAA+D;IAC/D,yBAAyB;IACzB,+DAA+D;IAE/D,mDAAmD;IAC3C,MAAM,CAAC,cAAc,CAAC,OAAoB;QAChD,OAAO,OAAO;aACX,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAClB,GAAG,EAAE,CAAC;YACN,KAAK,EAAE,KAAK;YACZ,IAAI,EACF,CAAC,CAAC,QAAQ;gBACV,eAAe,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC;gBAC1D,cAAc,CAAC,IAAI;SACtB,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;aACzE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,oEAAoE;IAC5D,MAAM,CAAC,uBAAuB,CAAC,OAAoB;QACzD,MAAM,aAAa,GAAG,IAAI,GAAG,EAA2B,CAAC;QAEzD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,iBAAiB,CAAC;YAE9D,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC;gBAC/B,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAEvC,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,IAAI,qBAAqB,CAC7B,iCAAiC,MAAM,CAAC,KAAK,CAAC,sBAAsB,KAAK,UAAU,UAAU,IAAI,CAClG,CAAC;gBACJ,CAAC;gBAED,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;IACH,CAAC;;AA3GD,iDAAiD;AACzB,kCAAkB,GAAG,IAAI,GAAG,CAAiB;IACnE,CAAC,iBAAiB,EAAE,cAAc,CAAC,SAAS,CAAC;IAC7C,CAAC,gBAAgB,EAAE,cAAc,CAAC,QAAQ,CAAC;IAC3C,CAAC,aAAa,EAAE,cAAc,CAAC,KAAK,CAAC;IACrC,CAAC,kBAAkB,EAAE,cAAc,CAAC,UAAU,CAAC;IAC/C,CAAC,kBAAkB,EAAE,cAAc,CAAC,UAAU,CAAC;IAC/C,CAAC,cAAc,EAAE,cAAc,CAAC,MAAM,CAAC;CACxC,CAAC,CAAC"}

package/lib/app/server-runner.d.ts

@@ -0,0 +1,36 @@
+import type { ServerAdapter, RunningServer } from '@kurdel/core/http';
+import type { LifecycleManager } from '../app/lifecycle-manager.js';
+/**
+ * Orchestrates HTTP server startup and graceful shutdown.
+ *
+ * Responsibilities:
+ * - Bridge between the framework runtime and the low-level ServerAdapter.
+ * - Execute OnStart and OnShutdown lifecycle hooks in proper order.
+ * - Wrap the raw server handle into a consistent RunningServer API.
+ *
+ * Design notes:
+ * - ServerRunner is runtime-only; no Node.js types leak through public API.
+ * - Hook execution order:
+ *     - OnStart → forward order
+ *     - OnShutdown → reverse order (LIFO)
+ * - The per-request IoC scope is managed elsewhere (ServerModule).
+ */
+export declare class ServerRunner {
+    private readonly adapter;
+    private readonly lifecycle;
+    constructor(adapter: ServerAdapter, lifecycle: LifecycleManager);
+    /**
+     * Start the HTTP server and return a handle for runtime control.
+     *
+     * @param onStart - Hooks executed once the server signals readiness.
+     * @param onShutdown - Hooks executed during graceful shutdown.
+     * @param port - Port number to listen on.
+     * @param hostOrCb - Optional hostname or callback function.
+     * @param cb - Optional callback (if hostname was provided).
+     *
+     * Supports both call forms:
+     *   - listen(port, callback)
+     *   - listen(port, host, callback)
+     */
+    listen(onStart: (() => Promise<void>)[] | undefined, onShutdown: (() => Promise<void>)[] | undefined, port: number, hostOrCb?: string | (() => void), cb?: () => void): RunningServer;
+}

package/lib/app/server-runner.js

@@ -0,0 +1,65 @@
+/**
+ * Orchestrates HTTP server startup and graceful shutdown.
+ *
+ * Responsibilities:
+ * - Bridge between the framework runtime and the low-level ServerAdapter.
+ * - Execute OnStart and OnShutdown lifecycle hooks in proper order.
+ * - Wrap the raw server handle into a consistent RunningServer API.
+ *
+ * Design notes:
+ * - ServerRunner is runtime-only; no Node.js types leak through public API.
+ * - Hook execution order:
+ *     - OnStart → forward order
+ *     - OnShutdown → reverse order (LIFO)
+ * - The per-request IoC scope is managed elsewhere (ServerModule).
+ */
+export class ServerRunner {
+    constructor(adapter, lifecycle) {
+        this.adapter = adapter;
+        this.lifecycle = lifecycle;
+    }
+    /**
+     * Start the HTTP server and return a handle for runtime control.
+     *
+     * @param onStart - Hooks executed once the server signals readiness.
+     * @param onShutdown - Hooks executed during graceful shutdown.
+     * @param port - Port number to listen on.
+     * @param hostOrCb - Optional hostname or callback function.
+     * @param cb - Optional callback (if hostname was provided).
+     *
+     * Supports both call forms:
+     *   - listen(port, callback)
+     *   - listen(port, host, callback)
+     */
+    listen(onStart = [], onShutdown = [], port, hostOrCb, cb) {
+        // Normalize callback overloads
+        const userCb = typeof hostOrCb === 'function' ? hostOrCb : cb;
+        // Wrap user callback with lifecycle hook execution
+        const onReady = async () => {
+            await this.lifecycle.runHooks('start', onStart);
+            userCb?.();
+        };
+        // Call adapter.listen with correct overload
+        if (typeof hostOrCb === 'string') {
+            this.adapter.listen?.(port, hostOrCb, onReady);
+        }
+        else {
+            this.adapter.listen?.(port, onReady);
+        }
+        // Expose the running server handle
+        return {
+            /** Access the underlying server (if adapter exposes it) */
+            raw: this.adapter.raw?.bind(this.adapter),
+            /** Graceful shutdown: stop adapter, then run shutdown hooks (LIFO) */
+            close: async () => {
+                try {
+                    await Promise.resolve(this.adapter.close?.());
+                }
+                finally {
+                    await this.lifecycle.runHooks('shutdown', [...onShutdown].reverse());
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=server-runner.js.map

package/lib/app/server-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-runner.js","sourceRoot":"","sources":["../../src/app/server-runner.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAY;IACvB,YACmB,OAAsB,EACtB,SAA2B;QAD3B,YAAO,GAAP,OAAO,CAAe;QACtB,cAAS,GAAT,SAAS,CAAkB;IAC3C,CAAC;IAEJ;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,UAAmC,EAAE,EACrC,aAAsC,EAAE,EACxC,IAAY,EACZ,QAAgC,EAChC,EAAe;QAEf,+BAA+B;QAC/B,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAE9D,mDAAmD;QACnD,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;YACzB,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,EAAE,EAAE,CAAC;QACb,CAAC,CAAC;QAEF,4CAA4C;QAC5C,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QAED,mCAAmC;QACnC,OAAO;YACL,2DAA2D;YAC3D,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;YAEzC,sEAAsE;YACtE,KAAK,EAAE,KAAK,IAAI,EAAE;gBAChB,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAChD,CAAC;wBAAS,CAAC;oBACT,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/lib/http/index.d.ts

@@ -0,0 +1,6 @@
+export * from './is-http-error.js';
+export * from './noop-response-renderer.js';
+export * from './runtime-request-orchestrator.js';
+export * from './runtime-response-renderer.js';
+export * from './render-action-result.js';
+export * from './runtime-router.js';

package/lib/http/index.js

@@ -0,0 +1,7 @@
+export * from './is-http-error.js';
+export * from './noop-response-renderer.js';
+export * from './runtime-request-orchestrator.js';
+export * from './runtime-response-renderer.js';
+export * from './render-action-result.js';
+export * from './runtime-router.js';
+//# sourceMappingURL=index.js.map

package/lib/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC"}

package/lib/http/is-http-error.d.ts

@@ -0,0 +1,2 @@
+import type { HttpError } from '@kurdel/core/http';
+export declare function isHttpError(err: unknown): err is HttpError;

package/lib/http/is-http-error.js

@@ -0,0 +1,7 @@
+export function isHttpError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        typeof err.status === 'number');
+}
+//# sourceMappingURL=is-http-error.js.map

package/lib/http/is-http-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-http-error.js","sourceRoot":"","sources":["../../src/http/is-http-error.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,QAAQ,IAAI,GAAG;QACf,OAAQ,GAAW,CAAC,MAAM,KAAK,QAAQ,CACxC,CAAC;AACJ,CAAC"}

package/lib/http/noop-response-renderer.d.ts

@@ -0,0 +1,7 @@
+import type { HttpResponse } from '@kurdel/common';
+import type { ActionResult, ResponseRenderer } from '@kurdel/core/http';
+/** No-op renderer used for non-platform runtime tests. */
+export declare class NoopResponseRenderer implements ResponseRenderer {
+    render(_res: HttpResponse, _result: ActionResult | void): void;
+    handleError(_res: HttpResponse, _err: unknown): void;
+}

package/lib/http/noop-response-renderer.js

@@ -0,0 +1,10 @@
+/** No-op renderer used for non-platform runtime tests. */
+export class NoopResponseRenderer {
+    render(_res, _result) {
+        // do nothing
+    }
+    handleError(_res, _err) {
+        // do nothing
+    }
+}
+//# sourceMappingURL=noop-response-renderer.js.map

package/lib/http/noop-response-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-response-renderer.js","sourceRoot":"","sources":["../../src/http/noop-response-renderer.ts"],"names":[],"mappings":"AAGA,0DAA0D;AAC1D,MAAM,OAAO,oBAAoB;IAC/B,MAAM,CAAC,IAAkB,EAAE,OAA4B;QACrD,aAAa;IACf,CAAC;IAED,WAAW,CAAC,IAAkB,EAAE,IAAa;QAC3C,aAAa;IACf,CAAC;CACF"}

package/lib/http/render-action-result.d.ts

@@ -0,0 +1,4 @@
+import type { HttpResponse } from '@kurdel/common';
+import type { ActionResult } from '@kurdel/core/http';
+/** Node-bound renderer for ActionResult. */
+export declare function renderActionResult(res: HttpResponse, r: ActionResult): void;

package/lib/http/render-action-result.js

@@ -0,0 +1,24 @@
+/** Node-bound renderer for ActionResult. */
+export function renderActionResult(res, r) {
+    switch (r.kind) {
+        case 'json':
+            res.status(r.status).json(r.body);
+            break;
+        case 'text':
+            res.status(r.status).send(r.body);
+            break;
+        case 'html': {
+            const withHeaders = res;
+            withHeaders.setHeader?.('Content-Type', r.contentType ?? 'text/html; charset=utf-8');
+            res.status(r.status).send(r.body);
+            break;
+        }
+        case 'redirect':
+            res.redirect(r.status, r.location);
+            break;
+        case 'empty':
+            res.status(r.status).send('');
+            break;
+    }
+}
+//# sourceMappingURL=render-action-result.js.map

package/lib/http/render-action-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-action-result.js","sourceRoot":"","sources":["../../src/http/render-action-result.ts"],"names":[],"mappings":"AAIA,4CAA4C;AAC5C,MAAM,UAAU,kBAAkB,CAAC,GAAiB,EAAE,CAAe;IACnE,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,MAAM;YACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM;QACR,KAAK,MAAM;YACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM;QACR,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,WAAW,GAAG,GAA8B,CAAC;YACnD,WAAW,CAAC,SAAS,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC,WAAW,IAAI,0BAA0B,CAAC,CAAC;YACrF,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM;QACR,CAAC;QACD,KAAK,UAAU;YACb,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;YACnC,MAAM;QACR,KAAK,OAAO;YACV,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9B,MAAM;IACV,CAAC;AACH,CAAC"}

package/lib/http/runtime-controller-pipe.d.ts

@@ -0,0 +1,16 @@
+import type { HttpContext, Controller, Middleware, ActionResult } from '@kurdel/core/http';
+/**
+ * RuntimeControllerPipe
+ *
+ * Executes a controller action within a pre-assembled middleware chain.
+ *
+ * Notes:
+ * - The list of middlewares is prepared upstream (e.g. by RuntimeRequestOrchestrator)
+ * - ControllerPipe does not merge middlewares itself
+ * - If the action is missing, produces a 404 text result
+ */
+export declare class RuntimeControllerPipe<TReadable = unknown> {
+    private readonly middlewares;
+    constructor(middlewares?: readonly Middleware<HttpContext<any, any, TReadable>>[]);
+    run(controller: Controller<any>, ctx: HttpContext<unknown, Record<string, string>, TReadable>, actionName: string): Promise<ActionResult<TReadable> | void>;
+}

package/lib/http/runtime-controller-pipe.js

@@ -0,0 +1,26 @@
+import { RuntimeMiddlewarePipe } from '../http/runtime-middleware-pipe.js';
+/**
+ * RuntimeControllerPipe
+ *
+ * Executes a controller action within a pre-assembled middleware chain.
+ *
+ * Notes:
+ * - The list of middlewares is prepared upstream (e.g. by RuntimeRequestOrchestrator)
+ * - ControllerPipe does not merge middlewares itself
+ * - If the action is missing, produces a 404 text result
+ */
+export class RuntimeControllerPipe {
+    constructor(middlewares = []) {
+        this.middlewares = middlewares;
+    }
+    async run(controller, ctx, actionName) {
+        const handler = controller.getAction(actionName);
+        if (typeof handler !== 'function') {
+            return ctx.text(404, `Action '${actionName}' not found in '${controller.constructor.name}'.`);
+        }
+        const pipe = new RuntimeMiddlewarePipe(this.middlewares);
+        const result = await pipe.run(ctx, async () => (await handler.call(controller, ctx)));
+        return result;
+    }
+}
+//# sourceMappingURL=runtime-controller-pipe.js.map

package/lib/http/runtime-controller-pipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-controller-pipe.js","sourceRoot":"","sources":["../../src/http/runtime-controller-pipe.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAqB;IAChC,YACmB,cAAuE,EAAE;QAAzE,gBAAW,GAAX,WAAW,CAA8D;IACzF,CAAC;IAEJ,KAAK,CAAC,GAAG,CACP,UAA2B,EAC3B,GAA4D,EAC5D,UAAkB;QAElB,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAEjD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAClC,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,UAAU,mBAAmB,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC;QAChG,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,WAA2B,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAC3B,GAAG,EACH,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAA4B,CAC7E,CAAC;QAEF,OAAO,MAAwC,CAAC;IAClD,CAAC;CACF"}

package/lib/http/runtime-controller-resolver.d.ts

@@ -0,0 +1,12 @@
+import type { Newable } from '@kurdel/common';
+import type { Container } from '@kurdel/ioc';
+import type { ControllerResolver } from '@kurdel/core/http';
+export declare class RuntimeControllerResolver implements ControllerResolver {
+    private readonly root;
+    constructor(root: Container);
+    /**
+     * Resolve controller instance from the provided request scope.
+     * Falls back to the root container when not registered in the scope.
+     */
+    resolve<T>(cls: Newable<T>, scope?: Container): T;
+}

package/lib/http/runtime-controller-resolver.js

@@ -0,0 +1,29 @@
+export class RuntimeControllerResolver {
+    constructor(root) {
+        this.root = root;
+    }
+    /**
+     * Resolve controller instance from the provided request scope.
+     * Falls back to the root container when not registered in the scope.
+     */
+    resolve(cls, scope) {
+        const c = scope ?? this.root;
+        // Prefer request scope; if scope.has() falls back to parent itself, the try-get below is enough.
+        if (typeof c.has === 'function') {
+            if (c.has(cls))
+                return c.get(cls);
+            // fallback to root if scope doesn't have it AND has() doesn't climb parents
+            if (c !== this.root && this.root.has?.(cls))
+                return this.root.get(cls);
+        }
+        // If has() isn’t available or already climbs to parent, single get() is sufficient.
+        try {
+            return c.get(cls);
+        }
+        catch {
+            // Final fallback to root
+            return this.root.get(cls);
+        }
+    }
+}
+//# sourceMappingURL=runtime-controller-resolver.js.map

package/lib/http/runtime-controller-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-controller-resolver.js","sourceRoot":"","sources":["../../src/http/runtime-controller-resolver.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,yBAAyB;IACpC,YAA6B,IAAe;QAAf,SAAI,GAAJ,IAAI,CAAW;IAAG,CAAC;IAEhD;;;OAGG;IACH,OAAO,CAAI,GAAe,EAAE,KAAiB;QAC3C,MAAM,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC;QAE7B,iGAAiG;QACjG,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;YACrC,4EAA4E;YAC5E,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QAC5E,CAAC;QAED,oFAAoF;QACpF,IAAI,CAAC;YACH,OAAO,CAAC,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;YACzB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;CACF"}

package/lib/http/runtime-http-context-factory.d.ts

@@ -0,0 +1,29 @@
+import type { HttpRequest, HttpResponse } from '@kurdel/common';
+import type { Container } from '@kurdel/ioc';
+import type { HttpContext, RouteMatch } from '@kurdel/core/http';
+/**
+ * ## RuntimeHttpContextFactory
+ *
+ * Responsible for constructing per-request {@link HttpContext} objects.
+ *
+ * Each incoming request receives a fresh, isolated context encapsulating:
+ * - HTTP request/response wrappers provided by the adapter
+ * - parsed URL, query, params, body
+ * - matched route metadata (controller/action/schema/auth)
+ * - a request-scoped IoC container
+ * - typed constructors for {@link ActionResult}
+ *
+ * The context object is immutable except for `result`,
+ * which is later populated by the orchestrator and renderer.
+ */
+export declare class RuntimeHttpContextFactory {
+    /**
+     * Constructs a fully initialized {@link HttpContext} instance.
+     *
+     * @param req    - incoming HTTP request
+     * @param res    - outgoing HTTP response
+     * @param match  - router resolution result
+     * @param scope  - request-scoped IoC container
+     */
+    create(req: HttpRequest, res: HttpResponse, match: RouteMatch, scope: Container): HttpContext;
+}