@zudojs/core 0.1.0 → 1.1.0

package/dist/modules/moduleLifecycle/moduleLifecycle.type.js

@@ -1,11 +1,22 @@
-import { ModuleLifecycleError as BaseModuleLifecycleError } from "@zudojs/errors";
+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 class ModuleLifecycleError extends BaseModuleLifecycleError {
+export 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;
     constructor(moduleId, phase, cause) {
-        const message = cause instanceof Error ? cause.message : String(cause);
-        super(moduleId, phase, `Module "${moduleId}" failed during ${phase}: ${message}`, cause);
+        super(moduleId, phase, cause);
+        this.name = "ModuleLifecycleError";
     }
 }
 //# sourceMappingURL=moduleLifecycle.type.js.map

package/dist/modules/moduleLoader/moduleLoader.loader.d.ts

@@ -7,6 +7,11 @@ import type { ModuleLoaderOptions, ModuleLoadResult } from "./moduleLoader.type.
  *
  * Reads definitions from registry, builds dependency graph,
  * validates, resolves startup order, instantiates modules.
+ *
+ * Dependencies are always resolved against every registered
+ * definition. autoLoad filtering applies only to load roots:
+ * a module registered with autoLoad disabled is still loaded
+ * when another loading module requires it.
  */
 export declare class ModuleLoader {
     private readonly application;
@@ -15,21 +20,50 @@ export declare class ModuleLoader {
     private readonly registry;
     private readonly allowExplicitLoad;
     private readonly contexts;
+    private readonly inFlightLoads;
     constructor(registry: ModuleRegistry, options: ModuleLoaderOptions);
-    /** Loads every module whose definition has autoLoad enabled. */
+    /**
+     * Loads every module whose definition has autoLoad enabled,
+     * plus every module those modules require (regardless of the
+     * required module's autoLoad setting).
+     */
     loadAll(): Promise<ModuleLoadResult>;
-    /** Loads a specific module and all of its required dependencies. */
+    /**
+     * Loads a specific module and all of its required dependencies.
+     *
+     * Concurrent load() calls for the same module share a single
+     * in-flight load.
+     */
     load(moduleId: ModuleId): Promise<Module>;
-    private loadDefinitions;
+    /**
+     * Loads the dependency closure of the requested module ids.
+     */
+    private loadClosure;
+    /**
+     * Collects the dependency closure of the requested modules
+     * across every registered definition.
+     *
+     * Optional dependencies join the closure only when they are
+     * registered; missing required dependencies are reported with
+     * the module that needs them.
+     */
+    private collectClosure;
     private createGraph;
-    private collectDependencies;
     private instantiate;
     private createModuleLogger;
-    private isExplicitlyRequested;
     getContext(moduleId: ModuleId): ModuleContext | undefined;
     requireContext(moduleId: ModuleId): ModuleContext;
     getContexts(): ReadonlyMap<ModuleId, ModuleContext>;
     isLoaded(moduleId: ModuleId): boolean;
+    /**
+     * Forgets a module's runtime instance and context.
+     *
+     * The loader does not run lifecycle hooks; callers that need
+     * the instance shut down first should use
+     * ModuleLifecycleManager.unloadModule(). Returns false when the
+     * module is not registered or holds no instance.
+     */
+    unload(moduleId: ModuleId): boolean;
 }
 /** Creates a module loader. */
 export declare function createModuleLoader(registry: ModuleRegistry, options: ModuleLoaderOptions): ModuleLoader;

package/dist/modules/moduleLoader/moduleLoader.loader.js

@@ -1,11 +1,20 @@
 import { createModuleContext } from "../moduleContext.context.js";
-import { createModuleDependencyGraph, resolveModuleStartupOrder, validateModuleDependencyGraph, } from "../moduleDependency/index.js";
+import { createModuleDependencyGraph, resolveModuleStartupOrder, } from "../moduleDependency/index.js";
 import { ModuleLoadError } from "./moduleLoader.type.js";
+import { ModuleError } from "../moduleError/moduleError.base.js";
+import { MissingModuleDependencyError } from "../moduleError/moduleError.dependency.js";
+import { InvalidModuleInstanceError, ModuleInstantiationError, } from "../moduleError/moduleError.lifecycle.js";
+import { ModuleNotFoundError } from "../moduleError/moduleError.registration.js";
 /**
  * Default module loader.
  *
  * Reads definitions from registry, builds dependency graph,
  * validates, resolves startup order, instantiates modules.
+ *
+ * Dependencies are always resolved against every registered
+ * definition. autoLoad filtering applies only to load roots:
+ * a module registered with autoLoad disabled is still loaded
+ * when another loading module requires it.
  */
 export class ModuleLoader {
     application;
@@ -14,6 +23,7 @@ export class ModuleLoader {
     registry;
     allowExplicitLoad;
     contexts = new Map();
+    inFlightLoads = new Map();
     constructor(registry, options) {
         this.registry = registry;
         this.application = options.application;
@@ -21,14 +31,24 @@ export class ModuleLoader {
         this.logger = options.logger;
         this.allowExplicitLoad = options.allowExplicitLoad ?? true;
     }
-    /** Loads every module whose definition has autoLoad enabled. */
+    /**
+     * Loads every module whose definition has autoLoad enabled,
+     * plus every module those modules require (regardless of the
+     * required module's autoLoad setting).
+     */
     async loadAll() {
-        const definitions = this.registry
+        const roots = this.registry
             .getDefinitions()
-            .filter((d) => d.autoLoad !== false);
-        return this.loadDefinitions(definitions);
+            .filter((definition) => definition.autoLoad !== false)
+            .map((definition) => definition.id);
+        return this.loadClosure(roots, { reportSkipped: true });
     }
-    /** Loads a specific module and all of its required dependencies. */
+    /**
+     * Loads a specific module and all of its required dependencies.
+     *
+     * Concurrent load() calls for the same module share a single
+     * in-flight load.
+     */
     async load(moduleId) {
         const registration = this.registry.require(moduleId);
         if (registration.state === "loaded" && registration.instance)
@@ -36,39 +56,83 @@ export class ModuleLoader {
         if (registration.definition.autoLoad === false && !this.allowExplicitLoad) {
             throw new ModuleLoadError(moduleId, new Error(`Module "${moduleId}" is not configured for explicit loading.`));
         }
-        const definitions = this.collectDependencies(moduleId);
-        await this.loadDefinitions(definitions);
-        const loaded = this.registry.require(moduleId);
-        if (!loaded.instance)
-            throw new ModuleLoadError(moduleId, new Error("Module was not instantiated."));
-        return loaded.instance;
+        const pending = this.inFlightLoads.get(moduleId);
+        if (pending)
+            return pending;
+        const loadPromise = (async () => {
+            await this.loadClosure([moduleId], { reportSkipped: false });
+            const loaded = this.registry.require(moduleId);
+            if (!loaded.instance)
+                throw new ModuleLoadError(moduleId, new Error("Module was not instantiated."));
+            return loaded.instance;
+        })().finally(() => {
+            this.inFlightLoads.delete(moduleId);
+        });
+        this.inFlightLoads.set(moduleId, loadPromise);
+        return loadPromise;
     }
-    async loadDefinitions(definitions) {
-        if (definitions.length === 0)
-            return { loaded: [], alreadyLoaded: [], skipped: [], order: [] };
-        const graph = this.createGraph(definitions);
-        const missing = validateModuleDependencyGraph(graph);
-        if (missing.length > 0)
-            throw new ModuleLoadError("module-dependencies", new Error(`Missing required modules: ${missing.join(", ")}`));
-        const order = resolveModuleStartupOrder(graph);
+    /**
+     * Loads the dependency closure of the requested module ids.
+     */
+    async loadClosure(requested, options) {
+        const closure = this.collectClosure(requested);
         const loaded = [];
         const alreadyLoaded = [];
-        const skipped = [];
-        for (const moduleId of order) {
-            const registration = this.registry.get(moduleId);
-            if (!registration)
-                throw new ModuleLoadError(moduleId, new Error(`Module "${moduleId}" disappeared from the registry during loading.`));
-            if (registration.state === "loaded" && registration.instance) {
-                alreadyLoaded.push(registration.instance);
-                continue;
+        const order = [];
+        /*
+         * Instances may declare dependencies of their own
+         * (Module.dependencies) that the definition does not list.
+         * Those are only known after instantiation, so the closure is
+         * extended and loaded in rounds until nothing new appears.
+         */
+        let pending = new Set(closure.keys());
+        while (pending.size > 0) {
+            const graph = this.createGraph([...closure.values()]);
+            const roundOrder = resolveModuleStartupOrder(graph).filter((id) => pending.has(id));
+            const discovered = [];
+            for (const moduleId of roundOrder) {
+                const registration = this.registry.get(moduleId);
+                if (!registration)
+                    throw new ModuleLoadError(moduleId, new Error(`Module "${moduleId}" disappeared from the registry during loading.`));
+                order.push(moduleId);
+                let instance;
+                if (registration.state === "loaded" && registration.instance) {
+                    instance = registration.instance;
+                    alreadyLoaded.push(instance);
+                }
+                else {
+                    instance = await this.instantiate(registration.definition);
+                    loaded.push(instance);
+                }
+                for (const dependencyId of instance.dependencies ?? []) {
+                    if (closure.has(dependencyId))
+                        continue;
+                    if (!this.registry.has(dependencyId))
+                        throw new MissingModuleDependencyError(moduleId, dependencyId);
+                    discovered.push(dependencyId);
+                }
             }
-            if (registration.definition.autoLoad === false &&
-                !this.isExplicitlyRequested(moduleId, definitions)) {
-                skipped.push(moduleId);
-                continue;
+            const extra = this.collectClosure(discovered);
+            pending = new Set();
+            for (const [id, definition] of extra) {
+                if (closure.has(id))
+                    continue;
+                closure.set(id, definition);
+                pending.add(id);
+            }
+        }
+        /*
+         * Skipped modules are determined after loading so that an
+         * autoLoad:false module pulled in by an instance-declared
+         * dependency is reported as loaded, not skipped.
+         */
+        const skipped = [];
+        if (options.reportSkipped) {
+            for (const definition of this.registry.getDefinitions()) {
+                if (definition.autoLoad === false && !closure.has(definition.id)) {
+                    skipped.push(definition.id);
+                }
             }
-            const instance = await this.instantiate(registration.definition);
-            loaded.push(instance);
         }
         return {
             loaded: Object.freeze([...loaded]),
@@ -77,29 +141,41 @@ export class ModuleLoader {
             order: Object.freeze([...order]),
         };
     }
-    createGraph(definitions) {
-        const nodes = definitions.map((d) => ({
-            id: d.id,
-            dependencies: this.registry.getDependencies(d.id),
-        }));
-        return createModuleDependencyGraph(nodes);
-    }
-    collectDependencies(moduleId) {
+    /**
+     * Collects the dependency closure of the requested modules
+     * across every registered definition.
+     *
+     * Optional dependencies join the closure only when they are
+     * registered; missing required dependencies are reported with
+     * the module that needs them.
+     */
+    collectClosure(requested) {
         const collected = new Map();
-        const visit = (currentId) => {
+        const queue = [...requested];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
             if (collected.has(currentId))
-                return;
+                continue;
             const registration = this.registry.require(currentId);
             collected.set(currentId, registration.definition);
             for (const dependency of this.registry.getDependencies(currentId)) {
-                if (dependency.optional && !this.registry.has(dependency.id))
-                    continue;
-                if (this.registry.has(dependency.id))
-                    visit(dependency.id);
+                if (!this.registry.has(dependency.id)) {
+                    if (dependency.optional)
+                        continue;
+                    throw new MissingModuleDependencyError(currentId, dependency.id);
+                }
+                queue.push(dependency.id);
             }
-        };
-        visit(moduleId);
-        return Object.freeze([...collected.values()]);
+        }
+        return collected;
+    }
+    createGraph(definitions) {
+        const nodes = definitions.map((d) => ({
+            id: d.id,
+            dependencies: this.registry.getDependencies(d.id),
+            version: d.version,
+        }));
+        return createModuleDependencyGraph(nodes);
     }
     async instantiate(definition) {
         const moduleId = definition.id;
@@ -107,9 +183,9 @@ export class ModuleLoader {
         try {
             const module = await definition.factory(definition.options);
             if (!module || typeof module !== "object")
-                throw new TypeError(`Module factory for "${moduleId}" did not return a valid module.`);
+                throw new InvalidModuleInstanceError(moduleId, `Module factory for "${moduleId}" did not return a valid module.`);
             if (module.id !== moduleId)
-                throw new TypeError(`Module factory returned module "${module.id}" but expected "${moduleId}".`);
+                throw new InvalidModuleInstanceError(moduleId, `Module factory returned module "${module.id}" but expected "${moduleId}".`);
             if (typeof module.attach === "function")
                 module.attach(this.application);
             const moduleLogger = this.createModuleLogger(module);
@@ -121,7 +197,22 @@ export class ModuleLoader {
                     logger: moduleLogger,
                 },
                 metadata: definition.metadata,
-                moduleContexts: this.contexts,
+                /*
+                 * Modules get a resolver, never the shared context map, so
+                 * they cannot enumerate or reach undeclared modules.
+                 */
+                moduleContexts: (dependencyId) => this.contexts.get(dependencyId),
+                /*
+                 * Dependencies declared by the instance itself
+                 * (Module.dependencies) are honoured alongside the
+                 * definition's, matching the lifecycle ordering.
+                 */
+                declaredDependencies: [
+                    ...this.registry
+                        .getDependencies(moduleId)
+                        .map((dependency) => dependency.id),
+                    ...(module.dependencies ?? []),
+                ],
             });
             this.contexts.set(moduleId, context);
             this.registry.setState(moduleId, "loaded", { instance: module });
@@ -129,7 +220,9 @@ export class ModuleLoader {
         }
         catch (error) {
             this.registry.setState(moduleId, "failed", { error });
-            throw new ModuleLoadError(moduleId, error);
+            if (error instanceof ModuleError)
+                throw error;
+            throw new ModuleInstantiationError(moduleId, error);
         }
     }
     createModuleLogger(module) {
@@ -138,16 +231,13 @@ export class ModuleLoader {
             return logger.child({ moduleId: module.id, module: module.name });
         return this.logger;
     }
-    isExplicitlyRequested(moduleId, definitions) {
-        return definitions.some((d) => d.id === moduleId);
-    }
     getContext(moduleId) {
         return this.contexts.get(moduleId);
     }
     requireContext(moduleId) {
         const context = this.getContext(moduleId);
         if (!context)
-            throw new Error(`Module "${moduleId}" has not been loaded.`);
+            throw new ModuleNotFoundError(moduleId);
         return context;
     }
     getContexts() {
@@ -156,6 +246,25 @@ export class ModuleLoader {
     isLoaded(moduleId) {
         return this.registry.get(moduleId)?.state === "loaded";
     }
+    /**
+     * Forgets a module's runtime instance and context.
+     *
+     * The loader does not run lifecycle hooks; callers that need
+     * the instance shut down first should use
+     * ModuleLifecycleManager.unloadModule(). Returns false when the
+     * module is not registered or holds no instance.
+     */
+    unload(moduleId) {
+        const registration = this.registry.get(moduleId);
+        if (!registration)
+            return false;
+        const hadInstance = this.contexts.delete(moduleId);
+        if (registration.state === "registered" ||
+            registration.state === "unloaded")
+            return hadInstance;
+        this.registry.setState(moduleId, "unloaded");
+        return true;
+    }
 }
 /** Creates a module loader. */
 export function createModuleLoader(registry, options) {

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

@@ -47,11 +47,13 @@ export interface ModuleLoadResult {
      */
     readonly order: readonly ModuleId[];
 }
-import { ModuleLoadError as BaseModuleLoadError } from "@zudojs/errors";
+import { ModuleError } from "../moduleError/moduleError.base.js";
 /**
  * Error thrown when one or more modules cannot be loaded.
+ *
+ * Part of the core module error taxonomy (code MODULE_LOAD_FAILED).
  */
-export declare class ModuleLoadError extends BaseModuleLoadError {
+export declare class ModuleLoadError extends ModuleError {
     constructor(moduleId: ModuleId, cause: unknown);
 }
 //# sourceMappingURL=moduleLoader.type.d.ts.map

package/dist/modules/moduleLoader/moduleLoader.type.js

@@ -1,11 +1,18 @@
-import { ModuleLoadError as BaseModuleLoadError } from "@zudojs/errors";
+import { ModuleError, ModuleErrorCode, } from "../moduleError/moduleError.base.js";
 /**
  * Error thrown when one or more modules cannot be loaded.
+ *
+ * Part of the core module error taxonomy (code MODULE_LOAD_FAILED).
  */
-export class ModuleLoadError extends BaseModuleLoadError {
+export class ModuleLoadError extends ModuleError {
     constructor(moduleId, cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
-        super(moduleId, `Failed to load module "${moduleId}": ${message}`, cause);
+        super(`Failed to load module "${moduleId}": ${message}`, {
+            code: ModuleErrorCode.LOAD_FAILED,
+            moduleId,
+            cause,
+        });
+        this.name = "ModuleLoadError";
     }
 }
 //# sourceMappingURL=moduleLoader.type.js.map

package/dist/modules/moduleMetadata.metadata.js

@@ -1,3 +1,4 @@
+import { InvalidModuleDefinitionError } from "./moduleError/moduleError.registration.js";
 function normalizeOptionalString(value) {
     if (value === undefined)
         return undefined;
@@ -35,12 +36,12 @@ function validateModuleMetadata(metadata) {
     if (metadata.deprecated &&
         metadata.deprecationMessage === undefined &&
         metadata.replacement === undefined) {
-        throw new TypeError("Deprecated modules should provide either a deprecationMessage or replacement module.");
+        throw new InvalidModuleDefinitionError("Deprecated modules should provide either a deprecationMessage or replacement module.");
     }
     if (metadata.homepage && !isValidUrl(metadata.homepage))
-        throw new TypeError(`Invalid module homepage URL: ${metadata.homepage}`);
+        throw new InvalidModuleDefinitionError(`Invalid module homepage URL: ${metadata.homepage}`);
     if (metadata.repository && !isValidUrl(metadata.repository))
-        throw new TypeError(`Invalid module repository URL: ${metadata.repository}`);
+        throw new InvalidModuleDefinitionError(`Invalid module repository URL: ${metadata.repository}`);
 }
 /** Creates immutable module metadata. */
 export function createModuleMetadata(options = {}) {
@@ -61,13 +62,22 @@ export function createModuleMetadata(options = {}) {
     validateModuleMetadata(metadata);
     return Object.freeze(metadata);
 }
+/**
+ * Removes keys whose value is undefined so spreading a metadata
+ * object cannot clobber defined values with undefined.
+ */
+function withoutUndefinedValues(metadata) {
+    if (!metadata)
+        return {};
+    return Object.fromEntries(Object.entries(metadata).filter(([, value]) => value !== undefined));
+}
 /** Merges two metadata objects. Values from `override` take precedence. */
 export function mergeModuleMetadata(base, override) {
     if (!base && !override)
         return createModuleMetadata();
     return createModuleMetadata({
-        ...(base ?? {}),
-        ...(override ?? {}),
+        ...withoutUndefinedValues(base),
+        ...withoutUndefinedValues(override),
         tags: [...(base?.tags ?? []), ...(override?.tags ?? [])],
         environments: override?.environments ?? base?.environments,
         extra: { ...(base?.extra ?? {}), ...(override?.extra ?? {}) },

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

@@ -3,6 +3,6 @@
  *
  * Stores module definitions and tracks their runtime state.
  */
-export { type ModuleRegistrationState, type ModuleRegistration, type ModuleRegistryOptions, type ModuleRegistryEventType, type ModuleRegistryEvent, type ModuleRegistryListener, type ModuleRegistry, } from "./moduleRegistry.type.js";
+export { type ModuleRegistrationState, type ModuleRegistration, type ModuleRegistryOptions, type ModuleRegisterOptions, type ModuleRegistryEventType, type ModuleRegistryEvent, type ModuleRegistryListener, type ModuleRegistry, } from "./moduleRegistry.type.js";
 export { DefaultModuleRegistry, createModuleRegistry, isModuleRegistration, } from "./moduleRegistry.registry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleRegistry/moduleRegistry.registry.d.ts

@@ -2,14 +2,14 @@ import type { Module, ModuleId } from "../module.js";
 import type { ModuleDefinition } from "../moduleDefinition.definition.js";
 import type { ModuleMetadata } from "../moduleMetadata.metadata.js";
 import type { ModuleDependency } from "../moduleDependency/moduleDependency.type.js";
-import type { ModuleRegistrationState, ModuleRegistration, ModuleRegistryOptions, ModuleRegistryListener, ModuleRegistry } from "./moduleRegistry.type.js";
+import type { ModuleRegistrationState, ModuleRegistration, ModuleRegistryOptions, ModuleRegistryListener, ModuleRegistry, ModuleRegisterOptions } from "./moduleRegistry.type.js";
 /** Default in-memory module registry. */
 export declare class DefaultModuleRegistry implements ModuleRegistry {
     private readonly registrations;
     private readonly listeners;
     private readonly allowReplacement;
     constructor(options?: ModuleRegistryOptions);
-    register<TModule extends Module>(definition: ModuleDefinition<TModule>): ModuleRegistration<TModule>;
+    register<TModule extends Module>(definition: ModuleDefinition<TModule>, options?: ModuleRegisterOptions): ModuleRegistration<TModule>;
     registerMany(definitions: readonly ModuleDefinition[]): readonly ModuleRegistration[];
     get(moduleId: ModuleId): ModuleRegistration | undefined;
     require(moduleId: ModuleId): ModuleRegistration;

package/dist/modules/moduleRegistry/moduleRegistry.registry.js

@@ -1,4 +1,6 @@
 import { isModuleDefinition } from "../moduleDefinition.definition.js";
+import { DuplicateModuleError, InvalidModuleDefinitionError, ModuleNotFoundError, } from "../moduleError/moduleError.registration.js";
+import { InvalidModuleStateError } from "../moduleError/moduleError.lifecycle.js";
 /** Default in-memory module registry. */
 export class DefaultModuleRegistry {
     registrations = new Map();
@@ -7,13 +9,36 @@ export class DefaultModuleRegistry {
     constructor(options = {}) {
         this.allowReplacement = options.allowReplacement ?? false;
     }
-    register(definition) {
+    register(definition, options = {}) {
         if (!isModuleDefinition(definition))
-            throw new TypeError("Invalid module definition.");
-        const moduleId = definition.id.trim();
+            throw new InvalidModuleDefinitionError("Invalid module definition.");
+        /*
+         * Ids are canonicalized when the definition is created
+         * (defineModule rejects untrimmed ids), so the registry can
+         * use definition.id directly.
+         */
+        const moduleId = definition.id;
+        if (moduleId !== moduleId.trim())
+            throw new InvalidModuleDefinitionError(`Module id "${moduleId}" must not contain leading or trailing whitespace.`, moduleId);
         const existing = this.registrations.get(moduleId);
         if (existing && !this.allowReplacement)
-            throw new Error(`Module "${moduleId}" is already registered.`);
+            throw new DuplicateModuleError(moduleId);
+        /*
+         * Replacing a definition whose module instance is already
+         * loaded (or currently loading) would strand the live
+         * instance: the lifecycle system would keep managing an
+         * object whose definition no longer exists. Callers must opt
+         * in explicitly with { replaceLoaded: true }.
+         */
+        if (existing &&
+            (existing.state === "loaded" || existing.state === "loading") &&
+            options.replaceLoaded !== true) {
+            throw new InvalidModuleStateError(moduleId, existing.state, [
+                "registered",
+                "failed",
+                "unloaded",
+            ]);
+        }
         const now = new Date();
         const registration = Object.freeze({
             definition,
@@ -42,7 +67,7 @@ export class DefaultModuleRegistry {
     require(moduleId) {
         const registration = this.get(moduleId);
         if (!registration)
-            throw new Error(`Module "${moduleId}" is not registered.`);
+            throw new ModuleNotFoundError(moduleId);
         return registration;
     }
     has(moduleId) {
@@ -78,9 +103,16 @@ export class DefaultModuleRegistry {
     setState(moduleId, state, details = {}) {
         const existing = this.require(moduleId);
         const now = new Date();
+        /*
+         * Leaving a state that carries a live instance drops the
+         * instance reference; the registry never keeps a stale module
+         * object around once it has been unloaded.
+         */
         const registration = Object.freeze({
             definition: existing.definition,
-            instance: details.instance ?? existing.instance,
+            instance: state === "unloaded"
+                ? undefined
+                : (details.instance ?? existing.instance),
             state,
             error: details.error,
             registeredAt: existing.registeredAt,

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

@@ -64,6 +64,23 @@ export interface ModuleRegistryEvent {
     readonly timestamp: Date;
 }
 export type ModuleRegistryListener = (event: ModuleRegistryEvent) => void | Promise<void>;
+/**
+ * Options accepted when registering a module definition.
+ */
+export interface ModuleRegisterOptions {
+    /**
+     * Allows replacing a definition whose module instance is
+     * already loaded (or loading).
+     *
+     * Replacing a loaded module strands the live instance, so it
+     * is rejected with InvalidModuleStateError unless the caller
+     * opts in explicitly. Replacement itself additionally requires
+     * the registry's allowReplacement option.
+     *
+     * Defaults to false.
+     */
+    readonly replaceLoaded?: boolean;
+}
 /**
  * Public contract for the module registry.
  */
@@ -71,7 +88,7 @@ export interface ModuleRegistry {
     /**
      * Registers a module definition.
      */
-    register<TModule extends Module>(definition: ModuleDefinition<TModule>): ModuleRegistration<TModule>;
+    register<TModule extends Module>(definition: ModuleDefinition<TModule>, options?: ModuleRegisterOptions): ModuleRegistration<TModule>;
     /**
      * Registers multiple definitions.
      */