@zudojs/core 0.0.1 → 1.0.0

package/dist/modules/moduleDependency/moduleDependency.ordering.js

@@ -1,44 +1,50 @@
-import { validateModuleDependencyGraph } from "./moduleDependency.graph.js";
+import { CircularModuleDependencyError, MissingModuleDependencyError, } from "../moduleError/moduleError.dependency.js";
 /**
  * Detects circular dependencies in a module graph.
  *
  * Returns the dependency cycle when one exists.
+ *
+ * This is the single cycle-detection mechanism used by the
+ * dependency subsystem. The implementation is iterative so very
+ * deep graphs cannot overflow the call stack.
  */
 export function findModuleDependencyCycle(graph) {
-    const visiting = new Set();
     const visited = new Set();
-    const path = [];
-    const visit = (moduleId) => {
-        if (visiting.has(moduleId)) {
-            const index = path.indexOf(moduleId);
-            if (index >= 0) {
-                return [...path.slice(index), moduleId];
-            }
-            return [moduleId];
-        }
-        if (visited.has(moduleId)) {
-            return undefined;
-        }
-        visiting.add(moduleId);
-        path.push(moduleId);
-        for (const dependency of graph.getDependencies(moduleId)) {
-            if (!graph.hasModule(dependency.id)) {
+    for (const startId of graph.nodes.keys()) {
+        if (visited.has(startId))
+            continue;
+        /*
+         * Iterative DFS. Each stack frame tracks the module and the
+         * index of the next dependency to visit.
+         */
+        const stack = [
+            { id: startId, nextDependency: 0 },
+        ];
+        const inPath = new Set([startId]);
+        const path = [startId];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const dependencies = graph.getDependencies(frame.id);
+            if (frame.nextDependency >= dependencies.length) {
+                stack.pop();
+                path.pop();
+                inPath.delete(frame.id);
+                visited.add(frame.id);
                 continue;
             }
-            const cycle = visit(dependency.id);
-            if (cycle) {
-                return cycle;
+            const dependency = dependencies[frame.nextDependency];
+            frame.nextDependency += 1;
+            if (!graph.hasModule(dependency.id))
+                continue;
+            if (inPath.has(dependency.id)) {
+                const index = path.indexOf(dependency.id);
+                return [...path.slice(index), dependency.id];
             }
-        }
-        path.pop();
-        visiting.delete(moduleId);
-        visited.add(moduleId);
-        return undefined;
-    };
-    for (const moduleId of graph.nodes.keys()) {
-        const cycle = visit(moduleId);
-        if (cycle) {
-            return cycle;
+            if (visited.has(dependency.id))
+                continue;
+            stack.push({ id: dependency.id, nextDependency: 0 });
+            inPath.add(dependency.id);
+            path.push(dependency.id);
         }
     }
     return undefined;
@@ -65,38 +71,60 @@ export function hasModuleDependencyCycle(graph) {
  * produces:
  *
  * users → orders → payments
+ *
+ * The sort is implemented iteratively (Kahn's algorithm). When
+ * not every module can be ordered, the cycle is located with
+ * findModuleDependencyCycle and reported.
  */
 export function resolveModuleStartupOrder(graph) {
-    const missing = validateModuleDependencyGraph(graph);
-    if (missing.length > 0) {
-        throw new Error(`Cannot resolve module startup order. Missing required dependencies: ${missing.join(", ")}`);
+    /*
+     * Missing required dependencies make the order meaningless,
+     * so they are reported first with the requiring module.
+     */
+    for (const node of graph.nodes.values()) {
+        for (const dependency of node.dependencies) {
+            if (dependency.optional)
+                continue;
+            if (!graph.hasModule(dependency.id)) {
+                throw new MissingModuleDependencyError(node.id, dependency.id);
+            }
+        }
+    }
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const node of graph.nodes.values()) {
+        let degree = 0;
+        for (const dependency of node.dependencies) {
+            if (!graph.hasModule(dependency.id))
+                continue;
+            degree += 1;
+            const list = dependents.get(dependency.id);
+            if (list)
+                list.push(node.id);
+            else
+                dependents.set(dependency.id, [node.id]);
+        }
+        inDegree.set(node.id, degree);
     }
-    const cycle = findModuleDependencyCycle(graph);
-    if (cycle) {
-        throw new Error(`Circular module dependency detected: ${cycle.join(" -> ")}`);
+    const queue = [];
+    for (const [moduleId, degree] of inDegree) {
+        if (degree === 0)
+            queue.push(moduleId);
     }
-    const temporary = new Set();
-    const permanent = new Set();
     const order = [];
-    const visit = (moduleId) => {
-        if (permanent.has(moduleId)) {
-            return;
-        }
-        if (temporary.has(moduleId)) {
-            throw new Error(`Circular module dependency detected involving "${moduleId}".`);
-        }
-        temporary.add(moduleId);
-        for (const dependency of graph.getDependencies(moduleId)) {
-            if (graph.hasModule(dependency.id)) {
-                visit(dependency.id);
-            }
-        }
-        temporary.delete(moduleId);
-        permanent.add(moduleId);
+    for (let index = 0; index < queue.length; index++) {
+        const moduleId = queue[index];
         order.push(moduleId);
-    };
-    for (const moduleId of graph.nodes.keys()) {
-        visit(moduleId);
+        for (const dependent of dependents.get(moduleId) ?? []) {
+            const degree = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, degree);
+            if (degree === 0)
+                queue.push(dependent);
+        }
+    }
+    if (order.length !== graph.nodes.size) {
+        const cycle = findModuleDependencyCycle(graph);
+        throw new CircularModuleDependencyError(cycle ?? [...graph.nodes.keys()].filter((id) => !order.includes(id)));
     }
     return Object.freeze(order);
 }

package/dist/modules/moduleDependency/moduleDependency.type.d.ts

@@ -37,6 +37,13 @@ export interface ModuleDependencyNode {
      * Dependencies declared by the module.
      */
     readonly dependencies: ModuleDependencies;
+    /**
+     * Semantic version of the module, when known.
+     *
+     * Used to check dependency version constraints while
+     * building the graph.
+     */
+    readonly version?: string;
 }
 /**
  * Complete module dependency graph.
@@ -62,5 +69,25 @@ export interface ModuleDependencyGraph {
 /**
  * A raw dependency declaration accepted by the framework.
  */
-export type ModuleDependencyInput = ModuleId | ModuleDependency;
+export type ModuleDependencyInput = ModuleId | (Pick<ModuleDependency, "id"> & Partial<Omit<ModuleDependency, "id">>);
+/**
+ * A raw dependency graph node accepted by `createModuleDependencyGraph`.
+ *
+ * Dependencies may be declared as plain ids or partial dependency objects;
+ * they are normalized while the graph is built.
+ */
+export interface ModuleDependencyNodeInput {
+    /**
+     * Module identifier.
+     */
+    readonly id: ModuleId;
+    /**
+     * Dependencies declared by the module.
+     */
+    readonly dependencies?: readonly ModuleDependencyInput[];
+    /**
+     * Semantic version of the module, when known.
+     */
+    readonly version?: string;
+}
 //# sourceMappingURL=moduleDependency.type.d.ts.map

package/dist/modules/moduleError/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { ModuleErrorCode, type ModuleErrorCode as ModuleErrorCodeType, type ModuleErrorDetails, ModuleError, } from "./moduleError.base.js";
 export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError, } from "./moduleError.registration.js";
-export { MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
+export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleError/index.js

@@ -5,7 +5,7 @@
  */
 export { ModuleErrorCode, ModuleError, } from "./moduleError.base.js";
 export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError, } from "./moduleError.registration.js";
-export { MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
+export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
 //# sourceMappingURL=index.js.map

package/dist/modules/moduleError/moduleError.dependency.d.ts

@@ -12,6 +12,17 @@ export declare class MissingModuleDependencyError extends ModuleError {
 export declare class CircularModuleDependencyError extends ModuleError {
     constructor(cycle: readonly ModuleId[]);
 }
+/**
+ * Error thrown when a dependency declaration is malformed:
+ * empty ids, self-dependencies, duplicate declarations, or
+ * unsupported version constraints.
+ */
+export declare class InvalidModuleDependencyError extends ModuleError {
+    constructor(message: string, options?: {
+        readonly moduleId?: ModuleId;
+        readonly dependencyId?: ModuleId;
+    });
+}
 /**
  * Error thrown when a module dependency version
  * cannot be satisfied.

package/dist/modules/moduleError/moduleError.dependency.js

@@ -26,6 +26,21 @@ export class CircularModuleDependencyError extends ModuleError {
         this.name = "CircularModuleDependencyError";
     }
 }
+/**
+ * Error thrown when a dependency declaration is malformed:
+ * empty ids, self-dependencies, duplicate declarations, or
+ * unsupported version constraints.
+ */
+export class InvalidModuleDependencyError extends ModuleError {
+    constructor(message, options = {}) {
+        super(message, {
+            code: ModuleErrorCode.INVALID_DEPENDENCY,
+            moduleId: options.moduleId,
+            dependencyId: options.dependencyId,
+        });
+        this.name = "InvalidModuleDependencyError";
+    }
+}
 /**
  * Error thrown when a module dependency version
  * cannot be satisfied.

package/dist/modules/moduleLifecycle/index.d.ts

@@ -3,8 +3,11 @@
  *
  * Manages the lifecycle phases of loaded modules:
  * initialize → start → stop → destroy.
+ *
+ * The state-machine plumbing (hook invocation, phase execution,
+ * state maps) is internal to this subsystem and intentionally
+ * not exported from this barrel.
  */
-export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHooks, type ModuleLifecycleOptions, ModuleLifecycleError, type ModuleLifecycleResult, type LifecycleStateMap, } from "./moduleLifecycle.type.js";
-export { ensureStateSynchronized, getLifecycleState, requireLifecycleState, getAllLifecycleStates, isModuleInitialized, isModuleStarted, isModuleDestroyed, invokeLifecycleHook, canModuleEnterPhase, setLifecycleState, executeLifecyclePhase, } from "./moduleLifecycle.stateMachine.js";
+export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHookName, type ModuleLifecycleStep, type ModuleLifecycleHooks, type ModuleLifecycleOptions, ModuleLifecycleError, type ModuleLifecycleResult, type ModuleLifecycleSkip, } from "./moduleLifecycle.type.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleLifecycle/index.js

@@ -3,8 +3,11 @@
  *
  * Manages the lifecycle phases of loaded modules:
  * initialize → start → stop → destroy.
+ *
+ * The state-machine plumbing (hook invocation, phase execution,
+ * state maps) is internal to this subsystem and intentionally
+ * not exported from this barrel.
  */
 export { ModuleLifecycleError, } from "./moduleLifecycle.type.js";
-export { ensureStateSynchronized, getLifecycleState, requireLifecycleState, getAllLifecycleStates, isModuleInitialized, isModuleStarted, isModuleDestroyed, invokeLifecycleHook, canModuleEnterPhase, setLifecycleState, executeLifecyclePhase, } from "./moduleLifecycle.stateMachine.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
 //# sourceMappingURL=index.js.map

package/dist/modules/moduleLifecycle/moduleLifecycle.lifecycle.d.ts

@@ -1,7 +1,8 @@
-import type { ModuleId } from "../module.js";
-import type { ModuleRegistry } from "../moduleRegistry/index.js";
+import type { Module, ModuleId } from "../module.js";
+import type { ModuleDefinition } from "../moduleDefinition.definition.js";
+import type { ModuleRegistration, ModuleRegistry } from "../moduleRegistry/index.js";
 import type { ModuleLoader } from "../moduleLoader/index.js";
-import type { ModuleLifecycleOptions, ModuleLifecycleResult } from "./moduleLifecycle.type.js";
+import type { ModuleLifecycleOptions, ModuleLifecycleResult, ModuleLifecycleState } from "./moduleLifecycle.type.js";
 /**
  * Module lifecycle manager.
  * Initializes, starts, stops, and destroys modules in dependency order.
@@ -10,6 +11,7 @@ export declare class ModuleLifecycleManager {
     private readonly registry;
     private readonly loader;
     private readonly options;
+    private readonly contextStorage;
     private readonly states;
     private operation;
     constructor(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions);
@@ -17,6 +19,42 @@ export declare class ModuleLifecycleManager {
     start(): Promise<ModuleLifecycleResult>;
     stop(): Promise<ModuleLifecycleResult>;
     destroy(): Promise<ModuleLifecycleResult>;
+    /**
+     * Rolls back modules that completed earlier phases after a
+     * startup failure.
+     *
+     * The rollback is best-effort: the already-completed subset is
+     * stopped (when requested) and destroyed in reverse dependency
+     * order, and any rollback errors are collected onto the
+     * original ModuleLifecycleError instead of masking it.
+     */
+    private rollbackAfterFailure;
+    /**
+     * Shuts down and unloads a single module.
+     *
+     * The module is stopped (when started) and destroyed, its
+     * lifecycle state is dropped, and the loader forgets its
+     * instance and context. Hook failures never abort the unload;
+     * they are reported in the result and on the lifecycle state.
+     *
+     * A module that other loaded modules still depend on cannot be
+     * unloaded; ModuleError (MODULE_OPERATION_NOT_ALLOWED) is thrown.
+     */
+    unloadModule(moduleId: ModuleId): Promise<ModuleLifecycleResult>;
+    /**
+     * Replaces a module definition, shutting down the currently
+     * loaded instance first.
+     *
+     * The registry must allow replacement (allowReplacement: true).
+     * The new definition is registered but not loaded; call the
+     * loader and lifecycle methods afterwards to bring it up.
+     */
+    replaceModule<TModule extends Module>(definition: ModuleDefinition<TModule>): Promise<ModuleRegistration<TModule>>;
+    /**
+     * Returns ids of loaded modules that declare a required or
+     * optional dependency on the given module.
+     */
+    private getLoadedDependents;
     startApplication(): Promise<{
         readonly initialized: ModuleLifecycleResult;
         readonly started: ModuleLifecycleResult;
@@ -25,9 +63,9 @@ export declare class ModuleLifecycleManager {
         readonly stopped: ModuleLifecycleResult;
         readonly destroyed: ModuleLifecycleResult;
     }>;
-    getState(moduleId: ModuleId): import("./moduleLifecycle.type.js").ModuleLifecycleState | undefined;
-    requireState(moduleId: ModuleId): import("./moduleLifecycle.type.js").ModuleLifecycleState;
-    getStates(): ReadonlyMap<ModuleId, import("./moduleLifecycle.type.js").ModuleLifecycleState>;
+    getState(moduleId: ModuleId): ModuleLifecycleState | undefined;
+    requireState(moduleId: ModuleId): ModuleLifecycleState;
+    getStates(): ReadonlyMap<ModuleId, ModuleLifecycleState>;
     isInitialized(moduleId: ModuleId): boolean;
     isStarted(moduleId: ModuleId): boolean;
     isDestroyed(moduleId: ModuleId): boolean;

package/dist/modules/moduleLifecycle/moduleLifecycle.lifecycle.js

@@ -1,4 +1,7 @@
+import { ModuleError, ModuleErrorCode, } from "../moduleError/moduleError.base.js";
 import { createModuleDependencyGraph, resolveModuleStartupOrder, resolveModuleShutdownOrder, } from "../moduleDependency/index.js";
+import { ModuleLifecycleError } from "./moduleLifecycle.type.js";
+import { getDefaultContextStorage } from "../../context/provider/defaultContextStorage.storage.js";
 import { ensureStateSynchronized, getLifecycleState, requireLifecycleState, getAllLifecycleStates, isModuleInitialized, isModuleStarted, isModuleDestroyed, executeLifecyclePhase, } from "./moduleLifecycle.stateMachine.js";
 /**
  * Module lifecycle manager.
@@ -8,6 +11,7 @@ export class ModuleLifecycleManager {
     registry;
     loader;
     options;
+    contextStorage;
     states = new Map();
     operation;
     constructor(registry, loader, options = {}) {
@@ -19,39 +23,178 @@ export class ModuleLifecycleManager {
             continueOnStopError: options.continueOnStopError ?? true,
             continueOnDestroyError: options.continueOnDestroyError ?? true,
         };
+        this.contextStorage = options.contextStorage ?? getDefaultContextStorage();
     }
     async initialize() {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getStartupOrder(), "initialize", "initializing", "initialized", this.options.continueOnInitializeError, this.registry, this.loader, this.states);
+            try {
+                return await executeLifecyclePhase(this.getStartupOrder(), "initialize", "initializing", "initialized", this.options.continueOnInitializeError, this.registry, this.loader, this.states, this.contextStorage);
+            }
+            catch (error) {
+                await this.rollbackAfterFailure(error, { stopFirst: false });
+                throw error;
+            }
         });
     }
     async start() {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getStartupOrder(), "start", "starting", "started", this.options.continueOnStartError, this.registry, this.loader, this.states);
+            try {
+                return await executeLifecyclePhase(this.getStartupOrder(), "start", "starting", "started", this.options.continueOnStartError, this.registry, this.loader, this.states, this.contextStorage);
+            }
+            catch (error) {
+                await this.rollbackAfterFailure(error, { stopFirst: true });
+                throw error;
+            }
         });
     }
     async stop() {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getShutdownOrder(), "stop", "stopping", "stopped", this.options.continueOnStopError, this.registry, this.loader, this.states);
+            return executeLifecyclePhase(this.getShutdownOrder(), "stop", "stopping", "stopped", this.options.continueOnStopError, this.registry, this.loader, this.states, this.contextStorage);
         });
     }
     async destroy() {
         return this.runExclusive(async () => {
             ensureStateSynchronized(this.registry, this.states);
-            return executeLifecyclePhase(this.getShutdownOrder(), "destroy", "destroying", "destroyed", this.options.continueOnDestroyError, this.registry, this.loader, this.states);
+            return executeLifecyclePhase(this.getShutdownOrder(), "destroy", "destroying", "destroyed", this.options.continueOnDestroyError, this.registry, this.loader, this.states, this.contextStorage);
         });
     }
+    /**
+     * Rolls back modules that completed earlier phases after a
+     * startup failure.
+     *
+     * The rollback is best-effort: the already-completed subset is
+     * stopped (when requested) and destroyed in reverse dependency
+     * order, and any rollback errors are collected onto the
+     * original ModuleLifecycleError instead of masking it.
+     */
+    async rollbackAfterFailure(error, options) {
+        const rollbackErrors = [];
+        try {
+            /*
+             * Only modules that actually entered the startup flow are
+             * rolled back; untouched modules keep their "created"
+             * state and never see stop/destroy hooks here.
+             */
+            const touchedPhases = new Set([
+                "initialized",
+                "starting",
+                "started",
+                "stopping",
+                "stopped",
+                "failed",
+            ]);
+            const shutdownOrder = this.getShutdownOrder().filter((moduleId) => {
+                const phase = getLifecycleState(moduleId, this.states)?.phase;
+                return phase !== undefined && touchedPhases.has(phase);
+            });
+            if (options.stopFirst) {
+                const stopResult = await executeLifecyclePhase(shutdownOrder, "stop", "stopping", "stopped", true, this.registry, this.loader, this.states, this.contextStorage);
+                for (const moduleId of stopResult.failed) {
+                    rollbackErrors.push(getLifecycleState(moduleId, this.states)?.error ??
+                        new Error(`Module "${moduleId}" failed to stop during rollback.`));
+                }
+            }
+            const destroyResult = await executeLifecyclePhase(shutdownOrder, "destroy", "destroying", "destroyed", true, this.registry, this.loader, this.states, this.contextStorage);
+            for (const moduleId of destroyResult.failed) {
+                rollbackErrors.push(getLifecycleState(moduleId, this.states)?.error ??
+                    new Error(`Module "${moduleId}" failed to destroy during rollback.`));
+            }
+        }
+        catch (rollbackError) {
+            rollbackErrors.push(rollbackError);
+        }
+        if (error instanceof ModuleLifecycleError && rollbackErrors.length > 0) {
+            error.rollbackErrors = Object.freeze([...rollbackErrors]);
+        }
+    }
+    /**
+     * Shuts down and unloads a single module.
+     *
+     * The module is stopped (when started) and destroyed, its
+     * lifecycle state is dropped, and the loader forgets its
+     * instance and context. Hook failures never abort the unload;
+     * they are reported in the result and on the lifecycle state.
+     *
+     * A module that other loaded modules still depend on cannot be
+     * unloaded; ModuleError (MODULE_OPERATION_NOT_ALLOWED) is thrown.
+     */
+    async unloadModule(moduleId) {
+        return this.runExclusive(async () => {
+            ensureStateSynchronized(this.registry, this.states);
+            const registration = this.registry.get(moduleId);
+            if (!registration?.instance) {
+                this.loader.unload(moduleId);
+                this.states.delete(moduleId);
+                return { completed: [], failed: [], skipped: [] };
+            }
+            const dependents = this.getLoadedDependents(moduleId);
+            if (dependents.length > 0) {
+                throw new ModuleError(`Module "${moduleId}" cannot be unloaded while loaded modules depend on it: ${dependents.join(", ")}.`, {
+                    code: ModuleErrorCode.OPERATION_NOT_ALLOWED,
+                    moduleId,
+                    metadata: { dependents },
+                });
+            }
+            const stopped = await executeLifecyclePhase([moduleId], "stop", "stopping", "stopped", true, this.registry, this.loader, this.states, this.contextStorage);
+            const destroyed = await executeLifecyclePhase([moduleId], "destroy", "destroying", "destroyed", true, this.registry, this.loader, this.states, this.contextStorage);
+            this.loader.unload(moduleId);
+            this.states.delete(moduleId);
+            return {
+                completed: Object.freeze([
+                    ...new Set([...stopped.completed, ...destroyed.completed]),
+                ]),
+                failed: Object.freeze([
+                    ...new Set([...stopped.failed, ...destroyed.failed]),
+                ]),
+                skipped: Object.freeze([...stopped.skipped, ...destroyed.skipped]),
+            };
+        });
+    }
+    /**
+     * Replaces a module definition, shutting down the currently
+     * loaded instance first.
+     *
+     * The registry must allow replacement (allowReplacement: true).
+     * The new definition is registered but not loaded; call the
+     * loader and lifecycle methods afterwards to bring it up.
+     */
+    async replaceModule(definition) {
+        const existing = this.registry.get(definition.id);
+        if (existing?.instance)
+            await this.unloadModule(definition.id);
+        return this.registry.register(definition);
+    }
+    /**
+     * Returns ids of loaded modules that declare a required or
+     * optional dependency on the given module.
+     */
+    getLoadedDependents(moduleId) {
+        const dependents = [];
+        for (const registration of this.registry.getAll()) {
+            if (registration.definition.id === moduleId)
+                continue;
+            if (registration.state !== "loaded")
+                continue;
+            const dependsOnModule = this.registry
+                .getDependencies(registration.definition.id)
+                .some((dependency) => dependency.id === moduleId);
+            if (dependsOnModule)
+                dependents.push(registration.definition.id);
+        }
+        return dependents;
+    }
     async startApplication() {
+        /*
+         * When continueOn*Error is disabled, phase failures are
+         * reported through the thrown (and rolled-back)
+         * ModuleLifecycleError from initialize()/start(). That is
+         * the single failure path of application startup.
+         */
         const initialized = await this.initialize();
-        if (initialized.failed.length > 0 &&
-            !this.options.continueOnInitializeError)
-            throw new Error("Application startup aborted because module initialization failed.");
         const started = await this.start();
-        if (started.failed.length > 0 && !this.options.continueOnStartError)
-            throw new Error("Application startup aborted because module startup failed.");
         return { initialized, started };
     }
     async stopApplication() {
@@ -81,6 +224,7 @@ export class ModuleLifecycleManager {
         const nodes = this.registry.getAll().map((r) => ({
             id: r.definition.id,
             dependencies: this.registry.getDependencies(r.definition.id),
+            version: r.definition.version,
         }));
         return createModuleDependencyGraph(nodes);
     }

package/dist/modules/moduleLifecycle/moduleLifecycle.stateMachine.d.ts

@@ -1,9 +1,15 @@
 import type { Module, ModuleId } from "../module.js";
 import type { ModuleContext } from "../moduleContext.context.js";
-import type { ModuleLifecycleHooks, ModuleLifecyclePhase, ModuleLifecycleState, LifecycleStateMap } from "./moduleLifecycle.type.js";
+import type { ModuleLifecycleStep, ModuleLifecyclePhase, ModuleLifecycleState, ModuleLifecycleSkip, LifecycleStateMap } from "./moduleLifecycle.type.js";
 import type { ModuleRegistry } from "../moduleRegistry/index.js";
 import type { ModuleLoader } from "../moduleLoader/index.js";
-/** Ensures lifecycle state is synchronized with the registry. */
+import type { ContextStorage } from "../../context/provider/contextStorage.storage.js";
+/**
+ * Ensures lifecycle state is synchronized with the registry.
+ *
+ * Registered modules gain a "created" state; states belonging to
+ * modules that are no longer registered are pruned.
+ */
 export declare function ensureStateSynchronized(registry: ModuleRegistry, states: LifecycleStateMap): void;
 export declare function getLifecycleState(moduleId: ModuleId, states: LifecycleStateMap): ModuleLifecycleState | undefined;
 export declare function requireLifecycleState(moduleId: ModuleId, states: LifecycleStateMap): ModuleLifecycleState;
@@ -11,11 +17,30 @@ export declare function getAllLifecycleStates(states: LifecycleStateMap): Readon
 export declare function isModuleInitialized(moduleId: ModuleId, states: LifecycleStateMap): boolean;
 export declare function isModuleStarted(moduleId: ModuleId, states: LifecycleStateMap): boolean;
 export declare function isModuleDestroyed(moduleId: ModuleId, states: LifecycleStateMap): boolean;
-export declare function invokeLifecycleHook(module: Module, hook: keyof ModuleLifecycleHooks, context: ModuleContext): Promise<void>;
-export declare function canModuleEnterPhase(moduleId: ModuleId, hook: keyof ModuleLifecycleHooks, states: LifecycleStateMap): boolean;
+/**
+ * Invokes the lifecycle hook for a step on a module.
+ *
+ * Only the canonical Module contract hooks are invoked:
+ *
+ * initialize → onInitialize
+ * start      → onReady
+ * stop       → onShutdown
+ * destroy    → onDestroy
+ *
+ * Modules that do not implement a hook are skipped for that step.
+ *
+ * When `contextStorage` holds an active execution context (the
+ * runtime's, during bootstrap and shutdown), the hook runs inside a
+ * context derived from it: `module` is the module id, `operation`
+ * is the hook name, and `{ moduleId, phase }` is merged into the
+ * metadata. Everything the hook awaits observes that context.
+ */
+export declare function invokeLifecycleHook(module: Module, step: ModuleLifecycleStep, context: ModuleContext, contextStorage?: ContextStorage, phase?: ModuleLifecyclePhase): Promise<void>;
+export declare function canModuleEnterPhase(moduleId: ModuleId, hook: ModuleLifecycleStep, states: LifecycleStateMap): boolean;
 export declare function setLifecycleState(moduleId: ModuleId, phase: ModuleLifecyclePhase, states: LifecycleStateMap, error?: unknown): void;
-export declare function executeLifecyclePhase(order: readonly ModuleId[], hook: keyof ModuleLifecycleHooks, activePhase: ModuleLifecyclePhase, completedPhase: ModuleLifecyclePhase, continueOnError: boolean, registry: ModuleRegistry, loader: ModuleLoader, states: LifecycleStateMap): Promise<{
+export declare function executeLifecyclePhase(order: readonly ModuleId[], hook: ModuleLifecycleStep, activePhase: ModuleLifecyclePhase, completedPhase: ModuleLifecyclePhase, continueOnError: boolean, registry: ModuleRegistry, loader: ModuleLoader, states: LifecycleStateMap, contextStorage?: ContextStorage): Promise<{
     readonly completed: readonly ModuleId[];
     readonly failed: readonly ModuleId[];
+    readonly skipped: readonly ModuleLifecycleSkip[];
 }>;
 //# sourceMappingURL=moduleLifecycle.stateMachine.d.ts.map