@kurdel/runtime 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andrii Sorokin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @kurdel/runtime
+
+Runtime **implementation layer** of Kurdel.  
+Includes router, controller resolver, lifecycle orchestration, and middleware handling.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @kurdel/runtime
+````
+
+---
+
+## 🧩 Responsibilities
+
+* Routing and controller dispatch
+* Middleware registry and composition
+* Module loading and lifecycle management
+* Template engine integration (via `TemplateEngine` interface)
+
+---
+
+## 🚀 Example
+
+```ts
+import { route, Controller, Ok } from '@kurdel/core/http';
+
+export class PingController extends Controller {
+  readonly routes = {
+    ping: route({ method: 'GET', path: '/ping' })(this.ping),
+  };
+  async ping() { return Ok({ ok: true }); }
+}
+```
+
+Used indirectly via `@kurdel/facade`.
+
+---
+
+## 📄 License
+
+MIT © Andrii Sorokin

package/lib/app/errors/controller-action-missing-result-error.d.ts

@@ -0,0 +1,9 @@
+import { HttpError } from '@kurdel/core/http';
+import type { Controller } from '@kurdel/core/http';
+/**
+ * Thrown when a controller action returns `undefined`,
+ * which violates the ActionResult contract.
+ */
+export declare class ControllerActionMissingResultError extends HttpError {
+    constructor(controller: Controller, action: string);
+}

package/lib/app/errors/controller-action-missing-result-error.js

@@ -0,0 +1,14 @@
+import { HttpError } from '@kurdel/core/http';
+/**
+ * Thrown when a controller action returns `undefined`,
+ * which violates the ActionResult contract.
+ */
+export class ControllerActionMissingResultError extends HttpError {
+    constructor(controller, action) {
+        super(500, `Controller action returned undefined: ${controller.constructor.name}.${action}`, {
+            controller: controller.constructor.name,
+            action,
+        });
+    }
+}
+//# sourceMappingURL=controller-action-missing-result-error.js.map

package/lib/app/errors/controller-action-missing-result-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-action-missing-result-error.js","sourceRoot":"","sources":["../../../src/app/errors/controller-action-missing-result-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C;;;GAGG;AACH,MAAM,OAAO,kCAAmC,SAAQ,SAAS;IAC/D,YAAY,UAAsB,EAAE,MAAc;QAChD,KAAK,CACH,GAAG,EACH,yCAAyC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,MAAM,EAAE,EAChF;YACE,UAAU,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI;YACvC,MAAM;SACP,CACF,CAAC;IACJ,CAAC;CACF"}

package/lib/app/errors/module-validation-error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Thrown when a module fails structural or dependency validation
+ * during the application bootstrap phase.
+ *
+ * Typical causes:
+ * - Duplicate provider tokens declared across multiple modules
+ * - Missing imported tokens that were never exported by any module
+ * - Declared exports that are not actually registered in the container
+ *
+ * This error represents a higher-level composition problem —
+ * it indicates that the module graph itself is inconsistent,
+ * not an issue within a single provider definition.
+ *
+ * @example
+ * ```ts
+ * throw new ModuleValidationError(
+ *   `Duplicate provider for token "${String(token)}" between modules "${a}" and "${b}".`
+ * );
+ * ```
+ *
+ * @see ProviderConfigurationError - for per-provider misconfiguration
+ */
+export declare class ModuleValidationError extends Error {
+    constructor(message: string);
+}

package/lib/app/errors/module-validation-error.js

@@ -0,0 +1,29 @@
+/**
+ * Thrown when a module fails structural or dependency validation
+ * during the application bootstrap phase.
+ *
+ * Typical causes:
+ * - Duplicate provider tokens declared across multiple modules
+ * - Missing imported tokens that were never exported by any module
+ * - Declared exports that are not actually registered in the container
+ *
+ * This error represents a higher-level composition problem —
+ * it indicates that the module graph itself is inconsistent,
+ * not an issue within a single provider definition.
+ *
+ * @example
+ * ```ts
+ * throw new ModuleValidationError(
+ *   `Duplicate provider for token "${String(token)}" between modules "${a}" and "${b}".`
+ * );
+ * ```
+ *
+ * @see ProviderConfigurationError - for per-provider misconfiguration
+ */
+export class ModuleValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ModuleValidationError';
+    }
+}
+//# sourceMappingURL=module-validation-error.js.map

package/lib/app/errors/module-validation-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-validation-error.js","sourceRoot":"","sources":["../../../src/app/errors/module-validation-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/lib/app/errors/provider-configuration-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thrown when a provider declaration is structurally valid
+ * but logically inconsistent with IoC container rules.
+ *
+ * Typical causes:
+ * - Declaring an async factory without marking it as `singleton`
+ * - Using `useFactory` or `useClass` with incompatible `deps`
+ * - Attempting to bind a provider that resolves to `undefined`
+ *
+ * This error indicates a configuration problem within a single
+ * provider definition, not a higher-level module composition issue.
+ *
+ * @example
+ * ```ts
+ * throw new ProviderConfigurationError(
+ *   `Async factory for "${String(provider.provide)}" must be declared as singleton.`
+ * );
+ * ```
+ *
+ * @see ModuleValidationError - for module-level composition issues
+ */
+export declare class ProviderConfigurationError extends Error {
+    constructor(message: string);
+}

package/lib/app/errors/provider-configuration-error.js

@@ -0,0 +1,28 @@
+/**
+ * Thrown when a provider declaration is structurally valid
+ * but logically inconsistent with IoC container rules.
+ *
+ * Typical causes:
+ * - Declaring an async factory without marking it as `singleton`
+ * - Using `useFactory` or `useClass` with incompatible `deps`
+ * - Attempting to bind a provider that resolves to `undefined`
+ *
+ * This error indicates a configuration problem within a single
+ * provider definition, not a higher-level module composition issue.
+ *
+ * @example
+ * ```ts
+ * throw new ProviderConfigurationError(
+ *   `Async factory for "${String(provider.provide)}" must be declared as singleton.`
+ * );
+ * ```
+ *
+ * @see ModuleValidationError - for module-level composition issues
+ */
+export class ProviderConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProviderConfigurationError';
+    }
+}
+//# sourceMappingURL=provider-configuration-error.js.map

package/lib/app/errors/provider-configuration-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-configuration-error.js","sourceRoot":"","sources":["../../../src/app/errors/provider-configuration-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/lib/app/index.d.ts

@@ -0,0 +1 @@
+export { RuntimeApplication } from './runtime-application.js';

package/lib/app/index.js

@@ -0,0 +1,2 @@
+export { RuntimeApplication } from './runtime-application.js';
+//# sourceMappingURL=index.js.map

package/lib/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/lib/app/lifecycle-manager.d.ts

@@ -0,0 +1,26 @@
+import type { OnStartHook, OnShutdownHook } from '@kurdel/core/app';
+/**
+ * Executes lifecycle hooks in sequence with error handling and optional logging.
+ *
+ * Used by the runtime to manage application startup and shutdown phases.
+ *
+ * Design goals:
+ * - Run hooks sequentially (not in parallel) to preserve dependency order.
+ * - Stop execution immediately on first error (fail fast).
+ * - Log hook errors if a logger is provided, but never swallow them silently.
+ */
+export declare class LifecycleManager {
+    private readonly logger?;
+    constructor(logger?: {
+        error?: (...args: any[]) => void;
+    } | undefined);
+    /**
+     * Run all registered lifecycle hooks of a given kind.
+     *
+     * @param kind - Indicates whether start or shutdown hooks are being executed.
+     * @param hooks - Ordered list of async or sync hooks to run.
+     *
+     * If any hook throws, execution stops and the error is rethrown after logging.
+     */
+    runHooks(kind: 'start' | 'shutdown', hooks: Array<OnStartHook | OnShutdownHook>): Promise<void>;
+}

package/lib/app/lifecycle-manager.js

@@ -0,0 +1,40 @@
+/**
+ * Executes lifecycle hooks in sequence with error handling and optional logging.
+ *
+ * Used by the runtime to manage application startup and shutdown phases.
+ *
+ * Design goals:
+ * - Run hooks sequentially (not in parallel) to preserve dependency order.
+ * - Stop execution immediately on first error (fail fast).
+ * - Log hook errors if a logger is provided, but never swallow them silently.
+ */
+export class LifecycleManager {
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Run all registered lifecycle hooks of a given kind.
+     *
+     * @param kind - Indicates whether start or shutdown hooks are being executed.
+     * @param hooks - Ordered list of async or sync hooks to run.
+     *
+     * If any hook throws, execution stops and the error is rethrown after logging.
+     */
+    async runHooks(kind, hooks) {
+        for (const hook of hooks) {
+            try {
+                await hook();
+            }
+            catch (err) {
+                try {
+                    this.logger?.error?.(`[lifecycle:${kind}]`, err);
+                }
+                catch {
+                    /* ignore logging errors */
+                }
+                throw err;
+            }
+        }
+    }
+}
+//# sourceMappingURL=lifecycle-manager.js.map

package/lib/app/lifecycle-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-manager.js","sourceRoot":"","sources":["../../src/app/lifecycle-manager.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAgB;IAC3B,YAA6B,MAA6C;QAA7C,WAAM,GAAN,MAAM,CAAuC;IAAG,CAAC;IAE9E;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CACZ,IAA0B,EAC1B,KAA0C;QAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,EAAE,CAAC;YACf,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,cAAc,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;gBACnD,CAAC;gBAAC,MAAM,CAAC;oBACP,2BAA2B;gBAC7B,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/lib/app/module-loader.d.ts

@@ -0,0 +1,29 @@
+import type { AppModule, AppConfig } from '@kurdel/core/app';
+import type { Container } from '@kurdel/ioc';
+/**
+ * Loads and initializes all application modules.
+ *
+ * Responsibilities:
+ * - Validate declared `imports` (fail fast if required tokens are missing)
+ * - Register `providers` into the IoC container using ProviderRegistrar
+ * - Execute each module’s optional `register(ioc, config)` hook
+ * - Verify that declared `exports` are actually bound in the container
+ *
+ * Design notes:
+ * - Modules are processed sequentially to ensure deterministic initialization order.
+ * - Each module operates within the same root container (no nested scopes here).
+ * - The loader itself performs no lifecycle logic — only structural assembly.
+ */
+export declare class ModuleLoader {
+    private readonly ioc;
+    constructor(ioc: Container);
+    /**
+     * Initialize the given list of modules in order.
+     *
+     * @param modules - Ordered list of application modules to load.
+     * @param config - Immutable application configuration.
+     *
+     * Throws if a module import or export token is missing in the container.
+     */
+    init(modules: AppModule[], config: AppConfig): Promise<void>;
+}

package/lib/app/module-loader.js

@@ -0,0 +1,61 @@
+import { ProviderRegistrar } from '../app/provider-registrar.js';
+import { ModuleValidationError } from '../app/errors/module-validation-error.js';
+/**
+ * Loads and initializes all application modules.
+ *
+ * Responsibilities:
+ * - Validate declared `imports` (fail fast if required tokens are missing)
+ * - Register `providers` into the IoC container using ProviderRegistrar
+ * - Execute each module’s optional `register(ioc, config)` hook
+ * - Verify that declared `exports` are actually bound in the container
+ *
+ * Design notes:
+ * - Modules are processed sequentially to ensure deterministic initialization order.
+ * - Each module operates within the same root container (no nested scopes here).
+ * - The loader itself performs no lifecycle logic — only structural assembly.
+ */
+export class ModuleLoader {
+    constructor(ioc) {
+        this.ioc = ioc;
+    }
+    /**
+     * Initialize the given list of modules in order.
+     *
+     * @param modules - Ordered list of application modules to load.
+     * @param config - Immutable application configuration.
+     *
+     * Throws if a module import or export token is missing in the container.
+     */
+    async init(modules, config) {
+        const registrar = new ProviderRegistrar(this.ioc);
+        for (const mod of modules) {
+            // --- 1️⃣ Validate declared imports ---
+            if (mod.imports) {
+                for (const dep of Object.values(mod.imports)) {
+                    if (!this.ioc.has(dep)) {
+                        throw new ModuleValidationError(`Module ${mod.constructor.name} missing dependency: ${String(dep)}`);
+                    }
+                }
+            }
+            // --- 2️⃣ Register providers ---
+            if (mod.providers) {
+                for (const provider of mod.providers) {
+                    registrar.register(provider);
+                }
+            }
+            // --- 3️⃣ Execute custom register() hook ---
+            if (typeof mod.register === 'function') {
+                await mod.register(this.ioc, config);
+            }
+            // --- 4️⃣ Validate declared exports ---
+            if (mod.exports) {
+                for (const token of Object.values(mod.exports)) {
+                    if (!this.ioc.has(token)) {
+                        throw new ModuleValidationError(`Module did not register expected export: ${String(token)}`);
+                    }
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=module-loader.js.map

package/lib/app/module-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.js","sourceRoot":"","sources":["../../src/app/module-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAElF;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACvB,YAA6B,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB,EAAE,MAAiB;QAChD,MAAM,SAAS,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,wCAAwC;YACxC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC7C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;wBACvB,MAAM,IAAI,qBAAqB,CAC7B,UAAU,GAAG,CAAC,WAAW,CAAC,IAAI,wBAAwB,MAAM,CAAC,GAAG,CAAC,EAAE,CACpE,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;YAED,iCAAiC;YACjC,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAClB,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;oBACrC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YAED,6CAA6C;YAC7C,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACvC,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACvC,CAAC;YAED,wCAAwC;YACxC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC/C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;wBACzB,MAAM,IAAI,qBAAqB,CAC7B,4CAA4C,MAAM,CAAC,KAAK,CAAC,EAAE,CAC5D,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/lib/app/provider-registrar.d.ts

@@ -0,0 +1,29 @@
+import type { ProviderConfig } from '@kurdel/core/app';
+import type { Container } from '@kurdel/ioc';
+/**
+ * Registers dependency providers in the IoC container according to DI semantics.
+ *
+ * Supported provider forms:
+ * - `useClass` — binds a class (constructor) with optional dependencies and lifecycle hint.
+ * - `useInstance` — binds an existing instance (always singleton).
+ * - `useFactory` — binds a factory function (sync or async), optionally cached as singleton.
+ *
+ * Async factories are handled gracefully:
+ * - If the factory returns a Promise and `singleton` is true, the resolved instance is bound.
+ * - Otherwise, async non-singleton factories are disallowed (runtime error).
+ *
+ * Design notes:
+ * - This class is a low-level helper used by `ModuleLoader`.
+ * - It performs no validation beyond binding logic — imports/exports are checked elsewhere.
+ */
+export declare class ProviderRegistrar {
+    private readonly ioc;
+    constructor(ioc: Container);
+    /**
+     * Register a single provider within the container.
+     *
+     * @param provider - Declarative provider configuration.
+     * @throws {Error} If async factory is declared without `singleton: true`.
+     */
+    register<T>(provider: ProviderConfig<T>): void;
+}

package/lib/app/provider-registrar.js

@@ -0,0 +1,67 @@
+import { ProviderConfigurationError } from '../app/errors/provider-configuration-error.js';
+/**
+ * Registers dependency providers in the IoC container according to DI semantics.
+ *
+ * Supported provider forms:
+ * - `useClass` — binds a class (constructor) with optional dependencies and lifecycle hint.
+ * - `useInstance` — binds an existing instance (always singleton).
+ * - `useFactory` — binds a factory function (sync or async), optionally cached as singleton.
+ *
+ * Async factories are handled gracefully:
+ * - If the factory returns a Promise and `singleton` is true, the resolved instance is bound.
+ * - Otherwise, async non-singleton factories are disallowed (runtime error).
+ *
+ * Design notes:
+ * - This class is a low-level helper used by `ModuleLoader`.
+ * - It performs no validation beyond binding logic — imports/exports are checked elsewhere.
+ */
+export class ProviderRegistrar {
+    constructor(ioc) {
+        this.ioc = ioc;
+    }
+    /**
+     * Register a single provider within the container.
+     *
+     * @param provider - Declarative provider configuration.
+     * @throws {Error} If async factory is declared without `singleton: true`.
+     */
+    register(provider) {
+        // --- 1️⃣ useClass: bind class constructor ---
+        if ('useClass' in provider) {
+            const binding = this.ioc.bind(provider.provide).to(provider.useClass);
+            if (provider.deps)
+                binding.with(provider.deps);
+            if (provider.singleton)
+                binding.inSingletonScope();
+            return;
+        }
+        // --- 2️⃣ useInstance: bind pre-constructed instance ---
+        if ('useInstance' in provider) {
+            this.ioc.bind(provider.provide).toInstance(provider.useInstance);
+            return;
+        }
+        // --- 3️⃣ useFactory: bind factory (sync or async) ---
+        if ('useFactory' in provider) {
+            const result = provider.useFactory(this.ioc);
+            // Async factory case
+            if (result instanceof Promise) {
+                if (!provider.singleton) {
+                    throw new ProviderConfigurationError(`Async factory for "${String(provider.provide)}" must be declared as singleton.`);
+                }
+                // When the promise resolves, bind the instance
+                result.then(instance => {
+                    this.ioc.bind(provider.provide).toInstance(instance);
+                });
+                return;
+            }
+            // Sync factory case
+            if (provider.singleton) {
+                this.ioc.bind(provider.provide).toInstance(result);
+            }
+            else {
+                this.ioc.toFactory(provider.provide, () => provider.useFactory(this.ioc));
+            }
+        }
+    }
+}
+//# sourceMappingURL=provider-registrar.js.map

package/lib/app/provider-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registrar.js","sourceRoot":"","sources":["../../src/app/provider-registrar.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,MAAM,gDAAgD,CAAC;AAE5F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,iBAAiB;IAC5B,YAA6B,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,CAAI,QAA2B;QACrC,+CAA+C;QAC/C,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAEzE,IAAI,QAAQ,CAAC,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/C,IAAI,QAAQ,CAAC,SAAS;gBAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAEnD,OAAO;QACT,CAAC;QAED,yDAAyD;QACzD,IAAI,aAAa,IAAI,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YACpE,OAAO;QACT,CAAC;QAED,uDAAuD;QACvD,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAE7C,qBAAqB;YACrB,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC9B,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;oBACxB,MAAM,IAAI,0BAA0B,CAClC,sBAAsB,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,kCAAkC,CACjF,CAAC;gBACJ,CAAC;gBAED,+CAA+C;gBAC/C,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;oBACrB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC1D,CAAC,CAAC,CAAC;gBAEH,OAAO;YACT,CAAC;YAED,oBAAoB;YACpB,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACvB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YACxD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAM,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,75 @@
+import type { Container } from '@kurdel/ioc';
+import type { AppConfig, Application, AppModule } from '@kurdel/core/app';
+import type { RunningServer } from '@kurdel/core/http';
+/**
+ * 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 declare class RuntimeApplication implements Application {
+    /** Immutable app configuration passed from the facade. */
+    private readonly config;
+    /** Root IoC container — central registry for all runtime providers. */
+    private readonly ioc;
+    /** Ordered list of modules to initialize (built-in + user-defined). */
+    private readonly modules;
+    /** Handles lifecycle hook execution (OnStart / OnShutdown). */
+    private readonly lifecycle;
+    /** Read-only accessor exposing the underlying IoC container. */
+    get container(): Container;
+    /**
+     * Construct a new runtime application.
+     *
+     * Steps performed:
+     *  - Store runtime configuration
+     *  - Compose the module pipeline (built-ins + user modules) via RuntimeComposer
+     */
+    constructor(config: AppConfig);
+    /**
+     * Add extra modules programmatically before bootstrap.
+     * Useful for integration tests or dynamic composition in code.
+     */
+    use(...modules: AppModule[]): void;
+    /**
+     * 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()`.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * 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: number, hostOrCb?: string | (() => void), cb?: () => void): RunningServer;
+    /**
+     * 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(): Container;
+}