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

package/src/resolution/resolver.ts

@@ -0,0 +1,1755 @@
+import type { Binding, BindingSlot } from "#/binding";
+import type { ConstructorInvocation } from "#/constructor-type";
+import type { Container } from "#/container/container";
+import type { InjectionDescriptor } from "#/decorators/inject";
+import {
+  AsyncActivationError,
+  AsyncResolutionError,
+  CircularDependencyError,
+  InternalError,
+  MissingMetadataError,
+  MissingScopeContextError,
+  NoMatchingBindingError,
+  TokenNotBoundError,
+} from "#/errors";
+import type { ConstructorMetadata, MetadataReader } from "#/metadata/metadata-types";
+import type { BindingRegistry } from "#/registry";
+import { selectAllBindings, selectBinding } from "#/resolution/binding-select";
+import type { ResolverCallbacks } from "#/resolution/environment";
+import { buildResolutionFrame, DefaultResolutionContext, runWithContainer } from "#/resolution/environment";
+import { InstantiationPlanCompiler, PLAN_RETRY } from "#/resolution/instantiation-plan";
+import type { LifecycleManager } from "#/resolution/lifecycle";
+import { enterResolutionPath, exitResolutionPath } from "#/resolution/resolution-path";
+import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
+import type { ScopeManager } from "#/resolution/scope";
+import { SINGLETON_MISS } from "#/resolution/scope";
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+import type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingScope,
+  BindingTag,
+  ConstraintContext,
+  Constructor,
+  ResolutionFrame,
+  ResolveOptions,
+} from "#/types";
+
+// Terminal result of the options-less lookup fast lane — alias hops already folded.
+interface DefaultLookupEntry {
+  readonly binding: Binding;
+  readonly owner: DependencyResolver;
+}
+
+// Fast-lane alias folding gives up past this many hops and defers to the resolve()
+// loop, whose Set-based traversal detects genuine cycles exactly (no arbitrary cap).
+const ALIAS_HOP_LIMIT = 32;
+
+type BindingWithScope = Binding & { scope: BindingScope };
+const EMPTY_STRING_LIST: ReadonlyArray<string> = [];
+const EMPTY_FRAME_LIST: ReadonlyArray<ResolutionFrame> = [];
+const ROOT_CONSTRAINT_CONTEXT = {
+  resolutionPath: EMPTY_STRING_LIST,
+  resolutionStack: EMPTY_FRAME_LIST,
+  parent: undefined,
+  ancestors: EMPTY_FRAME_LIST,
+  currentResolveOptions: undefined,
+};
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class DependencyResolver {
+  readonly #syncResolutionContextPool: Array<DefaultResolutionContext> = [];
+  // Cycle detection for the sync transient-dynamic lane lives on `binding.inFlight` — see the
+  // field's doc comment in binding.ts. It is an O(1) field read with no hashing, no path scan and
+  // no side table to allocate or grow, so the lane needs no depth split.
+  // Shared-context state for the async transient-dynamic lane.
+  //
+  // Every level of a SEQUENTIAL async chain shares the same resolutionPath and resolutionStack
+  // arrays (passed by reference through ctx.resolveAsync), and the context stores references
+  // rather than snapshots, so one DefaultResolutionContext can serve the whole chain — the arrays
+  // reflect the current state automatically as levels push and pop.
+  //
+  // #asyncChainCtx: the shared context, created on first use and reset at each new root call.
+  //   Inner levels of the same chain reuse it with zero setup.
+  // #asyncChainCtxPath: identity of the resolutionPath array owning the shared context — same
+  //   reference means an inner level of that chain, a different one means a concurrent chain
+  //   (e.g. Promise.all) which gets its own context instead.
+  // #asyncChainActiveLevels: active levels of the OWNING chain, so the path pointer is released
+  //   when the last one settles. Concurrent fallback calls are not counted.
+  //
+  // The method is NOT declared async: that would allocate an async state machine and an implicit
+  // promise per level, where a `.then(settle, settle)` side listener costs neither.
+  #asyncChainCtx: DefaultResolutionContext | undefined;
+  #asyncChainCtxPath: Array<string> | undefined;
+  #asyncChainActiveLevels = 0;
+  // Settle callback shared by every level of the owning async chain: all of them pop the same
+  // resolutionPath and decrement the same counter, so one closure serves the whole chain instead
+  // of allocating one per level (the async lane's dominant per-level allocation).
+  #asyncChainSettle: (() => void) | undefined;
+  readonly #classHasPostConstruct = new WeakMap<Constructor, boolean>();
+  readonly #classNeedsActiveContainer = new WeakMap<Constructor, boolean>();
+  readonly #classConstructorMetadata = new WeakMap<Constructor, ConstructorMetadata | null>();
+  readonly #activationNeedByBindingId = new Map<BindingIdentifier, boolean>();
+  #activationCacheVersion = -1;
+  // Options-less lookup memo across the parent chain: token → terminal {binding, owner}
+  // (alias hops folded). `null` = token must take the slow lookup path. Invalidated when
+  // any registry in the chain mutates (monotonic version sum).
+  readonly #defaultLookupByToken = new Map<Token<unknown> | Constructor, DefaultLookupEntry | null>();
+  #defaultLookupVersion = -1;
+  // Name-only lookup memo (token → name → entry) with the same chain-version
+  // invalidation. `null` = shape needs the full selection path.
+  readonly #namedLookupByToken = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry | null>>();
+  #namedLookupVersion = -1;
+  // Compiled transient-class plans (Dagger-style): a pure-static subgraph (class/constant/
+  // cached-singleton deps only) compiles once into a nested-constructor closure — cycle
+  // checking happens at compile time, so execution skips all per-resolve bookkeeping.
+  // `null` = binding is not plannable under the current versions.
+  readonly #classPlanByBindingId = new Map<BindingIdentifier, (() => unknown) | null>();
+  #classPlanRegistryVersion = -1;
+  #classPlanActivationVersion = -1;
+
+  readonly #registry: BindingRegistry;
+  readonly #scope: ScopeManager;
+  readonly #lifecycle: LifecycleManager;
+  readonly #metadataReader: MetadataReader;
+  readonly #container: Container;
+  readonly #parent: DependencyResolver | undefined;
+
+  constructor(
+    registry: BindingRegistry,
+    scope: ScopeManager,
+    lifecycle: LifecycleManager,
+    metadataReader: MetadataReader,
+    container: Container,
+    parent: DependencyResolver | undefined,
+  ) {
+    this.#registry = registry;
+    this.#scope = scope;
+    this.#lifecycle = lifecycle;
+    this.#metadataReader = metadataReader;
+    this.#container = container;
+    this.#parent = parent;
+  }
+
+  // ── Binding lookup ─────────────────────────────────────────────────────────
+
+  #findBinding(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): { binding: Binding; owner: DependencyResolver } | undefined {
+    if (options === undefined) {
+      const fastDefaultBinding = this.#registry.getFastDefault(token);
+      if (fastDefaultBinding !== undefined) {
+        return { binding: fastDefaultBinding, owner: this };
+      }
+    }
+
+    if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+      const namedBinding = this.#registry.getSimpleNamed(token, options.name);
+      if (
+        namedBinding !== undefined &&
+        this.#matchesBindingFast(namedBinding, options, resolutionPath, resolutionStack)
+      ) {
+        return { binding: namedBinding, owner: this };
+      }
+    }
+
+    if (
+      options !== undefined &&
+      options.name === undefined &&
+      options.tag === undefined &&
+      (options.tags?.length ?? 0) === 1
+    ) {
+      const [tagKey, tagValue] = options.tags![0]!;
+      const tagged = this.#registry.getSimpleTagged(token, tagKey, tagValue);
+      if (tagged !== undefined) {
+        return { binding: tagged, owner: this };
+      }
+    }
+
+    const bindings = this.#registry.getAll(token);
+    if (bindings.length > 0) {
+      if (bindings.length === 1) {
+        const onlyBinding = bindings[0]!;
+        const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
+        if (options === undefined && isDefaultSlot && onlyBinding.predicate === undefined) {
+          return { binding: onlyBinding, owner: this };
+        }
+        if (this.#matchesBindingFast(onlyBinding, options, resolutionPath, resolutionStack)) {
+          return { binding: onlyBinding, owner: this };
+        }
+      }
+      const ctx = this.#makeConstraintContext(resolutionPath, resolutionStack, options);
+      const binding = selectBinding(bindings, options, ctx, this.#getTokenName(token));
+      if (binding !== undefined) {
+        return { binding, owner: this };
+      }
+    }
+    if (this.#parent !== undefined) {
+      return this.#parent.#findBinding(token, options, resolutionPath, resolutionStack);
+    }
+    return undefined;
+  }
+
+  /**
+   * Binding lookup aligned with `resolve` — used by `Container.validate` without instantiating.
+   */
+  peekBindingForValidate(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions | undefined,
+  ): { binding: Binding; owner: DependencyResolver } | undefined {
+    return this.#findBinding(token, options, [], []);
+  }
+
+  /**
+   * Mirrors {@link DependencyResolver.resolveAll} candidate selection only (no instantiation).
+   */
+  peekCandidateBindingsForValidate(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions | undefined,
+  ): Array<Binding> {
+    if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+      return this.#getSimpleNamedBindingsFromChain(token, options.name);
+    }
+    const allBindings = this.#getAllBindingsFromChain(token);
+    if (allBindings.length === 0) {
+      return [];
+    }
+    const ctx = this.#makeConstraintContext([], [], options);
+    return selectAllBindings(allBindings, options, ctx);
+  }
+
+  // ── Sync resolve ───────────────────────────────────────────────────────────
+
+  resolveFromContext<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    // Hot lane: own-registry fast default. Fall back to the chain-versioned memo
+    // (parent-chain walk + alias folding) only on miss or alias.
+    const fastBinding = this.#registry.getFastDefault(token);
+    if (fastBinding !== undefined && fastBinding.kind !== "alias") {
+      return this.#resolveDefaultEntry<Value>(fastBinding, this, resolutionPath, resolutionStack);
+    }
+    const entry = this.#lookupDefaultEntry(token);
+    if (entry === null) {
+      return this.resolve(token, undefined, resolutionPath, resolutionStack);
+    }
+    return this.#resolveDefaultEntry<Value>(entry.binding, entry.owner, resolutionPath, resolutionStack);
+  }
+
+  #resolveDefaultEntry<const Value>(
+    binding: Binding,
+    owner: DependencyResolver,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))
+    ) {
+      return binding.value as Value;
+    }
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+    if (scope === "transient") {
+      if (binding.kind === "dynamic") {
+        const containerHooks =
+          this.#lifecycle.activationVersion === 0 ? undefined : this.#lifecycle.activationHandlersFor(binding.token);
+        if (binding.onActivation === undefined && (containerHooks === undefined || containerHooks.length === 0)) {
+          return this.#resolveTransientDynamicSyncFromContext(
+            binding as Binding<Value> & { kind: "dynamic" },
+            resolutionPath,
+            resolutionStack,
+          );
+        }
+        return this.#resolveTransientDynamicActivatedSync(
+          binding as Binding<Value> & { kind: "dynamic" },
+          containerHooks,
+          resolutionPath,
+          resolutionStack,
+        );
+      }
+      // Compiled plans only run at the top level — inner levels keep the runtime cycle guard.
+      if ((binding.kind === "class" || binding.kind === "resolved") && resolutionPath.length === 0) {
+        const plan = this.#getInstantiationPlan(binding);
+        if (plan !== null) {
+          return plan() as Value;
+        }
+      }
+    } else if (scope === "singleton") {
+      const cachedSingleton = owner.#scope.peekSingleton(binding.id);
+      if (cachedSingleton !== SINGLETON_MISS) {
+        return cachedSingleton as Value;
+      }
+      if (owner !== this) {
+        return owner.#resolveBinding(binding as Binding<Value>, undefined, resolutionPath, resolutionStack);
+      }
+    } else {
+      if (!this.#scope.isChild) {
+        throw new MissingScopeContextError(this.#getTokenName(binding.token));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return this.#scope.getScoped<Value>(binding.id);
+      }
+    }
+    return this.#resolveBinding(binding as Binding<Value>, undefined, resolutionPath, resolutionStack);
+  }
+
+  // Lean lane for an activated transient dynamic binding: same observable behavior as the
+  // generic #resolveBinding path (guard, frame, ctx, per-binding then container hooks) with
+  // the kind/activation dispatch resolved statically.
+  #resolveTransientDynamicActivatedSync<const Value>(
+    binding: Binding<Value> & { kind: "dynamic" },
+    containerHooks: ReadonlyArray<ActivationHandler<unknown>> | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    const frame = this.#getResolutionFrame(binding);
+    const tokenDisplayName = frame.tokenName;
+    const resolutionSet = enterResolutionPath(resolutionPath, tokenDisplayName, false);
+    resolutionStack.push(frame);
+    try {
+      const resolutionCtx = this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, undefined);
+      const factoryResult = binding.factory(resolutionCtx);
+      if (factoryResult instanceof Promise) {
+        throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+      }
+      let activated = factoryResult;
+      if (binding.onActivation !== undefined) {
+        const activationResult = binding.onActivation(resolutionCtx, activated);
+        if (activationResult instanceof Promise) {
+          throw new AsyncActivationError(tokenDisplayName, "onActivation");
+        }
+        activated = activationResult;
+      }
+      if (containerHooks !== undefined) {
+        for (let index = 0; index < containerHooks.length; index += 1) {
+          const activationResult = containerHooks[index]!(resolutionCtx, activated);
+          if (activationResult instanceof Promise) {
+            throw new AsyncActivationError(tokenDisplayName, "onActivation");
+          }
+          activated = activationResult as Value;
+        }
+      }
+      return activated;
+    } finally {
+      resolutionStack.pop();
+      resolutionPath.pop();
+      resolutionSet?.delete(tokenDisplayName);
+    }
+  }
+
+  #chainRegistryVersion(): number {
+    let version = this.#registry.version;
+    for (let resolver = this.#parent; resolver !== undefined; resolver = resolver.#parent) {
+      version += resolver.#registry.version;
+    }
+    return version;
+  }
+
+  #lookupDefaultEntry(token: Token<unknown> | Constructor): DefaultLookupEntry | null {
+    const version = this.#chainRegistryVersion();
+    if (version !== this.#defaultLookupVersion) {
+      this.#defaultLookupByToken.clear();
+      this.#defaultLookupVersion = version;
+    }
+    let entry = this.#defaultLookupByToken.get(token);
+    if (entry === undefined) {
+      entry = this.#computeDefaultEntry(token);
+      this.#defaultLookupByToken.set(token, entry);
+    }
+    return entry;
+  }
+
+  #computeDefaultEntry(token: Token<unknown> | Constructor): DefaultLookupEntry | null {
+    let current = token;
+    for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+      const entry = this.#findDefaultEntryInChain(current);
+      if (entry === null) {
+        return null;
+      }
+      if (entry.binding.kind === "alias") {
+        current = entry.binding.target;
+        continue;
+      }
+      return entry;
+    }
+    return null;
+  }
+
+  #lookupNamedEntry(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry | null {
+    const version = this.#chainRegistryVersion();
+    if (version !== this.#namedLookupVersion) {
+      this.#namedLookupByToken.clear();
+      this.#namedLookupVersion = version;
+    }
+    // ✓ TS6.0: Map.getOrInsert (ES2025)
+    const entriesByName = this.#namedLookupByToken.getOrInsert(token, new Map<string, DefaultLookupEntry | null>());
+    let entry = entriesByName.get(name);
+    if (entry === undefined) {
+      entry = this.#findNamedEntryInChain(token, name);
+      entriesByName.set(name, entry);
+    }
+    return entry;
+  }
+
+  #findNamedEntryInChain(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry | null {
+    const named = this.#registry.getSimpleNamed(token, name);
+    if (named !== undefined) {
+      // Predicates need a live context; aliases carry options through the full path.
+      if (named.predicate !== undefined || named.kind === "alias") {
+        return null;
+      }
+      return { binding: named, owner: this };
+    }
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findNamedEntryInChain(token, name);
+  }
+
+  #findDefaultEntryInChain(token: Token<unknown> | Constructor): DefaultLookupEntry | null {
+    const fast = this.#registry.getFastDefault(token);
+    if (fast !== undefined) {
+      return { binding: fast, owner: this };
+    }
+    // A level with non-fast bindings (multi-slot / predicate) needs full selection — bail.
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findDefaultEntryInChain(token);
+  }
+
+  #getInstantiationPlan(binding: Binding & { kind: "class" | "resolved" }): (() => unknown) | null {
+    const registryVersion = this.#chainRegistryVersion();
+    const activationVersion = this.#lifecycle.activationVersion;
+    if (registryVersion !== this.#classPlanRegistryVersion || activationVersion !== this.#classPlanActivationVersion) {
+      this.#classPlanByBindingId.clear();
+      this.#classPlanRegistryVersion = registryVersion;
+      this.#classPlanActivationVersion = activationVersion;
+    }
+    const cached = this.#classPlanByBindingId.get(binding.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const compiled = this.#planCompiler.compile(binding);
+    if (compiled === PLAN_RETRY) {
+      // Lifecycle metadata not discovered yet — the fallback resolve discovers it; retry then.
+      return null;
+    }
+    this.#classPlanByBindingId.set(binding.id, compiled);
+    return compiled;
+  }
+
+  // Compiler behind #getClassPlan — cold path, so the host indirection costs nothing hot.
+  readonly #planCompiler = new InstantiationPlanCompiler({
+    hasActivationHandlers: (token) => this.#lifecycle.hasActivationHandlers(token),
+    knownPostConstruct: (target) => this.#classHasPostConstruct.get(target),
+    needsActiveContainer: (target) => {
+      let needsActiveContainer = this.#classNeedsActiveContainer.get(target);
+      if (needsActiveContainer === undefined) {
+        const accessorMetadata = this.#metadataReader.getAccessorMetadata?.(target);
+        needsActiveContainer = (accessorMetadata?.length ?? 0) > 0;
+        this.#classNeedsActiveContainer.set(target, needsActiveContainer);
+      }
+      return needsActiveContainer;
+    },
+    getConstructorMetadata: (target) => this.#getConstructorMetadata(target),
+    lookupDependencyEntry: (token) => {
+      const entry = this.#lookupDefaultEntry(token);
+      return entry === null ? null : { binding: entry.binding, ownerScope: entry.owner.#scope };
+    },
+    resolveFallback: (token) => this.resolve(token, undefined, [], []),
+  });
+
+  resolve<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    // Name-only fast lane: memoized lookup, dispatching just the shapes whose
+    // semantics involve no resolution context (constants, cached singletons).
+    if (
+      options !== undefined &&
+      options.name !== undefined &&
+      options.tag === undefined &&
+      (options.tags === undefined || options.tags.length === 0)
+    ) {
+      const namedEntry = this.#lookupNamedEntry(token, options.name);
+      if (namedEntry !== null) {
+        const namedBinding = namedEntry.binding;
+        if (
+          namedBinding.kind === "constant" &&
+          namedBinding.onActivation === undefined &&
+          (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(namedBinding.token))
+        ) {
+          return namedBinding.value as Value;
+        }
+        const namedScope = (namedBinding as BindingWithScope).scope ?? "transient";
+        if (namedScope === "singleton") {
+          const cachedSingleton = namedEntry.owner.#scope.peekSingleton(namedBinding.id);
+          if (cachedSingleton !== SINGLETON_MISS) {
+            return cachedSingleton as Value;
+          }
+        }
+        // Everything else keeps the full path (context, activation, guards).
+      }
+    }
+
+    let currentToken: Token<unknown> | Constructor = token;
+    let visitedAliasTokens: Set<Token<unknown> | Constructor> | undefined;
+    let found = this.#findBinding(currentToken, options, resolutionPath, resolutionStack);
+
+    // Follow aliases iteratively with exact cycle detection — a revisited alias
+    // token throws CircularDependencyError instead of overflowing the call stack.
+    while (found !== undefined && found.binding.kind === "alias") {
+      const target = found.binding.target;
+      visitedAliasTokens ??= new Set([currentToken]);
+      if (visitedAliasTokens.has(target)) {
+        throw new CircularDependencyError([...visitedAliasTokens, target].map((entry) => tokenName(entry)));
+      }
+      visitedAliasTokens.add(target);
+      currentToken = target;
+      found = this.#findBinding(currentToken, options, resolutionPath, resolutionStack);
+    }
+
+    if (found === undefined) {
+      const ownBindings = this.#registry.getAll(currentToken);
+      if (ownBindings.length > 0) {
+        throw new NoMatchingBindingError(
+          this.#getTokenName(currentToken),
+          options ?? {},
+          this.#getAvailableSlots(currentToken),
+        );
+      }
+      throw new TokenNotBoundError(this.#getTokenName(currentToken));
+    }
+
+    const { binding, owner } = found;
+
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+
+    // Singleton from a parent resolver: delegate so the parent caches it correctly
+    if (scope === "singleton" && owner !== this) {
+      return owner.#resolveBinding(binding as Binding<Value>, options, resolutionPath, resolutionStack);
+    }
+
+    // Scoped/transient (or own singleton): resolve with this resolver's container/scope
+    return this.#resolveBinding(binding as Binding<Value>, options, resolutionPath, resolutionStack);
+  }
+
+  #resolveBinding<const Value>(
+    binding: Binding<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))
+    ) {
+      return binding.value;
+    }
+
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+
+    // Singleton cache check
+    if (scope === "singleton") {
+      if (this.#scope.hasSingleton(binding.id)) {
+        return this.#scope.getSingleton<Value>(binding.id);
+      }
+    }
+
+    // Scoped cache check
+    if (scope === "scoped") {
+      if (!this.#scope.isChild) {
+        throw new MissingScopeContextError(this.#getTokenName(binding.token));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return this.#scope.getScoped<Value>(binding.id);
+      }
+    }
+
+    const frame = this.#getResolutionFrame(binding);
+    const tokenDisplayName = frame.tokenName;
+    const resolutionSet = enterResolutionPath(resolutionPath, tokenDisplayName, false);
+    resolutionStack.push(frame);
+    const needsActivation = this.#needsActivation(binding);
+    if (!needsActivation && scope === "transient" && binding.kind === "dynamic") {
+      const resolutionCtx = this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, options);
+      try {
+        const dynamicResult = binding.factory(resolutionCtx);
+        if (dynamicResult instanceof Promise) {
+          throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+        }
+        resolutionStack.pop();
+        resolutionPath.pop();
+        resolutionSet?.delete(tokenDisplayName);
+        return dynamicResult;
+      } catch (error) {
+        resolutionStack.pop();
+        resolutionPath.pop();
+        resolutionSet?.delete(tokenDisplayName);
+        throw error;
+      }
+    }
+
+    try {
+      const needsResolutionContext = needsActivation || this.#requiresResolutionContext(binding);
+      const resolutionCtx = needsResolutionContext
+        ? this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, options)
+        : undefined;
+
+      const instance = this.#instantiateSync(binding, resolutionCtx, resolutionPath, resolutionStack);
+
+      const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+      const activated = shouldActivate
+        ? this.#lifecycle.runActivationSync(
+            resolutionCtx as DefaultResolutionContext,
+            binding,
+            instance,
+            this.#metadataReader,
+          )
+        : instance;
+
+      // Cache by scope
+      if (scope === "singleton") {
+        this.#scope.setSingleton(binding.id, activated);
+      } else if (scope === "scoped") {
+        this.#scope.setScoped(binding.id, activated);
+      }
+
+      return activated;
+    } finally {
+      resolutionStack.pop();
+      resolutionPath.pop();
+      resolutionSet?.delete(tokenDisplayName);
+    }
+  }
+
+  #instantiateSync<const Value>(
+    binding: Binding<Value>,
+    ctx: DefaultResolutionContext | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    switch (binding.kind) {
+      case "constant":
+        return binding.value;
+
+      case "dynamic": {
+        if (ctx === undefined) {
+          throw new InternalError("dynamic binding requires resolution context");
+        }
+        const factoryResult = binding.factory(ctx);
+        if (factoryResult instanceof Promise) {
+          throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+        }
+        return factoryResult;
+      }
+
+      case "dynamic-async":
+        throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+
+      case "class": {
+        const deps = this.#resolveClassDeps(binding.target, resolutionPath, resolutionStack);
+        const instance = this.#instantiateClass(binding.target, deps);
+        return instance as Value;
+      }
+
+      case "resolved": {
+        const deps = this.#resolveDescriptorDeps(binding.deps, resolutionPath, resolutionStack);
+        const factoryResult = binding.factory(...deps);
+        if (factoryResult instanceof Promise) {
+          throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+        }
+        return factoryResult;
+      }
+
+      case "resolved-async":
+        throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+
+      case "alias":
+        throw new InternalError("alias should have been followed before instantiation");
+    }
+  }
+
+  #resolveClassDeps(
+    target: Constructor,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Array<unknown> {
+    const meta = this.#getConstructorMetadata(target);
+    if (meta === undefined) {
+      if (target.length === 0) {
+        return [];
+      }
+      throw new MissingMetadataError(target.name);
+    }
+    if (meta.params.length === 0) {
+      return [];
+    }
+    if (meta.params.length === 1) {
+      const param = meta.params[0]!;
+      const paramOptions = injectionSlotToResolveOptions(param);
+      if (param.multi) {
+        return [this.resolveAll(param.token, paramOptions, resolutionPath, resolutionStack)];
+      }
+      if (param.optional) {
+        return [this.resolveOptional(param.token, paramOptions, resolutionPath, resolutionStack)];
+      }
+      if (paramOptions === undefined) {
+        return [this.resolveFromContext(param.token, resolutionPath, resolutionStack)];
+      }
+      return [this.resolve(param.token, paramOptions, resolutionPath, resolutionStack)];
+    }
+    const deps = new Array<unknown>(meta.params.length);
+    for (let index = 0; index < meta.params.length; index += 1) {
+      const param = meta.params[index]!;
+      const paramOptions = injectionSlotToResolveOptions(param);
+      if (param.multi) {
+        deps[index] = this.resolveAll(param.token, paramOptions, resolutionPath, resolutionStack);
+        continue;
+      }
+      if (param.optional) {
+        deps[index] = this.resolveOptional(param.token, paramOptions, resolutionPath, resolutionStack);
+        continue;
+      }
+      deps[index] =
+        paramOptions === undefined
+          ? this.resolveFromContext(param.token, resolutionPath, resolutionStack)
+          : this.resolve(param.token, paramOptions, resolutionPath, resolutionStack);
+    }
+    return deps;
+  }
+
+  #resolveDescriptorDeps(
+    deps: ReadonlyArray<InjectionDescriptor>,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Array<unknown> {
+    const resolved = new Array<unknown>(deps.length);
+    for (let index = 0; index < deps.length; index += 1) {
+      const dep = deps[index]!;
+      const depOptions = injectionSlotToResolveOptions(dep);
+      if (dep.multi) {
+        resolved[index] = this.resolveAll(
+          dep.token as Token<unknown> | Constructor,
+          depOptions,
+          resolutionPath,
+          resolutionStack,
+        );
+        continue;
+      }
+      if (dep.optional) {
+        resolved[index] = this.resolveOptional(
+          dep.token as Token<unknown> | Constructor,
+          depOptions,
+          resolutionPath,
+          resolutionStack,
+        );
+        continue;
+      }
+      resolved[index] =
+        depOptions === undefined
+          ? this.resolveFromContext(dep.token as Token<unknown> | Constructor, resolutionPath, resolutionStack)
+          : this.resolve(dep.token as Token<unknown> | Constructor, depOptions, resolutionPath, resolutionStack);
+    }
+    return resolved;
+  }
+
+  resolveOptional<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value | undefined {
+    if (this.#findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+      return undefined;
+    }
+    return this.resolve(token, options, resolutionPath, resolutionStack);
+  }
+
+  resolveAll<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Array<Value> {
+    if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+      const namedCandidates = this.#getSimpleNamedBindingsFromChain(token, options.name);
+      if (namedCandidates.length === 0) {
+        return [];
+      }
+      const resolved = new Array<Value>(namedCandidates.length);
+      for (let index = 0; index < namedCandidates.length; index += 1) {
+        resolved[index] = this.#resolveCandidateSync(
+          namedCandidates[index] as Binding<Value>,
+          options,
+          resolutionPath,
+          resolutionStack,
+        );
+      }
+      return resolved;
+    }
+
+    const allBindings = this.#getAllBindingsFromChain(token);
+    if (allBindings.length === 0) {
+      return [];
+    }
+
+    const ctx = this.#makeConstraintContext(resolutionPath, resolutionStack, options);
+    const candidates = selectAllBindings(allBindings, options, ctx);
+
+    const resolved = new Array<Value>(candidates.length);
+    for (let index = 0; index < candidates.length; index += 1) {
+      resolved[index] = this.#resolveCandidateSync(
+        candidates[index] as Binding<Value>,
+        options,
+        resolutionPath,
+        resolutionStack,
+      );
+    }
+    return resolved;
+  }
+
+  // ── Async resolve ──────────────────────────────────────────────────────────
+
+  resolveAsyncFromContext<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    // Hot lane: own-registry fast default (async chains resolve sibling dynamic bindings).
+    // Fall back to the chain-versioned memo only on miss or alias.
+    const fastBinding = this.#registry.getFastDefault(token);
+    if (fastBinding !== undefined && fastBinding.kind !== "alias") {
+      // Inline the dominant chain shape — transient dynamic factory with no activation.
+      if (
+        (fastBinding.kind === "dynamic-async" || fastBinding.kind === "dynamic") &&
+        fastBinding.scope === "transient" &&
+        fastBinding.onActivation === undefined &&
+        (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(fastBinding.token))
+      ) {
+        return this.#resolveTransientDynamicAsyncFromContext(
+          fastBinding as Binding<Value> & { kind: "dynamic" | "dynamic-async" },
+          resolutionPath,
+          resolutionStack,
+        );
+      }
+      return this.#resolveAsyncDefaultEntry<Value>(fastBinding, this, resolutionPath, resolutionStack);
+    }
+    const entry = this.#lookupDefaultEntry(token);
+    if (entry === null) {
+      return this.resolveAsync(token, undefined, resolutionPath, resolutionStack);
+    }
+    return this.#resolveAsyncDefaultEntry<Value>(entry.binding, entry.owner, resolutionPath, resolutionStack);
+  }
+
+  #resolveAsyncDefaultEntry<const Value>(
+    binding: Binding,
+    owner: DependencyResolver,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))
+    ) {
+      return Promise.resolve(binding.value as Value);
+    }
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+    if (scope === "transient") {
+      if (
+        (binding.kind === "dynamic" || binding.kind === "dynamic-async") &&
+        binding.onActivation === undefined &&
+        (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))
+      ) {
+        return this.#resolveTransientDynamicAsyncFromContext(
+          binding as Binding<Value> & { kind: "dynamic" | "dynamic-async" },
+          resolutionPath,
+          resolutionStack,
+        );
+      }
+    } else if (scope === "singleton") {
+      const cachedSingleton = owner.#scope.peekSingleton(binding.id);
+      if (cachedSingleton !== SINGLETON_MISS) {
+        return Promise.resolve(cachedSingleton as Value);
+      }
+      if (owner !== this) {
+        return owner.#resolveBindingAsync(binding as Binding<Value>, undefined, resolutionPath, resolutionStack);
+      }
+    } else {
+      if (!this.#scope.isChild) {
+        return Promise.reject(new MissingScopeContextError(this.#getTokenName(binding.token)));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return Promise.resolve(this.#scope.getScoped<Value>(binding.id));
+      }
+    }
+    return this.#resolveBindingAsync(binding as Binding<Value>, undefined, resolutionPath, resolutionStack);
+  }
+
+  async resolveAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    const found = this.#findBinding(token, options, resolutionPath, resolutionStack);
+
+    if (found === undefined) {
+      const ownBindings = this.#registry.getAll(token);
+      if (ownBindings.length > 0) {
+        throw new NoMatchingBindingError(this.#getTokenName(token), options ?? {}, this.#getAvailableSlots(token));
+      }
+      throw new TokenNotBoundError(this.#getTokenName(token));
+    }
+
+    let currentToken: Token<unknown> | Constructor = token;
+    let visitedAliasTokens: Set<Token<unknown> | Constructor> | undefined;
+    let aliasFollowed: DefaultLookupEntry | undefined = found;
+    while (aliasFollowed !== undefined && aliasFollowed.binding.kind === "alias") {
+      const target = aliasFollowed.binding.target;
+      visitedAliasTokens ??= new Set([currentToken]);
+      if (visitedAliasTokens.has(target)) {
+        throw new CircularDependencyError([...visitedAliasTokens, target].map((entry) => tokenName(entry)));
+      }
+      visitedAliasTokens.add(target);
+      currentToken = target;
+      aliasFollowed = this.#findBinding(currentToken, options, resolutionPath, resolutionStack);
+    }
+    if (aliasFollowed === undefined) {
+      const ownBindings = this.#registry.getAll(currentToken);
+      if (ownBindings.length > 0) {
+        throw new NoMatchingBindingError(
+          this.#getTokenName(currentToken),
+          options ?? {},
+          this.#getAvailableSlots(currentToken),
+        );
+      }
+      throw new TokenNotBoundError(this.#getTokenName(currentToken));
+    }
+    const { binding, owner } = aliasFollowed;
+
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+
+    if (scope === "singleton" && owner !== this) {
+      return owner.#resolveBindingAsync(binding as Binding<Value>, options, resolutionPath, resolutionStack);
+    }
+
+    return this.#resolveBindingAsync(binding as Binding<Value>, options, resolutionPath, resolutionStack);
+  }
+
+  async #resolveBindingAsync<const Value>(
+    binding: Binding<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      !this.#lifecycle.hasActivationHandlers(binding.token)
+    ) {
+      return binding.value;
+    }
+
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+
+    // Singleton cache
+    if (scope === "singleton") {
+      if (this.#scope.hasSingleton(binding.id)) {
+        return this.#scope.getSingleton<Value>(binding.id);
+      }
+      // In-flight dedup
+      const inflight = this.#scope.getInflight(binding.id);
+      if (inflight !== undefined) {
+        return inflight as Promise<Value>;
+      }
+    }
+
+    // Scoped cache
+    if (scope === "scoped") {
+      if (!this.#scope.isChild) {
+        throw new MissingScopeContextError(this.#getTokenName(binding.token));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return this.#scope.getScoped<Value>(binding.id);
+      }
+    }
+
+    const frame = this.#getResolutionFrame(binding);
+    const frameName = frame.tokenName;
+    const resolutionSet = enterResolutionPath(resolutionPath, frameName, false);
+    resolutionStack.push(frame);
+    const needsActivation = this.#needsActivation(binding);
+    if (!needsActivation && scope === "transient" && (binding.kind === "dynamic" || binding.kind === "dynamic-async")) {
+      const resolutionCtx = new DefaultResolutionContext(
+        this as unknown as ResolverCallbacks,
+        resolutionPath,
+        resolutionStack,
+        options,
+      );
+      try {
+        if (binding.kind === "dynamic-async") {
+          return await binding.factory(resolutionCtx);
+        }
+        const dynamicResult = binding.factory(resolutionCtx);
+        return dynamicResult instanceof Promise ? await dynamicResult : dynamicResult;
+      } finally {
+        resolutionStack.pop();
+        resolutionPath.pop();
+        resolutionSet?.delete(frameName);
+      }
+    }
+
+    const needsResolutionContext = needsActivation || this.#requiresResolutionContext(binding);
+    const resolutionCtx = needsResolutionContext
+      ? new DefaultResolutionContext(this as unknown as ResolverCallbacks, resolutionPath, resolutionStack, options)
+      : undefined;
+
+    try {
+      if (scope === "singleton") {
+        const createSingletonPromise = async (): Promise<Value> => {
+          const instance = await this.#instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
+
+          const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+          const activated = shouldActivate
+            ? await this.#lifecycle.runActivation(
+                resolutionCtx as DefaultResolutionContext,
+                binding,
+                instance,
+                this.#metadataReader,
+              )
+            : instance;
+
+          this.#scope.setSingleton(binding.id, activated);
+          this.#scope.clearInflight(binding.id);
+          return activated;
+        };
+
+        const singletonPromise = createSingletonPromise().catch((err: unknown) => {
+          this.#scope.clearInflight(binding.id);
+          throw err;
+        });
+        this.#scope.setInflight(binding.id, singletonPromise as Promise<unknown>);
+        return await singletonPromise;
+      }
+
+      const instance = await this.#instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
+
+      const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+      const activated = shouldActivate
+        ? await this.#lifecycle.runActivation(
+            resolutionCtx as DefaultResolutionContext,
+            binding,
+            instance,
+            this.#metadataReader,
+          )
+        : instance;
+
+      if (scope === "scoped") {
+        this.#scope.setScoped(binding.id, activated);
+      }
+
+      return activated;
+    } finally {
+      resolutionStack.pop();
+      resolutionPath.pop();
+      resolutionSet?.delete(frameName);
+    }
+  }
+
+  async #instantiateAsync<const Value>(
+    binding: Binding<Value>,
+    ctx: DefaultResolutionContext | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    switch (binding.kind) {
+      case "constant":
+        return binding.value;
+
+      case "dynamic": {
+        if (ctx === undefined) {
+          throw new InternalError("dynamic binding requires resolution context");
+        }
+        const factoryResult = binding.factory(ctx);
+        return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+      }
+
+      case "dynamic-async":
+        if (ctx === undefined) {
+          throw new InternalError("dynamic-async binding requires resolution context");
+        }
+        return binding.factory(ctx);
+
+      case "class": {
+        const deps = await this.#resolveClassDepsAsync(binding.target, resolutionPath, resolutionStack);
+        const instance = this.#instantiateClass(binding.target, deps);
+        return instance as Value;
+      }
+
+      case "resolved": {
+        if (ctx === undefined) {
+          throw new InternalError("resolved binding requires resolution context");
+        }
+        const deps = await this.#resolveDescriptorDepsAsync(binding.deps, resolutionPath, resolutionStack);
+        const factoryResult = binding.factory(...deps);
+        return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+      }
+
+      case "resolved-async": {
+        const deps = await this.#resolveDescriptorDepsAsync(binding.deps, resolutionPath, resolutionStack);
+        return binding.factory(...deps);
+      }
+
+      case "alias":
+        throw new InternalError("alias should have been followed before instantiation");
+    }
+  }
+
+  async #resolveClassDepsAsync(
+    target: Constructor,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Array<unknown>> {
+    const meta = this.#getConstructorMetadata(target);
+    if (meta === undefined) {
+      if (target.length === 0) {
+        return [];
+      }
+      throw new MissingMetadataError(target.name);
+    }
+    if (meta.params.length === 0) {
+      return [];
+    }
+    if (meta.params.length === 1) {
+      const param = meta.params[0]!;
+      const paramOptions = injectionSlotToResolveOptions(param);
+      if (param.multi) {
+        return [await this.resolveAllAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+      }
+      if (param.optional) {
+        return [await this.resolveOptionalAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+      }
+      if (paramOptions === undefined) {
+        return [await this.resolveAsyncFromContext(param.token, resolutionPath, resolutionStack)];
+      }
+      return [await this.resolveAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+    }
+    const pending = new Array<Promise<unknown>>(meta.params.length);
+    const shouldCloneContext = meta.params.length > 1;
+    for (let index = 0; index < meta.params.length; index += 1) {
+      const param = meta.params[index]!;
+      const paramOptions = injectionSlotToResolveOptions(param);
+      if (param.multi) {
+        pending[index] = this.resolveAllAsync(
+          param.token,
+          paramOptions,
+          shouldCloneContext ? [...resolutionPath] : resolutionPath,
+          shouldCloneContext ? [...resolutionStack] : resolutionStack,
+        );
+      } else if (param.optional) {
+        pending[index] = this.resolveOptionalAsync(
+          param.token,
+          paramOptions,
+          shouldCloneContext ? [...resolutionPath] : resolutionPath,
+          shouldCloneContext ? [...resolutionStack] : resolutionStack,
+        );
+      } else {
+        pending[index] =
+          paramOptions === undefined
+            ? this.resolveAsyncFromContext(
+                param.token,
+                shouldCloneContext ? [...resolutionPath] : resolutionPath,
+                shouldCloneContext ? [...resolutionStack] : resolutionStack,
+              )
+            : this.resolveAsync(
+                param.token,
+                paramOptions,
+                shouldCloneContext ? [...resolutionPath] : resolutionPath,
+                shouldCloneContext ? [...resolutionStack] : resolutionStack,
+              );
+      }
+    }
+    return Promise.all(pending);
+  }
+
+  async #resolveDescriptorDepsAsync(
+    deps: ReadonlyArray<InjectionDescriptor>,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Array<unknown>> {
+    const pending = new Array<Promise<unknown>>(deps.length);
+    const shouldCloneContext = deps.length > 1;
+    for (let index = 0; index < deps.length; index += 1) {
+      const dep = deps[index]!;
+      const depOptions = injectionSlotToResolveOptions(dep);
+      if (dep.multi) {
+        pending[index] = this.resolveAllAsync(
+          dep.token as Token<unknown> | Constructor,
+          depOptions,
+          shouldCloneContext ? [...resolutionPath] : resolutionPath,
+          shouldCloneContext ? [...resolutionStack] : resolutionStack,
+        );
+      } else if (dep.optional) {
+        pending[index] = this.resolveOptionalAsync(
+          dep.token as Token<unknown> | Constructor,
+          depOptions,
+          shouldCloneContext ? [...resolutionPath] : resolutionPath,
+          shouldCloneContext ? [...resolutionStack] : resolutionStack,
+        );
+      } else {
+        pending[index] =
+          depOptions === undefined
+            ? this.resolveAsyncFromContext(
+                dep.token as Token<unknown> | Constructor,
+                shouldCloneContext ? [...resolutionPath] : resolutionPath,
+                shouldCloneContext ? [...resolutionStack] : resolutionStack,
+              )
+            : this.resolveAsync(
+                dep.token as Token<unknown> | Constructor,
+                depOptions,
+                shouldCloneContext ? [...resolutionPath] : resolutionPath,
+                shouldCloneContext ? [...resolutionStack] : resolutionStack,
+              );
+      }
+    }
+    return Promise.all(pending);
+  }
+
+  async resolveOptionalAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value | undefined> {
+    if (this.#findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+      return undefined;
+    }
+    return this.resolveAsync(token, options, resolutionPath, resolutionStack);
+  }
+
+  async resolveAllAsync<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Array<Value>> {
+    if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+      const namedCandidates = this.#getSimpleNamedBindingsFromChain(token, options.name);
+      if (namedCandidates.length === 0) {
+        return [];
+      }
+      const pending = new Array<Promise<Value>>(namedCandidates.length);
+      for (let index = 0; index < namedCandidates.length; index += 1) {
+        pending[index] = this.#resolveCandidateAsync(
+          namedCandidates[index] as Binding<Value>,
+          options,
+          resolutionPath,
+          resolutionStack,
+        );
+      }
+      return Promise.all(pending);
+    }
+
+    const allBindings = this.#getAllBindingsFromChain(token);
+    if (allBindings.length === 0) {
+      return [];
+    }
+
+    const ctx = this.#makeConstraintContext(resolutionPath, resolutionStack, options);
+    const candidates = selectAllBindings(allBindings, options, ctx);
+
+    const pending = new Array<Promise<Value>>(candidates.length);
+    for (let index = 0; index < candidates.length; index += 1) {
+      pending[index] = this.#resolveCandidateAsync(
+        candidates[index] as Binding<Value>,
+        options,
+        resolutionPath,
+        resolutionStack,
+      );
+    }
+    return Promise.all(pending);
+  }
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  #getAllBindingsFromChain(token: Token<unknown> | Constructor): ReadonlyArray<Binding> {
+    const ownBindings = this.#registry.getAll(token);
+    if (this.#parent === undefined) {
+      return ownBindings;
+    }
+    const result: Array<Binding> = [...ownBindings];
+    let current: DependencyResolver | undefined = this.#parent;
+    while (current !== undefined) {
+      const own = current.#registry.getAll(token);
+      if (own.length > 0) {
+        result.push(...own);
+      }
+      current = current.#parent;
+    }
+    return result;
+  }
+
+  #getSimpleNamedBindingsFromChain(token: Token<unknown> | Constructor, name: string): Array<Binding> {
+    const ownBinding = this.#registry.getSimpleNamed(token, name);
+    if (this.#parent === undefined) {
+      return ownBinding !== undefined ? [ownBinding] : [];
+    }
+    const result: Array<Binding> = [];
+    if (ownBinding !== undefined) {
+      result.push(ownBinding);
+    }
+    let current: DependencyResolver | undefined = this.#parent;
+    while (current !== undefined) {
+      const binding = current.#registry.getSimpleNamed(token, name);
+      if (binding !== undefined) {
+        result.push(binding);
+      }
+      current = current.#parent;
+    }
+    return result;
+  }
+
+  #getAvailableSlots(token: Token<unknown> | Constructor): Array<string> {
+    return this.#registry.availableSlotStrings(token);
+  }
+
+  #makeConstraintContext(
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+    options: ResolveOptions | undefined,
+  ): ConstraintContext {
+    if (options === undefined && resolutionPath.length === 0 && resolutionStack.length === 0) {
+      return ROOT_CONSTRAINT_CONTEXT;
+    }
+    const parent = resolutionStack.at(-1);
+    const ancestors = resolutionStack.length > 1 ? resolutionStack.slice(0, -1) : [];
+    return {
+      resolutionPath,
+      resolutionStack,
+      parent,
+      ancestors,
+      currentResolveOptions: options,
+    };
+  }
+
+  #matchesBindingFast(
+    binding: Binding,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): boolean {
+    if (!this.#matchesSlotFast(binding.slot, options)) {
+      return false;
+    }
+    if (binding.predicate === undefined) {
+      return true;
+    }
+    const ctx = this.#makeConstraintContext(resolutionPath, resolutionStack, options);
+    return binding.predicate(ctx);
+  }
+
+  #matchesSlotFast(slot: BindingSlot, options: ResolveOptions | undefined): boolean {
+    const requestedName = options?.name;
+    const requestedTags = options?.tags;
+    const singleRequestedTag = options?.tag;
+    const hasRequestedTags = (requestedTags?.length ?? 0) > 0 || singleRequestedTag !== undefined;
+
+    if (slot.name !== undefined) {
+      if (requestedName === undefined || slot.name !== requestedName) {
+        return false;
+      }
+    } else if (requestedName !== undefined) {
+      return false;
+    }
+
+    if (slot.tags.length > 0) {
+      if (!hasRequestedTags) {
+        return false;
+      }
+      for (const [tagKey, tagValue] of slot.tags) {
+        if (!this.#matchesRequestedTag(tagKey, tagValue, requestedTags, singleRequestedTag)) {
+          return false;
+        }
+      }
+    } else if (hasRequestedTags) {
+      return false;
+    }
+
+    return true;
+  }
+
+  #getTokenName(token: Token<unknown> | Constructor): string {
+    return tokenName(token);
+  }
+
+  #getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined {
+    const cached = this.#classConstructorMetadata.get(target);
+    if (cached !== undefined) {
+      return cached === null ? undefined : cached;
+    }
+    const metadata = this.#metadataReader.getConstructorMetadata(target);
+    this.#classConstructorMetadata.set(target, metadata ?? null);
+    return metadata;
+  }
+
+  #instantiateClass(target: Constructor, deps: Array<unknown>): unknown {
+    let needsActiveContainer = this.#classNeedsActiveContainer.get(target);
+    if (needsActiveContainer === undefined) {
+      const accessorMetadata = this.#metadataReader.getAccessorMetadata?.(target);
+      needsActiveContainer = (accessorMetadata?.length ?? 0) > 0;
+      this.#classNeedsActiveContainer.set(target, needsActiveContainer);
+    }
+    const invokable = target as ConstructorInvocation;
+    if (!needsActiveContainer) {
+      return new invokable(...deps);
+    }
+    return runWithContainer(this.#container, () => new invokable(...deps));
+  }
+
+  #matchesRequestedTag(
+    tagKey: string,
+    tagValue: unknown,
+    requestedTags: ReadonlyArray<BindingTag> | undefined,
+    singleRequestedTag: BindingTag | undefined,
+  ): boolean {
+    if (
+      singleRequestedTag !== undefined &&
+      singleRequestedTag[0] === tagKey &&
+      Object.is(singleRequestedTag[1], tagValue)
+    ) {
+      return true;
+    }
+    if (requestedTags === undefined || requestedTags.length === 0) {
+      return false;
+    }
+    for (let index = 0; index < requestedTags.length; index += 1) {
+      const requestedTag = requestedTags[index]!;
+      if (requestedTag[0] === tagKey && Object.is(requestedTag[1], tagValue)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  #resolveTransientDynamicSyncFromContext<const Value>(
+    binding: Binding<Value> & { kind: "dynamic" },
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    // One lane at every depth. The separate deep lane existed because cycle detection used to be
+    // an O(depth) `resolutionPath.includes()` scan, which had to be escaped past ~32 levels; with
+    // the O(1) `binding.inFlight` mark there is nothing to escape, so the depth split — and the
+    // divergent behaviour it caused — is gone.
+    const frame = this.#getResolutionFrame(binding);
+    const tokenDisplayName = frame.tokenName;
+    if (binding.inFlight) {
+      throw new CircularDependencyError([...resolutionPath, tokenDisplayName]);
+    }
+    binding.inFlight = true;
+    resolutionPath.push(tokenDisplayName);
+    resolutionStack.push(frame);
+    const resolutionCtx = this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, undefined);
+    try {
+      const dynamicResult = binding.factory(resolutionCtx);
+      if (dynamicResult instanceof Promise) {
+        throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+      }
+      return dynamicResult;
+    } finally {
+      resolutionStack.pop();
+      resolutionPath.pop();
+      binding.inFlight = false;
+    }
+  }
+
+  // NOT declared `async` — avoids creating a JSAsyncGeneratorObject + implicit Promise wrapper on
+  // every invocation.  Cleanup is handled via .then(onFulfilled, onRejected) so the behaviour is
+  // identical to a try/finally but without the async machinery overhead.
+  #resolveTransientDynamicAsyncFromContext<const Value>(
+    binding: Binding<Value> & { kind: "dynamic" | "dynamic-async" },
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    // One lane at every depth. Cycle detection goes through `enterResolutionPath`, which is
+    // path-scoped — the only mechanism that stays correct when chains interleave (Promise.all) —
+    // and adapts on its own: a linear scan while the path is short, an attached Set past
+    // RESOLUTION_SET_THRESHOLD. That removes the depth split, and with it a silent change of
+    // behaviour (context identity, stack frames, promise shape) at the old threshold.
+    //
+    // For a sequential chain every level shares one resolutionPath/resolutionStack, so a single
+    // DefaultResolutionContext serves the whole chain: inner levels of the owning chain allocate
+    // nothing. A concurrent chain is detected by path identity and gets its own context.
+    const frame = this.#getResolutionFrame(binding);
+    const tokenDisplayName = frame.tokenName;
+    try {
+      enterResolutionPath(resolutionPath, tokenDisplayName, false);
+    } catch (cycleError) {
+      // This method is not `async`; keep failures as rejections rather than sync throws.
+      return Promise.reject(cycleError);
+    }
+
+    let ctx: DefaultResolutionContext;
+    let isOwnerLevel: boolean;
+    if (this.#asyncChainCtxPath === resolutionPath) {
+      ctx = this.#asyncChainCtx!;
+      isOwnerLevel = true;
+    } else if (this.#asyncChainCtxPath === undefined) {
+      const existing = this.#asyncChainCtx;
+      if (existing === undefined) {
+        ctx = new DefaultResolutionContext(
+          this as unknown as ResolverCallbacks,
+          resolutionPath,
+          resolutionStack,
+          undefined,
+        );
+        this.#asyncChainCtx = ctx;
+      } else {
+        existing.reset(this as unknown as ResolverCallbacks, resolutionPath, resolutionStack, undefined);
+        ctx = existing;
+      }
+      this.#asyncChainCtxPath = resolutionPath;
+      isOwnerLevel = true;
+    } else {
+      ctx = new DefaultResolutionContext(
+        this as unknown as ResolverCallbacks,
+        resolutionPath,
+        resolutionStack,
+        undefined,
+      );
+      isOwnerLevel = false;
+    }
+
+    if (isOwnerLevel) {
+      this.#asyncChainActiveLevels++;
+    }
+
+    // Invoke the factory synchronously to get its Promise (or a resolved value for "dynamic").
+    let factoryPromise: Promise<Value>;
+    try {
+      if (binding.kind === "dynamic-async") {
+        factoryPromise = binding.factory(ctx);
+      } else {
+        const factoryResult = binding.factory(ctx);
+        factoryPromise =
+          factoryResult instanceof Promise ? (factoryResult as Promise<Value>) : Promise.resolve(factoryResult);
+      }
+    } catch (factoryError) {
+      // Synchronous throw from the factory (rare) — clean up immediately.
+      exitResolutionPath(resolutionPath);
+      if (isOwnerLevel && --this.#asyncChainActiveLevels === 0) {
+        this.#asyncChainCtxPath = undefined;
+        this.#asyncChainSettle = undefined;
+      }
+      return Promise.reject(factoryError);
+    }
+
+    // Cleanup runs as a SIDE listener on the factory promise instead of a derived-promise chain:
+    // registered synchronously here, it is FIFO-guaranteed to run before the awaiting caller
+    // resumes, so ordering is identical while saving one intermediate promise and one microtask
+    // hop per level. Trade-off: the settle handler marks a rejection as handled, so an unawaited
+    // failing resolveAsync no longer surfaces as an unhandledRejection — callers are expected to
+    // await (or .catch) the returned promise.
+    //
+    // Every level of the owning chain unwinds identically, so one closure serves them all.
+    let settle: () => void;
+    if (isOwnerLevel) {
+      settle =
+        this.#asyncChainSettle ??
+        (this.#asyncChainSettle = (): void => {
+          exitResolutionPath(resolutionPath);
+          if (--this.#asyncChainActiveLevels === 0) {
+            this.#asyncChainCtxPath = undefined;
+            this.#asyncChainSettle = undefined;
+          }
+        });
+    } else {
+      settle = (): void => {
+        exitResolutionPath(resolutionPath);
+      };
+    }
+    factoryPromise.then(settle, settle);
+    return factoryPromise;
+  }
+
+  #resolveCandidateSync<const Value>(
+    binding: Binding<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Value {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      !this.#lifecycle.hasActivationHandlers(binding.token)
+    ) {
+      return binding.value;
+    }
+    if (binding.kind === "alias") {
+      return this.resolve(binding.target, options, resolutionPath, resolutionStack);
+    }
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+    if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
+      return this.#scope.getSingleton<Value>(binding.id);
+    }
+    if (scope === "scoped") {
+      if (!this.#scope.isChild) {
+        throw new MissingScopeContextError(this.#getTokenName(binding.token));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return this.#scope.getScoped<Value>(binding.id);
+      }
+    }
+    return this.#resolveBinding(binding, options, resolutionPath, resolutionStack);
+  }
+
+  #resolveCandidateAsync<const Value>(
+    binding: Binding<Value>,
+    options: ResolveOptions | undefined,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): Promise<Value> {
+    if (
+      binding.kind === "constant" &&
+      binding.onActivation === undefined &&
+      !this.#lifecycle.hasActivationHandlers(binding.token)
+    ) {
+      return Promise.resolve(binding.value);
+    }
+    const isolatedPath = [...resolutionPath];
+    const isolatedStack = [...resolutionStack];
+    if (binding.kind === "alias") {
+      return this.resolveAsync(binding.target, options, isolatedPath, isolatedStack);
+    }
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+    if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
+      return Promise.resolve(this.#scope.getSingleton<Value>(binding.id));
+    }
+    if (scope === "scoped") {
+      if (!this.#scope.isChild) {
+        return Promise.reject(new MissingScopeContextError(this.#getTokenName(binding.token)));
+      }
+      if (this.#scope.hasScoped(binding.id)) {
+        return Promise.resolve(this.#scope.getScoped<Value>(binding.id));
+      }
+    }
+    return this.#resolveBindingAsync(binding, options, isolatedPath, isolatedStack);
+  }
+
+  #getResolutionFrame<const Value>(binding: Binding<Value>): ResolutionFrame {
+    // Memoized on the binding rather than in a per-resolver Map: the frame derives only from
+    // immutable binding fields, so it is identical for every resolver, and a field read beats a
+    // Map lookup on every hop of a chain.
+    const existing = binding.frame;
+    if (existing !== undefined) {
+      return existing;
+    }
+    const scope = (binding as BindingWithScope).scope ?? "transient";
+    const frame = buildResolutionFrame(tokenName(binding.token), scope, binding.id, binding.kind, binding.slot);
+    binding.frame = frame;
+    return frame;
+  }
+
+  #needsActivation<const Value>(binding: Binding<Value>): boolean {
+    const lifecycleVersion = this.#lifecycle.activationVersion;
+    if (
+      lifecycleVersion === 0 &&
+      binding.kind !== "class" &&
+      binding.kind !== "alias" &&
+      binding.onActivation === undefined
+    ) {
+      return false;
+    }
+    if (this.#activationCacheVersion !== lifecycleVersion) {
+      this.#activationNeedByBindingId.clear();
+      this.#activationCacheVersion = lifecycleVersion;
+    }
+
+    const cached = this.#activationNeedByBindingId.get(binding.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    if (binding.kind === "class") {
+      let hasActivation = this.#lifecycle.hasActivationHandlers(binding.token) || binding.onActivation !== undefined;
+      const cachedPostConstruct = this.#classHasPostConstruct.get(binding.target);
+      // Unknown class lifecycle metadata: activate once, then cache after first instantiation.
+      if (cachedPostConstruct === undefined) {
+        hasActivation = true;
+      } else if (cachedPostConstruct) {
+        hasActivation = true;
+      }
+      this.#activationNeedByBindingId.set(binding.id, hasActivation);
+      return hasActivation;
+    }
+
+    let hasActivation = false;
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      hasActivation = true;
+    } else if (this.#lifecycle.hasActivationHandlers(binding.token)) {
+      hasActivation = true;
+    }
+
+    this.#activationNeedByBindingId.set(binding.id, hasActivation);
+    return hasActivation;
+  }
+
+  #refreshClassPostConstructCache(target: Constructor): void {
+    const lifecycle = this.#metadataReader.getLifecycleMetadata(target);
+    const hasPostConstruct =
+      lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0;
+    this.#classHasPostConstruct.set(target, hasPostConstruct);
+  }
+
+  /**
+   * Refreshes the post-construct cache for class bindings on first instantiation and
+   * returns the (possibly updated) shouldActivate flag.
+   */
+  #refreshActivationCacheIfNeeded<Value>(binding: Binding<Value>, needsActivation: boolean): boolean {
+    if (binding.kind === "class" && this.#classHasPostConstruct.get(binding.target) === undefined) {
+      this.#refreshClassPostConstructCache(binding.target);
+      this.#activationNeedByBindingId.delete(binding.id);
+      return this.#needsActivation(binding);
+    }
+    return needsActivation;
+  }
+
+  #requiresResolutionContext<const Value>(binding: Binding<Value>): boolean {
+    return binding.kind === "dynamic" || binding.kind === "dynamic-async";
+  }
+
+  #acquireSyncResolutionContext(
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+    options: ResolveOptions | undefined,
+  ): DefaultResolutionContext {
+    const depth = resolutionStack.length;
+    const existing = this.#syncResolutionContextPool[depth];
+    if (existing !== undefined) {
+      existing.reset(this as unknown as ResolverCallbacks, resolutionPath, resolutionStack, options);
+      return existing;
+    }
+    const created = new DefaultResolutionContext(
+      this as unknown as ResolverCallbacks,
+      resolutionPath,
+      resolutionStack,
+      options,
+    );
+    this.#syncResolutionContextPool[depth] = created;
+    return created;
+  }
+}