@codefast/di 0.5.0-canary.7 → 0.5.0-canary.9

package/src/container/container.ts

@@ -1,6 +1,7 @@
 import type { Binding, BindToBuilder } from "#/binding";
-import { bindingSlotEquals } from "#/binding";
-import { BindingEntry } from "#/container/binding-builders";
+import { NO_INSTANCE } from "#/binding";
+import type { BindingRegistration } from "#/container/binding-builders";
+import { BindingChain } from "#/container/binding-builders";
 import type { AutoRegisterRegistry } from "#/decorators/injectable";
 import {
   AsyncModuleLoadError,
@@ -23,7 +24,11 @@ import type { AsyncModuleBuilder } from "#/module";
 import { isSyncModule, MODULE_SETUP } from "#/module";
 import { BindingRegistry } from "#/registry";
 import { effectiveBindingScope } from "#/resolution/binding-scope";
+import type { ResolutionDiagnostics } from "#/resolution/diagnostics";
+import { RESOLUTION_DIAGNOSTICS } from "#/resolution/diagnostics";
 import { LifecycleManager } from "#/resolution/lifecycle";
+import { ROOT_BRANCH } from "#/resolution/resolution-path";
+import type { DependencySlot } from "#/resolution/resolve-options";
 import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
 import { DependencyResolver } from "#/resolution/resolver";
 import { ScopeManager } from "#/resolution/scope";
@@ -38,17 +43,6 @@ import type {
   ResolveOptions,
 } from "#/types";
 
-// True when re-adding `restored` would immediately be displaced again by `current`
-// (both slot-based with equal slots) — in that case the replacement was legitimate.
-function displacesRestoredBinding(current: Binding, restored: Binding): boolean {
-  const currentIsPurePredicate =
-    current.predicate !== undefined && current.slot.name === undefined && current.slot.tags.length === 0;
-  if (currentIsPurePredicate) {
-    return false;
-  }
-  return bindingSlotEquals(current.slot, restored.slot);
-}
-
 // ── Container interface ────────────────────────────────────────────────────────
 
 /**
@@ -119,23 +113,54 @@ class DefaultContainer implements Container {
   readonly #scope: ScopeManager;
   readonly #lifecycle: LifecycleManager;
   #resolver!: DependencyResolver;
-  readonly #inspector: Inspector;
+  // Built on the first introspecting call — a container that only binds and resolves never needs it.
+  #inspector: Inspector | undefined;
   readonly #parent: DefaultContainer | undefined;
 
-  // Module tracking: module -> ref count
-  readonly #moduleRefs = new Map<object, number>();
+  // Module tracking: module -> ref count. Both tables stay unallocated until a module is loaded.
+  #moduleRefs: Map<object, number> | undefined;
   // Module bindings: module -> array of binding IDs registered by it
-  readonly #moduleBindingIds = new Map<object, Array<BindingIdentifier>>();
+  #moduleBindingIds: Map<object, Array<BindingIdentifier>> | undefined;
+  // One shared registration for every chain this container's own `bind()` creates.
+  #registration: BindingRegistration | undefined;
 
   constructor(parent?: DefaultContainer) {
     this.#parent = parent;
     this.#registry = new BindingRegistry();
     this.#scope = new ScopeManager(parent !== undefined);
     this.#lifecycle = new LifecycleManager();
-    this.#inspector = new Inspector(this.#registry, this.#scope, parent !== undefined, () => this.#disposed);
     this.#initResolver();
   }
 
+  #getInspector(): Inspector {
+    return (this.#inspector ??= new Inspector(
+      this.#registry,
+      this.#scope,
+      this.#parent !== undefined,
+      () => this.#disposed,
+    ));
+  }
+
+  [RESOLUTION_DIAGNOSTICS](): ResolutionDiagnostics {
+    const builtSubsystems: Array<string> = [];
+    if (this.#inspector !== undefined) {
+      builtSubsystems.push("container.inspector");
+    }
+    if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
+      builtSubsystems.push("container.moduleTables");
+    }
+    if (this.#registry.isBuilt) {
+      builtSubsystems.push("registry.namedIndex");
+    }
+    if (this.#scope.isBuilt) {
+      builtSubsystems.push("scope.scoped");
+    }
+    if (this.#lifecycle.isBuilt) {
+      builtSubsystems.push("lifecycle.activationHooks");
+    }
+    return { ...this.#resolver.describeCaches(), scopedInstanceCount: this.#scope.scopedCount, builtSubsystems };
+  }
+
   #initResolver(): void {
     const metadataReader = this.#getMetadataReader();
     const parentResolver = this.#parent === undefined ? undefined : this.#parent.#resolver;
@@ -176,63 +201,24 @@ class DefaultContainer implements Container {
     return this.#createBindToBuilder(token);
   }
 
+  /** The registration every non-module chain shares, so `bind()` allocates only the builder. */
+  #ownRegistration(): BindingRegistration {
+    return (this.#registration ??= { registry: this.#registry, moduleBindingIds: undefined });
+  }
+
+  /** One registration per module load, holding that module's id list directly. */
+  #moduleRegistration(moduleRef: object): BindingRegistration {
+    return {
+      registry: this.#registry,
+      moduleBindingIds: (this.#moduleBindingIds ??= new Map()).getOrInsert(moduleRef, []),
+    };
+  }
+
   #createBindToBuilder<const Value>(
     token: Token<Value> | Constructor<Value>,
-    moduleRef?: object,
+    registration: BindingRegistration = this.#ownRegistration(),
   ): BindToBuilder<Value> {
-    const registry = this.#registry;
-    // Bindings displaced by this fluent chain's commits — each stays restorable
-    // until the chain settles on a shape that genuinely conflicts with it. A list,
-    // because one chain can displace several bindings (the default at an
-    // intermediate commit, then a named/tagged binding at the final one).
-    const displacedByChain: Array<Binding> = [];
-
-    const commitBinding = <BindingValue>(
-      binding: Binding<BindingValue>,
-      previousId?: BindingIdentifier,
-    ): BindingIdentifier => {
-      if (previousId !== undefined) {
-        registry.removeById(previousId);
-        if (moduleRef !== undefined) {
-          const ids = this.#moduleBindingIds.get(moduleRef);
-          if (ids !== undefined) {
-            const idx = ids.indexOf(previousId);
-            if (idx !== -1) {
-              ids.splice(idx, 1);
-            }
-          }
-        }
-      }
-      // The registry stores value-erased bindings — this is the single erasure point for the builder chain.
-      const displaced = registry.add(binding as Binding);
-      if (displaced !== undefined) {
-        // A fluent chain commits eagerly on each refinement, so an intermediate
-        // commit can displace a binding that the final shape would never conflict
-        // with. Remember it so a later re-commit that morphs away (named/tagged
-        // slot, pure predicate) can restore it.
-        displacedByChain.push(displaced);
-      }
-      if (previousId !== undefined && displacedByChain.length > 0) {
-        for (let index = displacedByChain.length - 1; index >= 0; index -= 1) {
-          const candidate = displacedByChain[index]!;
-          if (!displacesRestoredBinding(binding as Binding, candidate)) {
-            registry.add(candidate);
-            displacedByChain.splice(index, 1);
-          }
-        }
-      }
-      if (moduleRef !== undefined) {
-        let ids = this.#moduleBindingIds.get(moduleRef);
-        if (ids === undefined) {
-          ids = [];
-          this.#moduleBindingIds.set(moduleRef, ids);
-        }
-        ids.push(binding.id);
-      }
-      return binding.id;
-    };
-
-    return new BindingEntry<Value>(token, commitBinding);
+    return new BindingChain<Value>(token, registration);
   }
 
   unbind(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): void {
@@ -251,14 +237,15 @@ class DefaultContainer implements Container {
     return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
   }
 
-  /** Drain singleton scope entries for a set of already-removed bindings. */
+  /** Drain scope entries for already-removed bindings; only singletons yield deactivation pairs. */
   #drainSingletons(bindings: ReadonlyArray<Binding>): Array<[Binding, unknown]> {
     const pairs: Array<[Binding, unknown]> = [];
     for (const binding of bindings) {
-      if (this.#scope.hasSingleton(binding.id)) {
-        pairs.push([binding, this.#scope.getSingleton(binding.id)]);
-        this.#scope.deleteSingleton(binding.id);
+      if (binding.instance !== NO_INSTANCE) {
+        pairs.push([binding, binding.instance]);
+        this.#scope.deleteSingleton(binding);
       }
+      this.#scope.deleteScoped(binding.id);
     }
     return pairs;
   }
@@ -311,45 +298,26 @@ class DefaultContainer implements Container {
     this.#loadSyncModules(modules);
   }
 
-  #loadSyncModules(modules: Array<SyncModule>): void {
-    // Collect all modules in topological order (dedup by identity)
-    const toLoad = this.#collectModuleDeps(modules);
-    for (const module of toLoad) {
+  // Imports nested inside a module's setup re-enter here through the builder, so a module listed
+  // twice in one call is deduped by identity and the rest is ref-counting.
+  #loadSyncModules(modules: ReadonlyArray<SyncModule | AsyncModule>): void {
+    for (const module of new Set(modules)) {
       if (!isSyncModule(module)) {
         throw new AsyncModuleLoadError(module.name);
       }
       const moduleRef = module as object;
-      const existing = this.#moduleRefs.get(moduleRef);
+      const moduleRefs = (this.#moduleRefs ??= new Map());
+      const existing = moduleRefs.get(moduleRef);
       if (existing !== undefined) {
-        this.#moduleRefs.set(moduleRef, existing + 1);
+        moduleRefs.set(moduleRef, existing + 1);
         continue;
       }
-      this.#moduleRefs.set(moduleRef, 1);
+      moduleRefs.set(moduleRef, 1);
       const builder = this.#createModuleBuilder(moduleRef);
       module[MODULE_SETUP](builder);
     }
   }
 
-  #collectModuleDeps(modules: Array<SyncModule | AsyncModule>): Array<SyncModule | AsyncModule> {
-    const seen = new Set<object>();
-    const result: Array<SyncModule | AsyncModule> = [];
-
-    const visit = (module: SyncModule | AsyncModule): void => {
-      const moduleRef = module as object;
-      if (seen.has(moduleRef)) {
-        return;
-      }
-      seen.add(moduleRef);
-      // We'll collect deps during setup via the builder's import()
-      result.push(module);
-    };
-
-    for (const module of modules) {
-      visit(module);
-    }
-    return result;
-  }
-
   async loadAsync(...modules: Array<SyncModule | AsyncModule>): Promise<void> {
     this.#assertNotDisposed();
     for (const module of modules) {
@@ -359,12 +327,13 @@ class DefaultContainer implements Container {
 
   async #loadOneModuleAsync(module: SyncModule | AsyncModule): Promise<void> {
     const moduleRef = module as object;
-    const existing = this.#moduleRefs.get(moduleRef);
+    const moduleRefs = (this.#moduleRefs ??= new Map());
+    const existing = moduleRefs.get(moduleRef);
     if (existing !== undefined) {
-      this.#moduleRefs.set(moduleRef, existing + 1);
+      moduleRefs.set(moduleRef, existing + 1);
       return;
     }
-    this.#moduleRefs.set(moduleRef, 1);
+    moduleRefs.set(moduleRef, 1);
 
     if (isSyncModule(module)) {
       const builder = this.#createModuleBuilder(moduleRef);
@@ -381,9 +350,10 @@ class DefaultContainer implements Container {
   }
 
   #createModuleBuilder(moduleRef: object): ModuleBuilder {
+    const registration = this.#moduleRegistration(moduleRef);
     return {
       bind: <const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
-        this.#createBindToBuilder(token, moduleRef),
+        this.#createBindToBuilder(token, registration),
       import: (...modules: Array<SyncModule>): void => {
         this.#loadSyncModules(modules);
       },
@@ -391,9 +361,10 @@ class DefaultContainer implements Container {
   }
 
   #createAsyncModuleBuilder(moduleRef: object, importPromises: Array<Promise<void>>): AsyncModuleBuilder {
+    const registration = this.#moduleRegistration(moduleRef);
     return {
       bind: <const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value> =>
-        this.#createBindToBuilder(token, moduleRef),
+        this.#createBindToBuilder(token, registration),
       import: (...modules: Array<SyncModule | AsyncModule>): void => {
         for (const module of modules) {
           importPromises.push(this.#loadOneModuleAsync(module));
@@ -411,32 +382,33 @@ class DefaultContainer implements Container {
 
   /** Unregister module bindings and collect [binding, instance] pairs for deactivation. */
   #removeModuleBindings(ref: object): Array<[Binding, unknown]> {
-    this.#moduleRefs.delete(ref);
-    const ids = this.#moduleBindingIds.get(ref) ?? [];
-    this.#moduleBindingIds.delete(ref);
+    this.#moduleRefs?.delete(ref);
+    const ids = this.#moduleBindingIds?.get(ref) ?? [];
+    this.#moduleBindingIds?.delete(ref);
     const pairs: Array<[Binding, unknown]> = [];
     for (const id of ids) {
       const binding = this.#registry.getById(id);
       if (binding !== undefined) {
         this.#registry.removeById(id);
-        if (this.#scope.hasSingleton(id)) {
-          pairs.push([binding, this.#scope.getSingleton(id)]);
-          this.#scope.deleteSingleton(id);
+        if (binding.instance !== NO_INSTANCE) {
+          pairs.push([binding, binding.instance]);
+          this.#scope.deleteSingleton(binding);
         }
+        this.#scope.deleteScoped(binding.id);
       }
     }
     return pairs;
   }
 
   #unloadModuleSync(ref: object): void {
-    const count = this.#moduleRefs.get(ref) ?? 0;
+    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);
       }
     } else {
-      this.#moduleRefs.set(ref, count - 1);
+      this.#moduleRefs!.set(ref, count - 1);
     }
   }
 
@@ -448,14 +420,14 @@ class DefaultContainer implements Container {
   }
 
   async #unloadModuleAsync(ref: object): Promise<void> {
-    const count = this.#moduleRefs.get(ref) ?? 0;
+    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);
       }
     } else {
-      this.#moduleRefs.set(ref, count - 1);
+      this.#moduleRefs!.set(ref, count - 1);
     }
   }
 
@@ -492,23 +464,33 @@ class DefaultContainer implements Container {
 
   resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     this.#assertNotDisposed();
+    const rootStack = this.#resolver.rootStack;
+    // A resolve already holding the shared pair 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, [], []);
+    }
     if (options === undefined) {
-      return this.#resolver.resolveFromContext(token, [], []);
+      return this.#resolver.resolveFromContext(token, this.#resolver.rootPath, rootStack);
     }
-    return this.#resolver.resolve(token, options, [], []);
+    return this.#resolver.resolve(token, options, this.#resolver.rootPath, rootStack);
   }
 
   resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     this.#assertNotDisposed();
     if (options === undefined) {
-      return this.#resolver.resolveAsyncFromContext(token, [], []);
+      return this.#resolver.resolveAsyncFromRoot(token) as Promise<Value>;
     }
-    return this.#resolver.resolveAsync(token, options, [], []);
+    return this.#resolver.resolveAsync(token, options, [], [], ROOT_BRANCH);
   }
 
   resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
     this.#assertNotDisposed();
-    return this.#resolver.resolveOptional(token, options, [], []);
+    const rootStack = this.#resolver.rootStack;
+    return rootStack.length === 0
+      ? this.#resolver.resolveOptional(token, options, this.#resolver.rootPath, rootStack)
+      : this.#resolver.resolveOptional(token, options, [], []);
   }
 
   resolveOptionalAsync<const Value>(
@@ -516,12 +498,15 @@ class DefaultContainer implements Container {
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
     this.#assertNotDisposed();
-    return this.#resolver.resolveOptionalAsync(token, options, [], []);
+    return this.#resolver.resolveOptionalAsync(token, options, [], [], ROOT_BRANCH);
   }
 
   resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
     this.#assertNotDisposed();
-    return this.#resolver.resolveAll(token, options, [], []);
+    const rootStack = this.#resolver.rootStack;
+    return rootStack.length === 0
+      ? this.#resolver.resolveAll(token, options, this.#resolver.rootPath, rootStack)
+      : this.#resolver.resolveAll(token, options, [], []);
   }
 
   resolveAllAsync<const Value>(
@@ -529,7 +514,7 @@ class DefaultContainer implements Container {
     options?: ResolveOptions,
   ): Promise<Array<Value>> {
     this.#assertNotDisposed();
-    return this.#resolver.resolveAllAsync(token, options, [], []);
+    return this.#resolver.resolveAllAsync(token, options, [], [], ROOT_BRANCH);
   }
 
   // ── Child ─────────────────────────────────────────────────────────────────
@@ -549,11 +534,10 @@ class DefaultContainer implements Container {
 
     // Deactivate all singletons in this container (own only)
     const reader = this.#getMetadataReader();
-    for (const [id, instance] of this.#scope.getAllSingletons()) {
-      const binding = this.#registry.getById(id);
-      if (binding !== undefined) {
-        await this.#lifecycle.runDeactivation(binding, instance, reader);
-      }
+    // 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);
     }
 
     this.#scope.clearAll();
@@ -577,7 +561,7 @@ class DefaultContainer implements Container {
         continue;
       }
       const scope = effectiveBindingScope(binding);
-      if (scope === "singleton" && !this.#scope.hasSingleton(binding.id)) {
+      if (scope === "singleton" && binding.instance === NO_INSTANCE) {
         if (binding.predicate !== undefined) {
           continue;
         }
@@ -633,10 +617,7 @@ class DefaultContainer implements Container {
       for (const edge of this.#collectStaticDependencyEdges(current, reader)) {
         const { terminal, depTokenName } = edge;
         const depScope = this.#validationScopeFromTerminal(terminal);
-        if (depScope === "opaque") {
-          continue;
-        }
-        if (depScope === "scoped" || depScope === "transient") {
+        if (depScope !== "singleton") {
           throw new ScopeViolationError({
             consumerToken: rootName,
             consumerScope: "singleton",
@@ -654,27 +635,18 @@ class DefaultContainer implements Container {
     dfs(root, [rootName], new Set());
   }
 
-  #validationScopeFromTerminal(terminal: Binding): BindingScope | "opaque" {
-    switch (terminal.kind) {
-      case "constant":
-        return "singleton";
-      // A factory's *body* is not statically analyzable, but the scope it was bound with is
-      // declared like any other — so the captive-dependency check applies. The DFS below still
-      // refuses to descend into the factory; only this edge is judged.
-      case "dynamic":
-      case "dynamic-async":
-        return terminal.scope;
-      case "class":
-      case "resolved":
-      case "resolved-async":
-        return terminal.scope;
-      case "alias":
-        throw new InternalError("validate: expected terminal binding after alias resolution");
-      default: {
-        const exhaustive: never = terminal;
-        return exhaustive;
-      }
+  /**
+   * The scope this edge is judged against.
+   *
+   * @remarks A factory's *body* is not statically analyzable, but the scope it was bound with is
+   * declared like any other — so the captive-dependency check applies to it too. The DFS still
+   * refuses to descend into a factory; only the edge is judged.
+   */
+  #validationScopeFromTerminal(terminal: Binding): BindingScope {
+    if (terminal.kind === "alias") {
+      throw new InternalError("validate: expected terminal binding after alias resolution");
     }
+    return terminal.scope;
   }
 
   #followAliasChainToTerminal(binding: Binding, options: ResolveOptions | undefined): Binding | undefined {
@@ -698,75 +670,43 @@ class DefaultContainer implements Container {
     return current;
   }
 
+  /** What one dependency could resolve to: every candidate for `injectAll`, else at most one. */
+  #peekDependencyCandidates(dep: DependencySlot, options: ResolveOptions | undefined): ReadonlyArray<Binding> {
+    if (dep.multi) {
+      return this.#resolver.peekCandidateBindingsForValidate(dep.token, options);
+    }
+    const found = this.#resolver.peekBindingForValidate(dep.token, options);
+    return found === undefined ? [] : [found.binding];
+  }
+
+  /** What a binding declares up front — a class's params, a factory's descriptors, else nothing. */
+  #staticDependencies(binding: Binding, reader: MetadataReader): ReadonlyArray<DependencySlot> {
+    if (binding.kind === "class") {
+      return reader.getConstructorMetadata(binding.target as Constructor)?.params ?? [];
+    }
+    if (binding.kind === "resolved" || binding.kind === "resolved-async") {
+      return binding.deps;
+    }
+    return [];
+  }
+
   #collectStaticDependencyEdges(
     binding: Binding,
     reader: MetadataReader,
   ): Array<{ terminal: Binding; depTokenName: string }> {
     const edges: Array<{ terminal: Binding; depTokenName: string }> = [];
 
-    const pushTerminal = (terminal: Binding | undefined, displayName: string): void => {
-      if (terminal === undefined) {
-        return;
-      }
-      edges.push({ terminal, depTokenName: displayName });
-    };
-
-    if (binding.kind === "class") {
-      const meta = reader.getConstructorMetadata(binding.target as Constructor);
-      if (meta === undefined) {
-        return edges;
-      }
-      for (const param of meta.params) {
-        const paramOptions = injectionSlotToResolveOptions(param);
-        if (param.optional) {
-          continue;
-        }
-        const tokenRef = param.token;
-        if (param.multi) {
-          const candidates = this.#resolver.peekCandidateBindingsForValidate(tokenRef, paramOptions);
-          for (const cand of candidates) {
-            const term = this.#followAliasChainToTerminal(cand, paramOptions);
-            pushTerminal(term, term !== undefined ? tokenName(term.token as Token<unknown>) : "");
-          }
-          continue;
-        }
-        const found =
-          paramOptions === undefined
-            ? this.#resolver.peekBindingForValidate(tokenRef, undefined)
-            : this.#resolver.peekBindingForValidate(tokenRef, paramOptions);
-        if (found === undefined) {
-          continue;
-        }
-        const term = this.#followAliasChainToTerminal(found.binding, paramOptions);
-        pushTerminal(term, term !== undefined ? tokenName(term.token as Token<unknown>) : "");
+    for (const dep of this.#staticDependencies(binding, reader)) {
+      // An optional dependency imposes no scope constraint: it may legitimately be absent.
+      if (dep.optional) {
+        continue;
       }
-      return edges;
-    }
-
-    if (binding.kind === "resolved" || binding.kind === "resolved-async") {
-      for (const dep of binding.deps) {
-        const depOptions = injectionSlotToResolveOptions(dep);
-        if (dep.optional) {
-          continue;
-        }
-        const tokenRef = dep.token as Token<unknown> | Constructor;
-        if (dep.multi) {
-          const candidates = this.#resolver.peekCandidateBindingsForValidate(tokenRef, depOptions);
-          for (const cand of candidates) {
-            const term = this.#followAliasChainToTerminal(cand, depOptions);
-            pushTerminal(term, term !== undefined ? tokenName(term.token as Token<unknown>) : "");
-          }
-          continue;
-        }
-        const found =
-          depOptions === undefined
-            ? this.#resolver.peekBindingForValidate(tokenRef, undefined)
-            : this.#resolver.peekBindingForValidate(tokenRef, depOptions);
-        if (found === undefined) {
-          continue;
+      const depOptions = injectionSlotToResolveOptions(dep);
+      for (const candidate of this.#peekDependencyCandidates(dep, depOptions)) {
+        const terminal = this.#followAliasChainToTerminal(candidate, depOptions);
+        if (terminal !== undefined) {
+          edges.push({ terminal, depTokenName: tokenName(terminal.token as Token<unknown>) });
         }
-        const term = this.#followAliasChainToTerminal(found.binding, depOptions);
-        pushTerminal(term, term !== undefined ? tokenName(term.token as Token<unknown>) : "");
       }
     }
 
@@ -777,22 +717,22 @@ class DefaultContainer implements Container {
 
   has(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean {
     this.#assertNotDisposed();
-    return this.#inspector.has(token, options, () => this.#parent?.has(token, options) ?? false);
+    return this.#getInspector().has(token, options, () => this.#parent?.has(token, options) ?? false);
   }
 
   hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean {
     this.#assertNotDisposed();
-    return this.#inspector.hasOwn(token, options);
+    return this.#getInspector().hasOwn(token, options);
   }
 
   lookupBindings<const Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot> {
     this.#assertNotDisposed();
-    return this.#inspector.lookupBindings(token);
+    return this.#getInspector().lookupBindings(token);
   }
 
   inspect(): ContainerSnapshot {
     this.#assertNotDisposed();
-    return this.#inspector.inspect();
+    return this.#getInspector().inspect();
   }
 
   generateDependencyGraph(options?: GraphOptions): ContainerGraphJson {

package/src/decorators/inject.ts

@@ -34,10 +34,8 @@ export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<V
 /**
  * The value a factory receives for one declared dependency.
  *
- * @remarks `optional()` and `injectAll()` already fold their effect into the descriptor's own
- * type parameter — `InjectionDescriptor<Value | undefined>` and `InjectionDescriptor<Array<Value>>`
- * — so reading that parameter back is enough; bare tokens and constructors fall through to
- * {@link TokenValue}.
+ * @remarks `optional()` and `injectAll()` fold their effect into the descriptor's own type
+ * parameter, so reading it back is enough; bare tokens fall through to {@link TokenValue}.
  *
  * @since 0.5.0-canary.7
  */
@@ -195,7 +193,7 @@ export function inject<const Value>(
   }
   Object.defineProperties(decoratorFn, props);
 
-  return decoratorFn as unknown as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
+  return decoratorFn as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
 }
 
 // ── optional() ────────────────────────────────────────────────────────────────