@codefast/di 0.10.1 → 0.12.0

package/dist/container/container.js

@@ -1,22 +1,23 @@
-import { BindingChain } from "#container/binding-builders";
-import { NO_INSTANCE } from "#core/binding";
-import { effectiveBindingScope } from "#core/binding-scope";
+import { BindingChain } from "#container/binding-chain";
+import { effectiveBindingScope, NO_INSTANCE } from "#core/binding";
 import { constraintRequirementsOf } from "#core/constraint-requirement";
 import { getOrInsert, getOrInsertComputed } from "#core/map-upsert";
 import { isSyncModule, MODULE_SETUP } from "#core/module";
 import { BindingRegistry } from "#core/registry";
+import { advanceDisposeEpoch, disposeEpochRef } from "#core/state-epoch";
 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 { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#injection/dependency-slot";
 import { buildDependencyGraph } from "#introspection/dependency-graph";
+import { RESOLUTION_DIAGNOSTICS } from "#introspection/diagnostics";
+import { explainRequest } from "#introspection/explanation";
 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 { verifyingMetadataReader } from "#metadata/verifying-metadata-reader";
-import { ROOT_BRANCH } from "#resolution/path/resolution-path";
+import { LifecycleManager } from "#lifecycle/hooks";
+import { ScopeManager } from "#lifecycle/scopes";
+import { MetadataReaderToken } from "#metadata/reader-token";
+import { defaultMetadataReader } from "#metadata/symbol-reader";
+import { verifyingMetadataReader } from "#metadata/verifying-reader";
+import { ROOT_BRANCH } from "#resolution/path";
 import { DependencyResolver } from "#resolution/resolver";
 /** Whether a requirement's name is declared — on its token when it names one, on any token otherwise. */
 function isSlotNameDeclared(declared, requirement) {
@@ -49,12 +50,17 @@ const NO_DEACTIVATION_PAIRS = Object.freeze([]);
 // ── DefaultContainer ─────────────────────────────────────────────────────────────────────────────────────────────────
 class DefaultContainer {
     #disposed = false;
+    // The dispose epoch at which this child's chain was last confirmed live. Every dispose anywhere
+    // bumps the epoch, so an unchanged epoch means no ancestor closed since — the chain needs no walk.
+    #liveGeneration = -1;
     // The one teardown run — every dispose() call returns it once it exists.
     #disposePromise;
     #registry;
     #scope;
     #lifecycle;
     #resolver;
+    // Whether the reader came from `ContainerOptions` here or on an ancestor, which no token binding may override.
+    #hasConfiguredReader = false;
     // Built on the first introspecting call — a container that only binds and resolves never needs it.
     #inspector;
     #parent;
@@ -62,9 +68,16 @@ class DefaultContainer {
     #moduleRefs;
     // Module bindings: module -> array of binding IDs registered by it
     #moduleBindingIds;
+    // Module imports: module -> the modules it imported, so unload decrements their ref-count too.
+    #moduleImports;
     // One shared registration for every chain this container's own `bind()` creates.
     #registration;
+    // Bindings a plain last-wins bind displaced with a teardown still owed, by id: an unbind of that id or an
+    // unload of its module drains it, and dispose runs a constant's hook, which neither the registry nor the cache holds.
+    #orphanedBindings;
     constructor(parent, options) {
+        // oxlint-disable-next-line typescript/unbound-method -- installed as this instance's own method, so `this` is it
+        this.resolve = parent === undefined ? DefaultContainer.#rootResolve : DefaultContainer.#childResolve;
         this.#parent = parent;
         this.#registry = new BindingRegistry();
         this.#scope = new ScopeManager(parent !== undefined);
@@ -80,7 +93,7 @@ class DefaultContainer {
         if (this.#inspector !== undefined) {
             builtSubsystems.push("container.inspector");
         }
-        if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
+        if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined || this.#moduleImports !== undefined) {
             builtSubsystems.push("container.moduleTables");
         }
         if (this.#registry.isRecordMapBuilt) {
@@ -103,13 +116,14 @@ class DefaultContainer {
     }
     #initResolver(configuredReader) {
         const parent = this.#parent;
+        this.#hasConfiguredReader = configuredReader !== undefined || (parent !== undefined && parent.#hasConfiguredReader);
         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);
     }
-    /** What a container being constructed under this one inherits: a reader bound here, else this one's. */
+    /** What a container being constructed under this one inherits: a configured reader, else one bound here, else this one's. */
     #readerForChild() {
-        if (this.#registry.has(MetadataReaderToken)) {
+        if (!this.#hasConfiguredReader && this.#registry.has(MetadataReaderToken)) {
             try {
                 return this.#resolver.resolve(MetadataReaderToken, undefined, []);
             }
@@ -124,7 +138,7 @@ class DefaultContainer {
         return this.#resolver.metadataReader;
     }
     get isDisposed() {
-        return this.#disposed;
+        return this.#isChainDisposed();
     }
     // ── Binding ────────────────────────────────────────────────────────────────────────────────────────────────────────
     bind(token) {
@@ -133,15 +147,36 @@ class DefaultContainer {
     }
     /** The registration every non-module chain shares, so `bind()` allocates only the builder. */
     #ownRegistration() {
-        return (this.#registration ??= { registry: this.#registry, scope: this.#scope, moduleBindingIds: undefined });
+        return (this.#registration ??= {
+            registry: this.#registry,
+            scope: this.#scope,
+            moduleBindingIds: undefined,
+            onDisplaced: (binding) => {
+                this.#recordDisplaced(binding);
+            },
+        });
     }
-    /** One registration per module load, holding that module's id list directly. */
+    // A displaced binding holding a cached instance or owing a constant's deactivation is remembered until
+    // dispose, an unbind of its id or its module's unload; every other displaced binding is dropped.
+    #recordDisplaced(binding) {
+        if (binding.instance !== NO_INSTANCE || this.#owesConstantDeactivation(binding)) {
+            (this.#orphanedBindings ??= new Map()).set(binding.identifier, binding);
+        }
+    }
+    /**
+     * One registration per module load, holding that module's id list directly.
+     *
+     * @remarks It borrows the container's own displacement callback, so a constant a module's bind
+     * displaces is kept for dispose exactly as one displaced by `bind()` is.
+     */
     #moduleRegistration(moduleRef) {
         this.#moduleBindingIds ??= new Map();
+        const { onDisplaced } = this.#ownRegistration();
         return {
             registry: this.#registry,
             scope: this.#scope,
             moduleBindingIds: getOrInsert(this.#moduleBindingIds, moduleRef, []),
+            onDisplaced,
         };
     }
     #createBindToBuilder(token, registration = this.#ownRegistration()) {
@@ -154,30 +189,43 @@ class DefaultContainer {
     /** Remove bindings from registry + scope and collect [binding, instance] pairs for deactivation. */
     #collectDeactivationPairs(tokenOrId) {
         if (typeof tokenOrId === "number") {
-            const binding = this.#registry.removeById(tokenOrId);
+            const binding = this.#registry.removeById(tokenOrId) ?? this.#retireNotLive(tokenOrId);
             return binding === undefined ? NO_DEACTIVATION_PAIRS : this.#drainSingletons([binding]);
         }
         // Dropping the whole token in one pass: removing each binding by id instead would re-scan and
         // re-index the token's binding list once per binding.
         return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
     }
+    /** Retires an id the registry no longer holds, returning the displaced binding still owed a teardown. */
+    #retireNotLive(id) {
+        const orphaned = this.#orphanedBindings?.get(id);
+        if (orphaned !== undefined) {
+            this.#orphanedBindings.delete(id);
+        }
+        return orphaned;
+    }
     /** Drain scope entries for already-removed bindings, and pair each one that still owes a deactivation. */
     #drainSingletons(bindings) {
-        // Allocated by the first pair owed: an unbind or rebind of a binding nothing ever cached — the
-        // hot-swap shape — owes no deactivation and hands the shared empty list back.
+        // One flat list, allocated by the first pair owed: an unbind or rebind of a binding nothing
+        // ever cached — the hot-swap shape — owes no deactivation and hands the shared empty list back.
         let pairs;
-        for (const binding of bindings) {
-            if (binding.instance !== NO_INSTANCE) {
-                (pairs ??= []).push([binding, binding.instance]);
-                this.#scope.deleteSingleton(binding);
-            }
-            else if (this.#owesConstantDeactivation(binding)) {
-                (pairs ??= []).push([binding, binding.value]);
-            }
-            this.#scope.deleteScoped(binding.identifier);
+        for (let index = 0; index < bindings.length; index += 1) {
+            pairs = this.#drainSingleton(bindings[index], pairs);
         }
         return pairs ?? NO_DEACTIVATION_PAIRS;
     }
+    /** One binding's share of {@link DefaultContainer.#drainSingletons}, allocating `pairs` on the first pair owed. */
+    #drainSingleton(binding, pairs) {
+        if (binding.instance !== NO_INSTANCE) {
+            (pairs ??= []).push(binding, binding.instance);
+            this.#scope.deleteSingleton(binding);
+        }
+        else if (this.#owesConstantDeactivation(binding)) {
+            (pairs ??= []).push(binding, binding.value);
+        }
+        this.#scope.deleteScoped(binding.scopedCacheKey);
+        return pairs;
+    }
     /**
      * Whether a constant still owes its deactivation.
      *
@@ -195,32 +243,38 @@ class DefaultContainer {
             return;
         }
         const reader = this.#getMetadataReader();
-        const errors = [];
-        for (const [binding, instance] of pairs) {
+        const lifecycle = this.#lifecycle;
+        let errors;
+        for (let index = 0; index < pairs.length; index += 2) {
             try {
-                this.#lifecycle.runDeactivationSync(binding, instance, reader);
+                lifecycle.runDeactivationSync(pairs[index], pairs[index + 1], reader);
             }
             catch (error) {
-                errors.push(error);
+                (errors ??= []).push(error);
             }
         }
-        throwCollected(errors, "unbind completed, but deactivation hooks threw");
+        if (errors !== undefined) {
+            throwCollected(errors, "unbind completed, but deactivation hooks threw");
+        }
     }
     async #deactivatePairs(pairs) {
         if (pairs.length === 0) {
             return;
         }
         const reader = this.#getMetadataReader();
-        const errors = [];
-        for (const [binding, instance] of pairs) {
+        const lifecycle = this.#lifecycle;
+        let errors;
+        for (let index = 0; index < pairs.length; index += 2) {
             try {
-                await this.#lifecycle.runDeactivation(binding, instance, reader);
+                await lifecycle.runDeactivation(pairs[index], pairs[index + 1], reader);
             }
             catch (error) {
-                errors.push(error);
+                (errors ??= []).push(error);
             }
         }
-        throwCollected(errors, "unbind completed, but deactivation hooks threw");
+        if (errors !== undefined) {
+            throwCollected(errors, "unbind completed, but deactivation hooks threw");
+        }
     }
     #unbindSync(tokenOrId) {
         this.#deactivatePairsSync(this.#collectDeactivationPairs(tokenOrId));
@@ -232,19 +286,50 @@ class DefaultContainer {
     unbindAll() {
         this.#assertNotDisposed();
         this.#deactivatePairsSync(this.#drainSingletons(this.#registry.clear()));
+        this.#resetModuleTables();
     }
     async unbindAllAsync() {
         this.#assertNotDisposed();
         await this.#deactivatePairs(this.#drainSingletons(this.#registry.clear()));
+        this.#resetModuleTables();
+    }
+    // Clearing the registry also clears module bookkeeping, so a later `load()` of the same module is
+    // not silently skipped as already-loaded. Run after deactivation so the module's hooks still fire.
+    #resetModuleTables() {
+        this.#moduleRefs = undefined;
+        this.#moduleBindingIds = undefined;
+        this.#moduleImports = undefined;
     }
     rebind(token) {
         this.#assertNotDisposed();
-        if (!this.#registry.has(token)) {
-            throw new RebindUnboundTokenError(tokenName(token));
-        }
-        // Unbind existing (sync — if async deactivation, will throw AsyncDeactivationError)
-        this.#unbindSync(token);
-        return this.#createBindToBuilder(token);
+        // A lone default binding that owes no deactivation is replaced by the new chain's own
+        // registration, so the swap unbinds nothing up front. Anything else is unbound first, so an
+        // async deactivation throws here — before a replacement exists — exactly as `unbind()` does.
+        const lone = this.#registry.getFastDefault(token);
+        if (lone === undefined || lone.instance !== NO_INSTANCE || this.#owesConstantDeactivation(lone)) {
+            if (!this.#registry.has(token)) {
+                throw new RebindUnboundTokenError(tokenName(token));
+            }
+            this.#unbindSync(token);
+            return this.#createBindToBuilder(token);
+        }
+        return new BindingChain(token, this.#rebindRegistration());
+    }
+    #displacingRegistration;
+    /** A registration whose displaced binding is deactivated on the spot instead of kept for dispose, for `rebind`. */
+    #rebindRegistration() {
+        return (this.#displacingRegistration ??= {
+            registry: this.#registry,
+            scope: this.#scope,
+            moduleBindingIds: undefined,
+            // One binding at a time, so the hot-swap rebind that owes nothing allocates nothing.
+            deactivateDisplaced: (binding) => {
+                const pairs = this.#drainSingleton(binding, undefined);
+                if (pairs !== undefined) {
+                    this.#deactivatePairsSync(pairs);
+                }
+            },
+        });
     }
     // ── Module ─────────────────────────────────────────────────────────────────────────────────────────────────────────
     load(...modules) {
@@ -266,14 +351,23 @@ class DefaultContainer {
                 continue;
             }
             moduleRefs.set(moduleRef, 1);
-            const builder = this.#createModuleBuilder(moduleRef);
-            try {
-                module[MODULE_SETUP](builder);
+            this.#applySyncModule(module, moduleRef);
+        }
+    }
+    /** Runs a sync module's setup, or files its declarations, rolling the load back if either throws. */
+    #applySyncModule(module, moduleRef) {
+        const setup = module[MODULE_SETUP];
+        try {
+            if (typeof setup === "function") {
+                setup(this.#createModuleBuilder(moduleRef));
             }
-            catch (error) {
-                throw this.#rollbackFailedLoadSync(moduleRef, error);
+            else {
+                BindingChain.registerDeclared(setup, this.#moduleRegistration(moduleRef));
             }
         }
+        catch (error) {
+            throw this.#rollbackFailedLoadSync(moduleRef, error);
+        }
     }
     async loadAsync(...modules) {
         this.#assertNotDisposed();
@@ -313,13 +407,7 @@ class DefaultContainer {
         }
         moduleRefs.set(moduleRef, 1);
         if (isSyncModule(module)) {
-            const builder = this.#createModuleBuilder(moduleRef);
-            try {
-                module[MODULE_SETUP](builder);
-            }
-            catch (error) {
-                throw this.#rollbackFailedLoadSync(moduleRef, error);
-            }
+            this.#applySyncModule(module, moduleRef);
         }
         else {
             const importPromises = [];
@@ -344,6 +432,7 @@ class DefaultContainer {
         return {
             bind: (token) => this.#createBindToBuilder(token, registration),
             import: (...modules) => {
+                this.#recordModuleImports(moduleRef, modules);
                 this.#loadSyncModules(modules);
             },
         };
@@ -353,12 +442,21 @@ class DefaultContainer {
         return {
             bind: (token) => this.#createBindToBuilder(token, registration),
             import: (...modules) => {
+                this.#recordModuleImports(moduleRef, modules);
                 for (const module of modules) {
                     importPromises.push(this.#loadOneModuleAsync(module));
                 }
             },
         };
     }
+    // Records that `moduleRef` imported each module, so unloading it later releases the reference the
+    // import took — otherwise an imported module's ref-count only ever climbs.
+    #recordModuleImports(moduleRef, modules) {
+        const list = getOrInsert((this.#moduleImports ??= new Map()), moduleRef, []);
+        for (const module of modules) {
+            list.push(module);
+        }
+    }
     unload(...modules) {
         this.#assertNotDisposed();
         for (const module of modules) {
@@ -368,11 +466,12 @@ class DefaultContainer {
     /** Unregister module bindings and collect [binding, instance] pairs for deactivation. */
     #removeModuleBindings(ref) {
         this.#moduleRefs?.delete(ref);
+        this.#moduleImports?.delete(ref);
         const ids = this.#moduleBindingIds?.get(ref) ?? [];
         this.#moduleBindingIds?.delete(ref);
         const removed = [];
         for (const id of ids) {
-            const binding = this.#registry.removeById(id);
+            const binding = this.#registry.removeById(id) ?? this.#retireNotLive(id);
             if (binding !== undefined) {
                 removed.push(binding);
             }
@@ -382,7 +481,15 @@ class DefaultContainer {
     #unloadModuleSync(ref) {
         const count = this.#moduleRefs?.get(ref) ?? 0;
         if (count <= 1) {
+            // Read the imports before removal clears them, then release each — a child only unbinds once
+            // its own ref-count reaches zero, mirroring the increment `import` took on load.
+            const imported = this.#moduleImports?.get(ref);
             this.#deactivatePairsSync(this.#removeModuleBindings(ref));
+            if (imported !== undefined) {
+                for (const child of imported) {
+                    this.#unloadModuleSync(child);
+                }
+            }
         }
         else {
             this.#moduleRefs.set(ref, count - 1);
@@ -397,7 +504,13 @@ class DefaultContainer {
     async #unloadModuleAsync(ref) {
         const count = this.#moduleRefs?.get(ref) ?? 0;
         if (count <= 1) {
+            const imported = this.#moduleImports?.get(ref);
             await this.#deactivatePairs(this.#removeModuleBindings(ref));
+            if (imported !== undefined) {
+                for (const child of imported) {
+                    await this.#unloadModuleAsync(child);
+                }
+            }
         }
         else {
             this.#moduleRefs.set(ref, count - 1);
@@ -420,9 +533,10 @@ class DefaultContainer {
         this.#assertNotDisposed();
         this.#lifecycle.registerDeactivation(token, handler);
     }
-    // ── Resolution ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    resolve(token, options) {
-        this.#assertNotDisposed();
+    static #rootResolve(token, options) {
+        if (this.#disposed) {
+            throw new DisposedContainerError();
+        }
         const rootStack = this.#resolver.rootStack;
         // A resolve already holding the shared stack means this one is nested; it mints its own.
         if (rootStack.length !== 0) {
@@ -435,8 +549,28 @@ class DefaultContainer {
         }
         return this.#resolver.resolve(token, options, rootStack);
     }
+    // The root's body again behind the child's check, so neither role's compiled resolve carries the other's path.
+    static #childResolve(token, options) {
+        this.#assertChainLive();
+        const rootStack = this.#resolver.rootStack;
+        if (rootStack.length !== 0) {
+            return options === undefined
+                ? this.#resolver.resolveFromContext(token, [])
+                : this.#resolver.resolve(token, options, []);
+        }
+        if (options === undefined) {
+            return this.#resolver.resolveFromContext(token, rootStack);
+        }
+        return this.#resolver.resolve(token, options, rootStack);
+    }
     resolveAsync(token, options) {
-        this.#assertNotDisposed();
+        // Not `async`: the guard's throw becomes the rejection this method promises.
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         if (options === undefined) {
             return this.#resolver.resolveAsyncFromRoot(token);
         }
@@ -450,7 +584,12 @@ class DefaultContainer {
             : this.#resolver.resolveOptional(token, options, []);
     }
     resolveOptionalAsync(token, options) {
-        this.#assertNotDisposed();
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         return this.#resolver.resolveOptionalAsync(token, options, [], ROOT_BRANCH);
     }
     resolveAll(token, options) {
@@ -464,7 +603,12 @@ class DefaultContainer {
             : this.#resolver.resolveAll(token, options, []);
     }
     resolveAllAsync(token, options) {
-        this.#assertNotDisposed();
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         if (options === undefined) {
             return this.#resolver.resolveRootCollectionAsync(token);
         }
@@ -473,7 +617,10 @@ class DefaultContainer {
     // ── Child ──────────────────────────────────────────────────────────────────────────────────────────────────────────
     createChild() {
         this.#assertNotDisposed();
-        return new DefaultContainer(this);
+        const child = new DefaultContainer(this);
+        // Born confirmed live: the parent's chain was checked just above, so the child's first read skips the walk.
+        child.#liveGeneration = disposeEpochRef.value;
+        return child;
     }
     // ── Dispose ────────────────────────────────────────────────────────────────────────────────────────────────────────
     dispose() {
@@ -485,6 +632,8 @@ class DefaultContainer {
         this.#disposed = true;
         // Refuses new materializations immediately; in-flight ones are drained just below.
         this.#scope.markClosed();
+        // Descendants read this to learn their chain closed — a resolve through a disposed ancestor is refused.
+        advanceDisposeEpoch();
         await this.#scope.settleInflight();
         const reader = this.#getMetadataReader();
         const errors = [];
@@ -515,6 +664,20 @@ class DefaultContainer {
                 }
             }
         }
+        // Constants a plain last-wins bind() displaced left the registry with their hook still owed; one
+        // whose activation cached an instance was drained above, so only the untouched ones remain.
+        if (this.#orphanedBindings !== undefined) {
+            for (const binding of this.#orphanedBindings.values()) {
+                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");
     }
@@ -566,6 +729,11 @@ class DefaultContainer {
             if (!this.#isBoundInChain(hookToken)) {
                 throw new UnreachableLifecycleHookError(tokenName(hookToken), phase);
             }
+            // A deactivation only ever runs for a singleton or constant, so a hook on a token whose every
+            // binding is scoped or transient can never fire — the builder blocks it, `container.onDeactivation` cannot.
+            if (phase === "onDeactivation" && !this.#hasDeactivatableBindingInChain(hookToken)) {
+                throw new UnreachableLifecycleHookError(tokenName(hookToken), phase, "no-deactivatable-binding");
+            }
         }
         this.#validateConstraintRequirements(allBindings);
     }
@@ -608,6 +776,16 @@ class DefaultContainer {
         const parent = this.#parent;
         return parent !== undefined && parent.#isBoundInChain(token);
     }
+    // Whether the token has a binding a deactivation hook can run for — a singleton or a constant.
+    #hasDeactivatableBindingInChain(token) {
+        for (const binding of this.#registry.getAll(token)) {
+            if (effectiveBindingScope(binding) === "singleton") {
+                return true;
+            }
+        }
+        const parent = this.#parent;
+        return parent !== undefined && parent.#hasDeactivatableBindingInChain(token);
+    }
     #isSingletonStaticAnalyzableBinding(binding) {
         if (effectiveBindingScope(binding) !== "singleton") {
             return false;
@@ -701,10 +879,7 @@ class DefaultContainer {
     #collectStaticDependencyEdges(binding, reader) {
         const edges = [];
         for (const dep of this.#staticDependencies(binding, reader)) {
-            // An optional dependency imposes no scope constraint: it may legitimately be absent.
-            if (dep.optional) {
-                continue;
-            }
+            // An optional dependency that is absent peeks no candidate; one that is bound is captured like any other.
             const depOptions = injectionSlotToResolveOptions(dep);
             for (const candidate of this.#peekDependencyCandidates(dep, depOptions)) {
                 const terminal = this.#followAliasChainToTerminal(candidate, depOptions);
@@ -718,7 +893,16 @@ class DefaultContainer {
     // ── Introspection ──────────────────────────────────────────────────────────────────────────────────────────────────
     has(token, options) {
         this.#assertNotDisposed();
-        return this.#getInspector().hasOwn(token, options) || (this.#parent?.has(token, options) ?? false);
+        return this.#hasInChain(token, options);
+    }
+    // Recurses through the parent's registry, not its public `has`, so a live child answers even when
+    // an ancestor is disposed — the disposed-guard belongs on the entry point, not every chain hop.
+    #hasInChain(token, options) {
+        if (this.#getInspector().hasOwn(token, options)) {
+            return true;
+        }
+        const parent = this.#parent;
+        return parent !== undefined && parent.#hasInChain(token, options);
     }
     hasOwn(token, options) {
         this.#assertNotDisposed();
@@ -732,15 +916,51 @@ class DefaultContainer {
         this.#assertNotDisposed();
         return this.#getInspector().inspect();
     }
+    explain(token, options) {
+        this.#assertNotDisposed();
+        return explainRequest([this.#registry, ...this.#ancestorRegistries()], token, options);
+    }
     generateDependencyGraph(options) {
         this.#assertNotDisposed();
-        return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, this.#parent === undefined ? undefined : this.#parent.#registry);
+        return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, this.#ancestorRegistries());
+    }
+    /** The registries above this container, nearest first — the order every chain walk reads them in. */
+    #ancestorRegistries() {
+        const registries = [];
+        for (let ancestor = this.#parent; ancestor !== undefined; ancestor = ancestor.#parent) {
+            registries.push(ancestor.#registry);
+        }
+        return registries;
     }
     // ── Internal ───────────────────────────────────────────────────────────────────────────────────────────────────────
+    // Two field reads and no epoch on a live root. This and `#assertChainLive` each stay under V8's small-function
+    // size, so every entry point inlines both outright; the walk and the throw sit in `#confirmChainLive`.
     #assertNotDisposed() {
-        if (this.#disposed) {
+        if (this.#disposed || this.#parent !== undefined) {
+            this.#assertChainLive();
+        }
+    }
+    // An unchanged dispose epoch means no container anywhere closed since this chain was last confirmed live;
+    // every dispose advances it, this container's own included, so a disposed container always reaches the walk.
+    #assertChainLive() {
+        if (disposeEpochRef.value !== this.#liveGeneration) {
+            this.#confirmChainLive();
+        }
+    }
+    #confirmChainLive() {
+        if (this.#isChainDisposed()) {
             throw new DisposedContainerError();
         }
+        this.#liveGeneration = disposeEpochRef.value;
+    }
+    // Whether this container or any ancestor is disposed — the plain walk, taken only on the cold refresh
+    // and by the `isDisposed` getter, so it needs no memo of its own.
+    #isChainDisposed() {
+        if (this.#disposed) {
+            return true;
+        }
+        const parent = this.#parent;
+        return parent !== undefined && parent.#isChainDisposed();
     }
 }
 /** Reports collected hook failures once teardown finished: the one error as itself, several aggregated. */