@codefast/di 0.5.0-canary.9 → 0.6.0

package/dist/container/container.js

@@ -1,23 +1,40 @@
-import { NO_INSTANCE } from "#/binding";
 import { BindingChain } from "#/container/binding-builders";
-import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, } from "#/errors";
+import { NO_INSTANCE } from "#/core/binding";
+import { effectiveBindingScope } from "#/core/binding-scope";
+import { constraintRequirementOf } from "#/core/constraint-requirement";
+import { isSyncModule, MODULE_SETUP } from "#/core/module";
+import { BindingRegistry } from "#/core/registry";
+import { tokenName } from "#/core/token";
+import { RESOLUTION_DIAGNOSTICS } from "#/errors/diagnostics";
+import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#/errors/errors";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/injection/resolve-options";
 import { buildDependencyGraph } from "#/introspection/dependency-graph";
 import { Inspector } from "#/introspection/inspector";
+import { LifecycleManager } from "#/lifecycle/lifecycle-manager";
+import { ScopeManager } from "#/lifecycle/scope-manager";
 import { MetadataReaderToken } from "#/metadata/metadata-reader-token";
 import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
-import { isSyncModule, MODULE_SETUP } from "#/module";
-import { BindingRegistry } from "#/registry";
-import { effectiveBindingScope } from "#/resolution/binding-scope";
-import { RESOLUTION_DIAGNOSTICS } from "#/resolution/diagnostics";
-import { LifecycleManager } from "#/resolution/lifecycle";
-import { ROOT_BRANCH } from "#/resolution/resolution-path";
-import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
+import { verifyingMetadataReader } from "#/metadata/verifying-metadata-reader";
+import { ROOT_BRANCH } from "#/resolution/path/resolution-path";
 import { DependencyResolver } from "#/resolution/resolver";
-import { ScopeManager } from "#/resolution/scope";
-import { tokenName } from "#/token";
-// ── DefaultContainer ──────────────────────────────────────────────────────────
+// A Record rather than an if-chain, so a new `BindingScope` is a compile error here instead of
+// silently landing in whichever branch happened to be last.
+const APPLY_BINDING_SCOPE = {
+    singleton: (builder) => {
+        builder.singleton();
+    },
+    scoped: (builder) => {
+        builder.scoped();
+    },
+    transient: (builder) => {
+        builder.transient();
+    },
+};
+// ── DefaultContainer ─────────────────────────────────────────────────────────────────────────────────────────────────
 class DefaultContainer {
     #disposed = false;
+    // The one teardown run — every dispose() call returns it once it exists.
+    #disposePromise;
     #registry;
     #scope;
     #lifecycle;
@@ -31,12 +48,12 @@ class DefaultContainer {
     #moduleBindingIds;
     // One shared registration for every chain this container's own `bind()` creates.
     #registration;
-    constructor(parent) {
+    constructor(parent, options) {
         this.#parent = parent;
         this.#registry = new BindingRegistry();
         this.#scope = new ScopeManager(parent !== undefined);
         this.#lifecycle = new LifecycleManager();
-        this.#initResolver();
+        this.#initResolver(options?.metadataReader);
     }
     #getInspector() {
         return (this.#inspector ??= new Inspector(this.#registry, this.#scope, this.#parent !== undefined, () => this.#disposed));
@@ -49,54 +66,59 @@ class DefaultContainer {
         if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
             builtSubsystems.push("container.moduleTables");
         }
-        if (this.#registry.isBuilt) {
+        if (this.#registry.isNamedIndexBuilt) {
             builtSubsystems.push("registry.namedIndex");
         }
-        if (this.#scope.isBuilt) {
+        if (this.#registry.isTaggedIndexBuilt) {
+            builtSubsystems.push("registry.taggedIndex");
+        }
+        if (this.#scope.isScopedCacheBuilt) {
             builtSubsystems.push("scope.scoped");
         }
-        if (this.#lifecycle.isBuilt) {
+        if (this.#lifecycle.isActivationTableBuilt) {
             builtSubsystems.push("lifecycle.activationHooks");
         }
         return { ...this.#resolver.describeCaches(), scopedInstanceCount: this.#scope.scopedCount, builtSubsystems };
     }
-    #initResolver() {
-        const metadataReader = this.#getMetadataReader();
-        const parentResolver = this.#parent === undefined ? undefined : this.#parent.#resolver;
+    #initResolver(configuredReader) {
+        const parent = this.#parent;
+        const metadataReader = verifyingMetadataReader(configuredReader ?? (parent === undefined ? defaultMetadataReader : parent.#readerForChild()));
+        const parentResolver = parent === undefined ? undefined : parent.#resolver;
         this.#resolver = new DependencyResolver(this.#registry, this.#scope, this.#lifecycle, metadataReader, this, parentResolver);
     }
-    #getMetadataReader() {
-        // Check if a custom MetadataReader has been bound
-        const metaBindings = this.#registry.getAll(MetadataReaderToken);
-        if (metaBindings.length > 0) {
+    /** What a container being constructed under this one inherits: a reader bound here, else this one's. */
+    #readerForChild() {
+        if (this.#registry.getAll(MetadataReaderToken).length > 0) {
             try {
-                return this.#resolver.resolve(MetadataReaderToken, undefined, [], []);
+                return this.#resolver.resolve(MetadataReaderToken, undefined, []);
             }
             catch {
-                // fall through to default
+                // An unresolvable reader binding is not worth failing a child over.
             }
         }
-        if (this.#parent !== undefined) {
-            return this.#parent.#getMetadataReader();
-        }
-        return defaultMetadataReader;
+        return this.#resolver.metadataReader;
+    }
+    /** One reader per container, fixed when its resolver was built — so every path agrees on it. */
+    #getMetadataReader() {
+        return this.#resolver.metadataReader;
     }
     get isDisposed() {
         return this.#disposed;
     }
-    // ── Binding ──────────────────────────────────────────────────────────────
+    // ── Binding ────────────────────────────────────────────────────────────────────────────────────────────────────────
     bind(token) {
         this.#assertNotDisposed();
         return this.#createBindToBuilder(token);
     }
     /** The registration every non-module chain shares, so `bind()` allocates only the builder. */
     #ownRegistration() {
-        return (this.#registration ??= { registry: this.#registry, moduleBindingIds: undefined });
+        return (this.#registration ??= { registry: this.#registry, scope: this.#scope, moduleBindingIds: undefined });
     }
     /** One registration per module load, holding that module's id list directly. */
     #moduleRegistration(moduleRef) {
         return {
             registry: this.#registry,
+            scope: this.#scope,
             moduleBindingIds: (this.#moduleBindingIds ??= new Map()).getOrInsert(moduleRef, []),
         };
     }
@@ -117,7 +139,7 @@ class DefaultContainer {
         // re-index the token's binding list once per binding.
         return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
     }
-    /** Drain scope entries for already-removed bindings; only singletons yield deactivation pairs. */
+    /** Drain scope entries for already-removed bindings, and pair each one that still owes a deactivation. */
     #drainSingletons(bindings) {
         const pairs = [];
         for (const binding of bindings) {
@@ -125,36 +147,71 @@ class DefaultContainer {
                 pairs.push([binding, binding.instance]);
                 this.#scope.deleteSingleton(binding);
             }
+            else if (this.#owesConstantDeactivation(binding)) {
+                pairs.push([binding, binding.value]);
+            }
             this.#scope.deleteScoped(binding.id);
         }
         return pairs;
     }
-    #unbindSync(tokenOrId) {
+    /**
+     * Whether a constant still owes its deactivation.
+     *
+     * @remarks A constant's value is handed in at bind time rather than built on demand, so its hook is
+     * owed whether or not anything ever resolved it. Callers check `instance` first: a constant that
+     * carries one was cached through activation and is deactivated with that value instead.
+     */
+    #owesConstantDeactivation(binding) {
+        return (binding.kind === "constant" &&
+            (binding.onDeactivation !== undefined || this.#lifecycle.hasDeactivationHandlers(binding.token)));
+    }
+    /** Runs every pair's deactivation even when one throws, then reports what threw. */
+    #deactivatePairsSync(pairs) {
+        if (pairs.length === 0) {
+            return;
+        }
         const reader = this.#getMetadataReader();
-        for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
-            this.#lifecycle.runDeactivationSync(binding, instance, reader);
+        const errors = [];
+        for (const [binding, instance] of pairs) {
+            try {
+                this.#lifecycle.runDeactivationSync(binding, instance, reader);
+            }
+            catch (error) {
+                errors.push(error);
+            }
         }
+        throwCollected(errors, "unbind completed, but deactivation hooks threw");
     }
-    async unbindAsync(tokenOrId) {
-        this.#assertNotDisposed();
+    async #deactivatePairs(pairs) {
+        if (pairs.length === 0) {
+            return;
+        }
         const reader = this.#getMetadataReader();
-        for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
-            await this.#lifecycle.runDeactivation(binding, instance, reader);
+        const errors = [];
+        for (const [binding, instance] of pairs) {
+            try {
+                await this.#lifecycle.runDeactivation(binding, instance, reader);
+            }
+            catch (error) {
+                errors.push(error);
+            }
         }
+        throwCollected(errors, "unbind completed, but deactivation hooks threw");
+    }
+    #unbindSync(tokenOrId) {
+        this.#deactivatePairsSync(this.#collectDeactivationPairs(tokenOrId));
+    }
+    async unbindAsync(tokenOrId) {
+        this.#assertNotDisposed();
+        await this.#deactivatePairs(this.#collectDeactivationPairs(tokenOrId));
     }
     unbindAll() {
         this.#assertNotDisposed();
-        const reader = this.#getMetadataReader();
-        for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
-            this.#lifecycle.runDeactivationSync(binding, instance, reader);
-        }
+        this.#deactivatePairsSync(this.#drainSingletons(this.#registry.clear()));
     }
     async unbindAllAsync() {
         this.#assertNotDisposed();
-        const reader = this.#getMetadataReader();
-        for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
-            await this.#lifecycle.runDeactivation(binding, instance, reader);
-        }
+        await this.#deactivatePairs(this.#drainSingletons(this.#registry.clear()));
     }
     rebind(token) {
         this.#assertNotDisposed();
@@ -165,7 +222,7 @@ class DefaultContainer {
         this.#unbindSync(token);
         return this.#createBindToBuilder(token);
     }
-    // ── Module ────────────────────────────────────────────────────────────────
+    // ── Module ─────────────────────────────────────────────────────────────────────────────────────────────────────────
     load(...modules) {
         this.#assertNotDisposed();
         this.#loadSyncModules(modules);
@@ -186,15 +243,42 @@ class DefaultContainer {
             }
             moduleRefs.set(moduleRef, 1);
             const builder = this.#createModuleBuilder(moduleRef);
-            module[MODULE_SETUP](builder);
+            try {
+                module[MODULE_SETUP](builder);
+            }
+            catch (error) {
+                throw this.#rollbackFailedLoadSync(moduleRef, error);
+            }
         }
     }
     async loadAsync(...modules) {
         this.#assertNotDisposed();
-        for (const module of modules) {
+        // Deduped by identity like the sync lane, so `loadAsync(m, m)` ref-counts once.
+        for (const module of new Set(modules)) {
             await this.#loadOneModuleAsync(module);
         }
     }
+    /** Undo a failed load — bindings registered before the throw and the ref-count both roll back. */
+    #rollbackFailedLoadSync(moduleRef, cause) {
+        const pairs = this.#removeModuleBindings(moduleRef);
+        try {
+            this.#deactivatePairsSync(pairs);
+        }
+        catch (rollbackError) {
+            return new AggregateError([cause, rollbackError], "module load failed, and rolling it back threw too");
+        }
+        return cause;
+    }
+    async #rollbackFailedLoad(moduleRef, cause) {
+        const pairs = this.#removeModuleBindings(moduleRef);
+        try {
+            await this.#deactivatePairs(pairs);
+        }
+        catch (rollbackError) {
+            return new AggregateError([cause, rollbackError], "module load failed, and rolling it back threw too");
+        }
+        return cause;
+    }
     async #loadOneModuleAsync(module) {
         const moduleRef = module;
         const moduleRefs = (this.#moduleRefs ??= new Map());
@@ -206,15 +290,28 @@ class DefaultContainer {
         moduleRefs.set(moduleRef, 1);
         if (isSyncModule(module)) {
             const builder = this.#createModuleBuilder(moduleRef);
-            module[MODULE_SETUP](builder);
+            try {
+                module[MODULE_SETUP](builder);
+            }
+            catch (error) {
+                throw this.#rollbackFailedLoadSync(moduleRef, error);
+            }
         }
         else {
             const importPromises = [];
             const builder = this.#createAsyncModuleBuilder(moduleRef, importPromises);
-            await module[MODULE_SETUP](builder);
-            // Await nested async imports triggered inside the setup callback
-            if (importPromises.length > 0) {
-                await Promise.all(importPromises);
+            try {
+                await module[MODULE_SETUP](builder);
+                // Await nested async imports triggered inside the setup callback
+                if (importPromises.length > 0) {
+                    await Promise.all(importPromises);
+                }
+            }
+            catch (error) {
+                // Nested imports may still be registering — let them settle before rolling back, so no
+                // registration lands after the rejection and none becomes an unhandled rejection.
+                await Promise.allSettled(importPromises);
+                throw await this.#rollbackFailedLoad(moduleRef, error);
             }
         }
     }
@@ -249,27 +346,19 @@ class DefaultContainer {
         this.#moduleRefs?.delete(ref);
         const ids = this.#moduleBindingIds?.get(ref) ?? [];
         this.#moduleBindingIds?.delete(ref);
-        const pairs = [];
+        const removed = [];
         for (const id of ids) {
-            const binding = this.#registry.getById(id);
+            const binding = this.#registry.removeById(id);
             if (binding !== undefined) {
-                this.#registry.removeById(id);
-                if (binding.instance !== NO_INSTANCE) {
-                    pairs.push([binding, binding.instance]);
-                    this.#scope.deleteSingleton(binding);
-                }
-                this.#scope.deleteScoped(binding.id);
+                removed.push(binding);
             }
         }
-        return pairs;
+        return this.#drainSingletons(removed);
     }
     #unloadModuleSync(ref) {
         const count = this.#moduleRefs?.get(ref) ?? 0;
         if (count <= 1) {
-            const reader = this.#getMetadataReader();
-            for (const [binding, instance] of this.#removeModuleBindings(ref)) {
-                this.#lifecycle.runDeactivationSync(binding, instance, reader);
-            }
+            this.#deactivatePairsSync(this.#removeModuleBindings(ref));
         }
         else {
             this.#moduleRefs.set(ref, count - 1);
@@ -284,10 +373,7 @@ class DefaultContainer {
     async #unloadModuleAsync(ref) {
         const count = this.#moduleRefs?.get(ref) ?? 0;
         if (count <= 1) {
-            const reader = this.#getMetadataReader();
-            for (const [binding, instance] of this.#removeModuleBindings(ref)) {
-                await this.#lifecycle.runDeactivation(binding, instance, reader);
-            }
+            await this.#deactivatePairs(this.#removeModuleBindings(ref));
         }
         else {
             this.#moduleRefs.set(ref, count - 1);
@@ -297,21 +383,11 @@ class DefaultContainer {
         this.#assertNotDisposed();
         const entries = registry.entries();
         for (const { target, scope } of entries) {
-            const builder = this.#createBindToBuilder(target);
-            const bindingBuilder = builder.toSelf();
-            if (scope === "singleton") {
-                bindingBuilder.singleton();
-            }
-            else if (scope === "scoped") {
-                bindingBuilder.scoped();
-            }
-            else {
-                bindingBuilder.transient();
-            }
+            APPLY_BINDING_SCOPE[scope](this.#createBindToBuilder(target).toSelf());
         }
         return entries.length;
     }
-    // ── Lifecycle hooks ────────────────────────────────────────────────────────
+    // ── Lifecycle hooks ────────────────────────────────────────────────────────────────────────────────────────────────
     onActivation(token, handler) {
         this.#assertNotDisposed();
         this.#lifecycle.registerActivation(token, handler);
@@ -320,69 +396,97 @@ class DefaultContainer {
         this.#assertNotDisposed();
         this.#lifecycle.registerDeactivation(token, handler);
     }
-    // ── Resolution ────────────────────────────────────────────────────────────
+    // ── Resolution ─────────────────────────────────────────────────────────────────────────────────────────────────────
     resolve(token, options) {
         this.#assertNotDisposed();
         const rootStack = this.#resolver.rootStack;
-        // A resolve already holding the shared pair means this one is nested; it mints its own.
+        // A resolve already holding the shared stack means this one is nested; it mints its own.
         if (rootStack.length !== 0) {
             return options === undefined
-                ? this.#resolver.resolveFromContext(token, [], [])
-                : this.#resolver.resolve(token, options, [], []);
+                ? this.#resolver.resolveFromContext(token, [])
+                : this.#resolver.resolve(token, options, []);
         }
         if (options === undefined) {
-            return this.#resolver.resolveFromContext(token, this.#resolver.rootPath, rootStack);
+            return this.#resolver.resolveFromContext(token, rootStack);
         }
-        return this.#resolver.resolve(token, options, this.#resolver.rootPath, rootStack);
+        return this.#resolver.resolve(token, options, rootStack);
     }
     resolveAsync(token, options) {
         this.#assertNotDisposed();
         if (options === undefined) {
             return this.#resolver.resolveAsyncFromRoot(token);
         }
-        return this.#resolver.resolveAsync(token, options, [], [], ROOT_BRANCH);
+        return this.#resolver.resolveAsync(token, options, [], ROOT_BRANCH);
     }
     resolveOptional(token, options) {
         this.#assertNotDisposed();
         const rootStack = this.#resolver.rootStack;
         return rootStack.length === 0
-            ? this.#resolver.resolveOptional(token, options, this.#resolver.rootPath, rootStack)
-            : this.#resolver.resolveOptional(token, options, [], []);
+            ? this.#resolver.resolveOptional(token, options, rootStack)
+            : this.#resolver.resolveOptional(token, options, []);
     }
     resolveOptionalAsync(token, options) {
         this.#assertNotDisposed();
-        return this.#resolver.resolveOptionalAsync(token, options, [], [], ROOT_BRANCH);
+        return this.#resolver.resolveOptionalAsync(token, options, [], ROOT_BRANCH);
     }
     resolveAll(token, options) {
         this.#assertNotDisposed();
         const rootStack = this.#resolver.rootStack;
         return rootStack.length === 0
-            ? this.#resolver.resolveAll(token, options, this.#resolver.rootPath, rootStack)
-            : this.#resolver.resolveAll(token, options, [], []);
+            ? this.#resolver.resolveAll(token, options, rootStack)
+            : this.#resolver.resolveAll(token, options, []);
     }
     resolveAllAsync(token, options) {
         this.#assertNotDisposed();
-        return this.#resolver.resolveAllAsync(token, options, [], [], ROOT_BRANCH);
+        return this.#resolver.resolveAllAsync(token, options, [], ROOT_BRANCH);
     }
-    // ── Child ─────────────────────────────────────────────────────────────────
+    // ── Child ──────────────────────────────────────────────────────────────────────────────────────────────────────────
     createChild() {
         this.#assertNotDisposed();
         return new DefaultContainer(this);
     }
-    // ── Dispose ───────────────────────────────────────────────────────────────
-    async dispose() {
-        if (this.#disposed) {
-            return;
-        }
+    // ── Dispose ────────────────────────────────────────────────────────────────────────────────────────────────────────
+    dispose() {
+        // One teardown, shared: a second caller awaits the same run instead of returning early while
+        // hooks from the first are still executing.
+        return (this.#disposePromise ??= this.#runDispose());
+    }
+    async #runDispose() {
         this.#disposed = true;
-        // Deactivate all singletons in this container (own only)
+        // Refuses new materializations immediately; in-flight ones are drained just below.
+        this.#scope.markClosed();
+        await this.#scope.settleInflight();
         const reader = this.#getMetadataReader();
+        const errors = [];
         // Iterate a copy: a deactivation handler is user code, and the live list is what
-        // materializing or dropping a singleton mutates.
-        for (const binding of this.#scope.cachedSingletons().slice()) {
-            await this.#lifecycle.runDeactivation(binding, binding.instance, reader);
+        // materializing or dropping a singleton mutates. Reverse materialization order, so a
+        // dependent tears down before the dependencies it may still reach through.
+        const cached = this.#scope.cachedSingletons().slice();
+        for (let index = cached.length - 1; index >= 0; index -= 1) {
+            const binding = cached[index];
+            try {
+                await this.#lifecycle.runDeactivation(binding, binding.instance, reader);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        // A constant never reaches the singleton cache unless activation put it there, so its hook is
+        // owed from the registry instead — and only a container that has held one pays for looking.
+        if (this.#registry.hasHeldConstantBinding) {
+            for (const binding of this.#registry.allBindings()) {
+                if (binding.instance === NO_INSTANCE && this.#owesConstantDeactivation(binding)) {
+                    try {
+                        await this.#lifecycle.runDeactivation(binding, binding.value, reader);
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                }
+            }
         }
         this.#scope.clearAll();
+        throwCollected(errors, "dispose() completed, but deactivation hooks threw");
     }
     [Symbol.asyncDispose]() {
         return this.dispose();
@@ -390,7 +494,7 @@ class DefaultContainer {
     [Symbol.dispose]() {
         throw new SyncDisposalNotSupportedError();
     }
-    // ── Initialization ────────────────────────────────────────────────────────
+    // ── Initialization ─────────────────────────────────────────────────────────────────────────────────────────────────
     async initializeAsync() {
         this.#assertNotDisposed();
         const allBindings = this.#registry.allBindings();
@@ -403,8 +507,11 @@ class DefaultContainer {
                 if (binding.predicate !== undefined) {
                     continue;
                 }
-                // Has activation — need to resolve
-                if (binding.kind === "constant" && binding.onActivation === undefined) {
+                // A constant is already its own instance, so only an activation hook gives the warm-up
+                // something to run — and a container-level hook counts as one just as a per-binding hook does.
+                if (binding.kind === "constant" &&
+                    binding.onActivation === undefined &&
+                    !this.#lifecycle.hasActivationHandlers(binding.token)) {
                     continue;
                 }
                 const slotOptions = bindingSlotToResolveOptions(binding.slot);
@@ -412,7 +519,7 @@ class DefaultContainer {
             }
         }
     }
-    // ── Validate ──────────────────────────────────────────────────────────────
+    // ── Validate ───────────────────────────────────────────────────────────────────────────────────────────────────────
     validate() {
         this.#assertNotDisposed();
         const reader = this.#getMetadataReader();
@@ -423,6 +530,48 @@ class DefaultContainer {
             }
             this.#validateSingletonBindingGraph(binding, reader);
         }
+        for (const [hookToken, phase] of this.#lifecycle.hookedTokens()) {
+            if (!this.#isBoundInChain(hookToken)) {
+                throw new UnreachableLifecycleHookError(tokenName(hookToken), phase);
+            }
+        }
+        this.#validateConstraintRequirements(allBindings);
+    }
+    /** A constraint waiting on a slot name no binding declares can never hold. */
+    #validateConstraintRequirements(allBindings) {
+        let declaredSlotNames;
+        for (const binding of allBindings) {
+            const { predicate } = binding;
+            if (predicate === undefined) {
+                continue;
+            }
+            const requirement = constraintRequirementOf(predicate);
+            if (requirement === undefined) {
+                continue;
+            }
+            declaredSlotNames ??= this.#slotNamesInChain();
+            if (!declaredSlotNames.has(requirement.name)) {
+                throw new UnreachableConstraintError(tokenName(binding.token), requirement.name, requirement.helperName);
+            }
+        }
+    }
+    /** Every slot name declared anywhere a resolve through this container could reach. */
+    #slotNamesInChain() {
+        const names = this.#parent === undefined ? new Set() : this.#parent.#slotNamesInChain();
+        for (const binding of this.#registry.allBindings()) {
+            if (binding.slot.name !== undefined) {
+                names.add(binding.slot.name);
+            }
+        }
+        return names;
+    }
+    // Ancestors count: a parent-owned binding is one this container can still resolve through.
+    #isBoundInChain(token) {
+        if (this.#registry.has(token)) {
+            return true;
+        }
+        const parent = this.#parent;
+        return parent !== undefined && parent.#isBoundInChain(token);
     }
     #isSingletonStaticAnalyzableBinding(binding) {
         if (effectiveBindingScope(binding) !== "singleton") {
@@ -432,7 +581,7 @@ class DefaultContainer {
     }
     /**
      * DFS over explicit constructor / `toResolved*` dependency edges. Follows `toAlias` chains to the
-     * terminal binding for scope checks (SPEC §6.9).
+     * terminal binding for scope checks.
      *
      * @remarks A `toDynamic*` dependency is scope-checked like any other — its declared scope is what
      * makes it captive — but the DFS does not descend into the factory, whose body is opaque.
@@ -531,7 +680,7 @@ class DefaultContainer {
         }
         return edges;
     }
-    // ── Introspection ─────────────────────────────────────────────────────────
+    // ── Introspection ──────────────────────────────────────────────────────────────────────────────────────────────────
     has(token, options) {
         this.#assertNotDisposed();
         return this.#getInspector().has(token, options, () => this.#parent?.has(token, options) ?? false);
@@ -552,21 +701,33 @@ class DefaultContainer {
         this.#assertNotDisposed();
         return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, this.#parent === undefined ? undefined : this.#parent.#registry);
     }
-    // ── Internal ──────────────────────────────────────────────────────────────
+    // ── Internal ───────────────────────────────────────────────────────────────────────────────────────────────────────
     #assertNotDisposed() {
         if (this.#disposed) {
             throw new DisposedContainerError();
         }
     }
 }
-// ── Container static ──────────────────────────────────────────────────────────
+/** Reports collected hook failures once teardown finished: the one error as itself, several aggregated. */
+function throwCollected(errors, message) {
+    if (errors.length === 0) {
+        return;
+    }
+    if (errors.length === 1) {
+        throw errors[0];
+    }
+    throw new AggregateError(errors, message);
+}
+// ── Container static ─────────────────────────────────────────────────────────────────────────────────────────────────
 /**
  * @since 0.3.16-canary.0
  */
 export const Container = {
-    create() {
-        return new DefaultContainer();
+    create(options) {
+        return new DefaultContainer(undefined, options);
     },
+    // Variadic modules leave no room for an options argument. A container that needs both is
+    // `Container.create(options)` followed by `load(...)`, which is what these two do anyway.
     fromModules(...modules) {
         const container = new DefaultContainer();
         container.load(...modules);