@zudojs/core 0.1.0 → 1.1.0

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,186 @@ export class ModuleLifecycleManager {
             continueOnStopError: options.continueOnStopError ?? true,
             continueOnDestroyError: options.continueOnDestroyError ?? true,
         };
+        this.contextStorage = options.contextStorage ?? getDefaultContextStorage();
     }
-    async initialize() {
+    async initialize(options = {}) {
         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", options.continueOnError ?? this.options.continueOnInitializeError, this.registry, this.loader, this.states, this.contextStorage);
+            }
+            catch (error) {
+                await this.rollbackAfterFailure(error, { stopFirst: false });
+                throw error;
+            }
         });
     }
-    async start() {
+    async start(options = {}) {
         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", options.continueOnError ?? this.options.continueOnStartError, this.registry, this.loader, this.states, this.contextStorage);
+            }
+            catch (error) {
+                await this.rollbackAfterFailure(error, { stopFirst: true });
+                throw error;
+            }
         });
     }
-    async stop() {
+    async stop(options = {}) {
         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", options.continueOnError ?? this.options.continueOnStopError, this.registry, this.loader, this.states, this.contextStorage);
         });
     }
-    async destroy() {
+    async destroy(options = {}) {
         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", options.continueOnError ?? 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.resolveDependencies(registration).some((dependency) => dependency.id === moduleId);
+            if (dependsOnModule)
+                dependents.push(registration.definition.id);
+        }
+        return dependents;
+    }
+    /**
+     * Dependencies of a registered module: those declared on the
+     * definition plus any the loaded instance declares itself
+     * (`Module.dependencies`, e.g. via the BaseModule constructor).
+     * Instance-declared dependencies are required; a definition
+     * entry for the same id wins so optional/version flags survive.
+     */
+    resolveDependencies(registration) {
+        return resolveRegistrationDependencies(this.registry, registration);
+    }
     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() {
@@ -77,20 +228,31 @@ export class ModuleLifecycleManager {
     isDestroyed(moduleId) {
         return isModuleDestroyed(moduleId, this.states);
     }
+    /**
+     * Builds the dependency graph over the loaded modules only.
+     *
+     * Lifecycle phases run for loaded modules, so a registered but
+     * unloaded definition (autoLoad: false) must not be able to
+     * break them with a missing or circular dependency of its own.
+     * Dependencies of a loaded module that are not loaded are kept
+     * as edges so the ordering reports them as missing.
+     */
     createGraph() {
-        const nodes = this.registry.getAll().map((r) => ({
+        const nodes = this.registry
+            .getAll()
+            .filter((r) => r.state === "loaded")
+            .map((r) => ({
             id: r.definition.id,
-            dependencies: this.registry.getDependencies(r.definition.id),
+            dependencies: this.resolveDependencies(r),
+            version: r.definition.version,
         }));
         return createModuleDependencyGraph(nodes);
     }
     getStartupOrder() {
-        const order = resolveModuleStartupOrder(this.createGraph());
-        return Object.freeze(order.filter((id) => this.registry.get(id)?.state === "loaded"));
+        return resolveModuleStartupOrder(this.createGraph());
     }
     getShutdownOrder() {
-        const order = resolveModuleShutdownOrder(this.createGraph());
-        return Object.freeze(order.filter((id) => this.registry.get(id)?.state === "loaded"));
+        return resolveModuleShutdownOrder(this.createGraph());
     }
     async runExclusive(operation) {
         while (this.operation)
@@ -109,6 +271,29 @@ export class ModuleLifecycleManager {
         }
     }
 }
+/**
+ * Resolves the dependencies of a registration: definition-declared
+ * dependencies plus the ids the loaded instance declares through
+ * `Module.dependencies`. Shared by the lifecycle manager and the
+ * loader so both agree on the graph.
+ */
+export function resolveRegistrationDependencies(registry, registration) {
+    const declared = registry.getDependencies(registration.definition.id);
+    const instanceDependencies = registration.instance?.dependencies ?? [];
+    if (instanceDependencies.length === 0)
+        return declared;
+    const seen = new Set(declared.map((dependency) => dependency.id));
+    const merged = [...declared];
+    for (const id of instanceDependencies) {
+        if (typeof id !== "string" || id.length === 0 || seen.has(id))
+            continue;
+        if (id === registration.definition.id)
+            continue;
+        seen.add(id);
+        merged.push(Object.freeze({ id, optional: false }));
+    }
+    return Object.freeze(merged);
+}
 /** Creates a module lifecycle manager. */
 export function createModuleLifecycleManager(registry, loader, options = {}) {
     return new ModuleLifecycleManager(registry, loader, options);

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

package/dist/modules/moduleLifecycle/moduleLifecycle.stateMachine.js

@@ -1,11 +1,23 @@
 import { ModuleLifecycleError } from "./moduleLifecycle.type.js";
-/** Ensures lifecycle state is synchronized with the registry. */
+import { ModuleNotFoundError } from "../moduleError/moduleError.registration.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 function ensureStateSynchronized(registry, states) {
+    const registered = new Set();
     for (const registration of registry.getAll()) {
         const moduleId = registration.definition.id;
+        registered.add(moduleId);
         if (!states.has(moduleId))
             states.set(moduleId, { moduleId, phase: "created" });
     }
+    for (const moduleId of [...states.keys()]) {
+        if (!registered.has(moduleId))
+            states.delete(moduleId);
+    }
 }
 export function getLifecycleState(moduleId, states) {
     return states.get(moduleId);
@@ -13,7 +25,7 @@ export function getLifecycleState(moduleId, states) {
 export function requireLifecycleState(moduleId, states) {
     const state = getLifecycleState(moduleId, states);
     if (!state)
-        throw new Error(`No lifecycle state exists for module "${moduleId}".`);
+        throw new ModuleNotFoundError(moduleId);
     return state;
 }
 export function getAllLifecycleStates(states) {
@@ -29,13 +41,59 @@ export function isModuleStarted(moduleId, states) {
 export function isModuleDestroyed(moduleId, states) {
     return getLifecycleState(moduleId, states)?.phase === "destroyed";
 }
-export async function invokeLifecycleHook(module, hook, context) {
-    const lifecycleModule = module;
-    const handler = lifecycleModule[hook];
+/**
+ * Maps each lifecycle step to the hook of the public Module
+ * contract (ModuleLifecycle) that the engine invokes for it.
+ */
+const STEP_HOOKS = {
+    initialize: "onInitialize",
+    start: "onReady",
+    stop: "onShutdown",
+    destroy: "onDestroy",
+};
+/**
+ * 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 async function invokeLifecycleHook(module, step, context, contextStorage, phase = STEP_PHASES[step]) {
+    const hookName = STEP_HOOKS[step];
+    const handler = module[hookName];
     if (typeof handler !== "function")
         return;
-    await handler.call(module, context);
+    const invoke = () => handler.call(module, context);
+    if (contextStorage?.has()) {
+        await contextStorage.runDerived({
+            module: module.id,
+            operation: hookName,
+            metadata: { moduleId: module.id, phase },
+        }, invoke);
+        return;
+    }
+    await invoke();
 }
+/**
+ * Active phase a module is in while each step's hook runs.
+ */
+const STEP_PHASES = {
+    initialize: "initializing",
+    start: "starting",
+    stop: "stopping",
+    destroy: "destroying",
+};
 export function canModuleEnterPhase(moduleId, hook, states) {
     const state = getLifecycleState(moduleId, states);
     if (!state)
@@ -50,7 +108,9 @@ export function canModuleEnterPhase(moduleId, hook, states) {
         case "destroy":
             return (state.phase === "stopped" ||
                 state.phase === "initialized" ||
-                state.phase === "created");
+                state.phase === "created" ||
+                state.phase === "started" ||
+                state.phase === "failed");
         default:
             return false;
     }
@@ -68,9 +128,30 @@ export function setLifecycleState(moduleId, phase, states, error) {
         destroyedAt: phase === "destroyed" ? now : previous?.destroyedAt,
     }));
 }
-export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states) {
+/**
+ * Phases that count as "already satisfied" for a hook: modules
+ * in these phases are silently skipped rather than reported.
+ */
+const SATISFIED_PHASES = {
+    initialize: ["initialized", "starting", "started"],
+    start: ["started"],
+    stop: ["created", "initialized", "stopped", "destroying", "destroyed"],
+    destroy: ["destroyed"],
+};
+/**
+ * Phases a required dependency must be in before a dependent
+ * module may enter a forward phase.
+ */
+const REQUIRED_DEPENDENCY_PHASES = {
+    initialize: ["initialized", "starting", "started"],
+    start: ["started"],
+};
+export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states, contextStorage) {
     const completed = [];
     const failed = [];
+    const skipped = [];
+    const blocked = new Set();
+    const requiredDependencyPhases = REQUIRED_DEPENDENCY_PHASES[hook];
     for (const moduleId of order) {
         const registration = registry.get(moduleId);
         if (!registration?.instance)
@@ -84,11 +165,49 @@ export async function executeLifecyclePhase(order, hook, activePhase, completedP
                 throw new ModuleLifecycleError(moduleId, activePhase, new Error(`Module "${moduleId}" does not have a ModuleContext.`));
             continue;
         }
-        if (!canModuleEnterPhase(moduleId, hook, states))
+        const currentPhase = getLifecycleState(moduleId, states)?.phase;
+        if (!canModuleEnterPhase(moduleId, hook, states)) {
+            if (currentPhase !== undefined &&
+                SATISFIED_PHASES[hook].includes(currentPhase)) {
+                continue;
+            }
+            skipped.push({
+                moduleId,
+                reason: `Module is in phase "${currentPhase ?? "unknown"}" and cannot enter ${hook}.`,
+            });
+            blocked.add(moduleId);
             continue;
+        }
+        /*
+         * Forward phases only run when every required dependency
+         * reached the requisite state. Modules whose dependencies
+         * failed (or were skipped) are skipped with a reason instead
+         * of being initialized against a broken dependency.
+         */
+        if (requiredDependencyPhases) {
+            const blockingDependency = registry
+                .getDependencies(moduleId)
+                .find((dependency) => {
+                if (dependency.optional)
+                    return false;
+                if (blocked.has(dependency.id) || failed.includes(dependency.id))
+                    return true;
+                const dependencyPhase = getLifecycleState(dependency.id, states)?.phase;
+                return (dependencyPhase === undefined ||
+                    !requiredDependencyPhases.includes(dependencyPhase));
+            });
+            if (blockingDependency) {
+                skipped.push({
+                    moduleId,
+                    reason: `Dependency "${blockingDependency.id}" is not ready for ${hook}.`,
+                });
+                blocked.add(moduleId);
+                continue;
+            }
+        }
         setLifecycleState(moduleId, activePhase, states);
         try {
-            await invokeLifecycleHook(module, hook, context);
+            await invokeLifecycleHook(module, hook, context, contextStorage, activePhase);
             setLifecycleState(moduleId, completedPhase, states);
             completed.push(moduleId);
         }
@@ -102,6 +221,7 @@ export async function executeLifecyclePhase(order, hook, activePhase, completedP
     return {
         completed: Object.freeze([...completed]),
         failed: Object.freeze([...failed]),
+        skipped: Object.freeze([...skipped]),
     };
 }
 //# sourceMappingURL=moduleLifecycle.stateMachine.js.map

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

@@ -1,5 +1,5 @@
-import type { ModuleId } from "../module.js";
-import type { ModuleContext } from "../moduleContext.context.js";
+import type { ModuleId, ModuleLifecycle } from "../module.js";
+import type { ContextStorage } from "../../context/provider/contextStorage.storage.js";
 /**
  * Lifecycle phases supported by the module system.
  */
@@ -16,34 +16,34 @@ export interface ModuleLifecycleState {
     readonly stoppedAt?: Date;
     readonly destroyedAt?: Date;
 }
+/**
+ * Canonical lifecycle hook names of the public Module contract.
+ *
+ * The lifecycle engine invokes exactly these methods:
+ *
+ * initialize step → onInitialize
+ * start step      → onReady
+ * stop step       → onShutdown
+ * destroy step    → onDestroy
+ */
+export type ModuleLifecycleHookName = "onInitialize" | "onReady" | "onShutdown" | "onDestroy";
+/**
+ * Lifecycle steps executed by the module lifecycle engine.
+ *
+ * Each step maps onto one ModuleLifecycleHookName; see
+ * ModuleLifecycleHookName for the mapping.
+ */
+export type ModuleLifecycleStep = "initialize" | "start" | "stop" | "destroy";
 /**
  * Lifecycle hooks supported by a module.
  *
- * Modules can implement any subset of these hooks.
+ * @deprecated The module hook contract is ModuleLifecycle
+ * (onInitialize/onReady/onShutdown/onDestroy). This alias exists
+ * for source compatibility only; the legacy
+ * initialize/start/stop/destroy method names are never invoked
+ * by the lifecycle engine.
  */
-export interface ModuleLifecycleHooks {
-    /**
-     * Called before the module starts accepting work.
-     */
-    initialize?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called after all modules have initialized.
-     *
-     * This is useful when a module needs other modules to
-     * already be initialized before it becomes active.
-     */
-    start?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called when the application begins shutting down.
-     */
-    stop?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called after the module has stopped.
-     *
-     * This is the place for final resource cleanup.
-     */
-    destroy?(context: ModuleContext): void | Promise<void>;
-}
+export type ModuleLifecycleHooks = ModuleLifecycle;
 /**
  * Options controlling module lifecycle behavior.
  */
@@ -72,20 +72,70 @@ export interface ModuleLifecycleOptions {
      * Defaults to true.
      */
     readonly continueOnDestroyError?: boolean;
+    /**
+     * ContextStorage consulted before every hook invocation. When an
+     * execution context is active in it (the runtime establishes its
+     * RuntimeExecutionContext around bootstrap and shutdown), each
+     * hook runs in a context derived from it with
+     * `module`/`operation` set and `{ moduleId, phase }` merged into
+     * the metadata. When no context is active the hook is invoked
+     * directly.
+     *
+     * Defaults to getDefaultContextStorage(); pass the runtime's
+     * storage when injecting a custom one.
+     */
+    readonly contextStorage?: ContextStorage;
 }
-import { ModuleLifecycleError as BaseModuleLifecycleError } from "@zudojs/errors";
+/**
+ * Per-call overrides accepted by the ModuleLifecycleManager phase
+ * methods (initialize/start/stop/destroy).
+ */
+export interface ModuleLifecyclePhaseOptions {
+    /**
+     * Overrides the manager's continueOn*Error setting for this one
+     * phase run. The runtime passes its own startup/shutdown flags
+     * here so a hand-assembled manager cannot disagree with the
+     * runtime that drives it.
+     */
+    readonly continueOnError?: boolean;
+}
+import { ModuleOperationError } from "../moduleError/moduleError.lifecycle.js";
 /**
  * Error thrown when a module lifecycle operation fails.
+ *
+ * Part of the core module error taxonomy: it is a ModuleError
+ * carrying the phase-specific code (MODULE_INITIALIZATION_FAILED,
+ * MODULE_START_FAILED, ...), so callers can catch it by type or by
+ * code.
  */
-export declare class ModuleLifecycleError extends BaseModuleLifecycleError {
+export declare class ModuleLifecycleError extends ModuleOperationError {
+    /**
+     * Errors encountered while rolling back already-completed
+     * modules after this failure. Best-effort: rollback itself
+     * never masks the original failure.
+     */
+    rollbackErrors?: readonly unknown[];
     constructor(moduleId: ModuleId, phase: ModuleLifecyclePhase, cause: unknown);
 }
+/**
+ * Reason a module was skipped during a lifecycle phase.
+ */
+export interface ModuleLifecycleSkip {
+    readonly moduleId: ModuleId;
+    readonly reason: string;
+}
 /**
  * Result of a lifecycle operation.
  */
 export interface ModuleLifecycleResult {
     readonly completed: readonly ModuleId[];
     readonly failed: readonly ModuleId[];
+    /**
+     * Modules that could not participate in the phase, with the
+     * reason: their required dependencies failed or were skipped,
+     * or their current phase does not permit the transition.
+     */
+    readonly skipped: readonly ModuleLifecycleSkip[];
 }
 /**
  * Internal lifecycle state map.