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

package/src/resolution/resolver.ts

@@ -1,5 +1,5 @@
 import type { Binding, BindingSlot } from "#/binding";
-import type { ConstructorInvocation } from "#/constructor-type";
+import { NO_INSTANCE } from "#/binding";
 import type { Container } from "#/container/container";
 import type { InjectionDescriptor } from "#/decorators/inject";
 import {
@@ -12,17 +12,21 @@ import {
   NoMatchingBindingError,
   TokenNotBoundError,
 } from "#/errors";
-import type { ConstructorMetadata, MetadataReader } from "#/metadata/metadata-types";
+import type { MetadataReader } from "#/metadata/metadata-types";
 import type { BindingRegistry } from "#/registry";
+import { ActivationNeedCache } from "#/resolution/activation-need";
+import type { DefaultLookupEntry } from "#/resolution/binding-lookup-cache";
+import { BindingLookupCache } from "#/resolution/binding-lookup-cache";
 import { selectAllBindings, selectBinding } from "#/resolution/binding-select";
+import { ClassIntrospector } from "#/resolution/class-introspector";
+import type { ResolutionDiagnostics } from "#/resolution/diagnostics";
 import type { ResolverCallbacks } from "#/resolution/environment";
-import { buildResolutionFrame, DefaultResolutionContext, runWithContainer } from "#/resolution/environment";
+import { buildResolutionFrame, DefaultResolutionContext } 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 {
@@ -36,16 +40,6 @@ import type {
   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> = [];
@@ -60,53 +54,12 @@ const ROOT_CONSTRAINT_CONTEXT = {
 /**
  * @since 0.3.16-canary.0
  */
-export class DependencyResolver {
+export class DependencyResolver implements ResolverCallbacks {
   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.
+  // Pure allocation pool: a chain's own context is threaded through the call, so nothing here
+  // identifies a chain.
+  readonly #asyncChainContextPool: Array<DefaultResolutionContext> = [];
+  // Compiled plans; `null` marks a binding as unplannable under the current cache versions.
   readonly #classPlanByBindingId = new Map<BindingIdentifier, (() => unknown) | null>();
   #classPlanRegistryVersion = -1;
   #classPlanActivationVersion = -1;
@@ -115,8 +68,10 @@ export class DependencyResolver {
   readonly #scope: ScopeManager;
   readonly #lifecycle: LifecycleManager;
   readonly #metadataReader: MetadataReader;
-  readonly #container: Container;
   readonly #parent: DependencyResolver | undefined;
+  readonly #lookup: BindingLookupCache<DependencyResolver>;
+  readonly #classes: ClassIntrospector;
+  readonly #activation: ActivationNeedCache;
 
   constructor(
     registry: BindingRegistry,
@@ -130,8 +85,29 @@ export class DependencyResolver {
     this.#scope = scope;
     this.#lifecycle = lifecycle;
     this.#metadataReader = metadataReader;
-    this.#container = container;
     this.#parent = parent;
+    this.#lookup = new BindingLookupCache<DependencyResolver>(
+      registry,
+      this,
+      parent === undefined ? undefined : parent.#lookup,
+    );
+    this.#classes = new ClassIntrospector(metadataReader, container);
+    this.#activation = new ActivationNeedCache(lifecycle, this.#classes);
+  }
+
+  /** Structural counts for {@link RESOLUTION_DIAGNOSTICS}; see `resolution/diagnostics.ts`. */
+  describeCaches(): Pick<ResolutionDiagnostics, "asyncContextPoolSize" | "compiledPlanCount" | "syncContextPoolSize"> {
+    let compiledPlanCount = 0;
+    for (const plan of this.#classPlanByBindingId.values()) {
+      if (plan !== null) {
+        compiledPlanCount += 1;
+      }
+    }
+    return {
+      asyncContextPoolSize: this.#asyncChainContextPool.length,
+      compiledPlanCount,
+      syncContextPoolSize: this.#syncResolutionContextPool.length,
+    };
   }
 
   // ── Binding lookup ─────────────────────────────────────────────────────────
@@ -237,7 +213,7 @@ export class DependencyResolver {
     if (fastBinding !== undefined && fastBinding.kind !== "alias") {
       return this.#resolveDefaultEntry<Value>(fastBinding, this, resolutionPath, resolutionStack);
     }
-    const entry = this.#lookupDefaultEntry(token);
+    const entry = this.#lookup.defaultEntry(token);
     if (entry === null) {
       return this.resolve(token, undefined, resolutionPath, resolutionStack);
     }
@@ -284,8 +260,8 @@ export class DependencyResolver {
         }
       }
     } else if (scope === "singleton") {
-      const cachedSingleton = owner.#scope.peekSingleton(binding.id);
-      if (cachedSingleton !== SINGLETON_MISS) {
+      const cachedSingleton = binding.instance;
+      if (cachedSingleton !== NO_INSTANCE) {
         return cachedSingleton as Value;
       }
       if (owner !== this) {
@@ -346,89 +322,8 @@ export class DependencyResolver {
     }
   }
 
-  #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 registryVersion = this.#lookup.chainVersion();
     const activationVersion = this.#lifecycle.activationVersion;
     if (registryVersion !== this.#classPlanRegistryVersion || activationVersion !== this.#classPlanActivationVersion) {
       this.#classPlanByBindingId.clear();
@@ -451,22 +346,28 @@ export class DependencyResolver {
   // 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),
+    knownPostConstruct: (target) => this.#classes.knownPostConstruct(target),
+    needsActiveContainer: (target) => this.#classes.needsActiveContainer(target),
+    getConstructorMetadata: (target) => this.#classes.constructorMetadata(target),
     lookupDependencyEntry: (token) => {
-      const entry = this.#lookupDefaultEntry(token);
-      return entry === null ? null : { binding: entry.binding, ownerScope: entry.owner.#scope };
+      const entry = this.#lookup.defaultEntry(token);
+      return entry === null ? null : { binding: entry.binding };
+    },
+    getResolutionFrame: (binding) => this.#getResolutionFrame(binding),
+    // Dispatches exactly as #resolveClassDeps does, so an escaped dep is indistinguishable
+    // from the same dep on a fully interpreted resolve.
+    resolveEscaped: (token, options, arity, resolutionPath, resolutionStack) => {
+      if (arity === "all") {
+        return this.resolveAll(token, options, resolutionPath, resolutionStack);
+      }
+      if (arity === "optional") {
+        return this.resolveOptional(token, options, resolutionPath, resolutionStack);
+      }
+      if (options === undefined) {
+        return this.resolveFromContext(token, resolutionPath, resolutionStack);
+      }
+      return this.resolve(token, options, resolutionPath, resolutionStack);
     },
-    resolveFallback: (token) => this.resolve(token, undefined, [], []),
   });
 
   resolve<const Value>(
@@ -483,7 +384,7 @@ export class DependencyResolver {
       options.tag === undefined &&
       (options.tags === undefined || options.tags.length === 0)
     ) {
-      const namedEntry = this.#lookupNamedEntry(token, options.name);
+      const namedEntry = this.#lookup.namedEntry(token, options.name);
       if (namedEntry !== null) {
         const namedBinding = namedEntry.binding;
         if (
@@ -495,9 +396,8 @@ export class DependencyResolver {
         }
         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;
+          if (namedBinding.instance !== NO_INSTANCE) {
+            return namedBinding.instance as Value;
           }
         }
         // Everything else keeps the full path (context, activation, guards).
@@ -563,10 +463,8 @@ export class DependencyResolver {
     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);
-      }
+    if (scope === "singleton" && binding.instance !== NO_INSTANCE) {
+      return binding.instance as Value;
     }
 
     // Scoped cache check
@@ -583,7 +481,7 @@ export class DependencyResolver {
     const tokenDisplayName = frame.tokenName;
     const resolutionSet = enterResolutionPath(resolutionPath, tokenDisplayName, false);
     resolutionStack.push(frame);
-    const needsActivation = this.#needsActivation(binding);
+    const needsActivation = this.#activation.needsActivation(binding);
     if (!needsActivation && scope === "transient" && binding.kind === "dynamic") {
       const resolutionCtx = this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, options);
       try {
@@ -611,7 +509,7 @@ export class DependencyResolver {
 
       const instance = this.#instantiateSync(binding, resolutionCtx, resolutionPath, resolutionStack);
 
-      const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+      const shouldActivate = this.#activation.refreshAfterFirstInstantiation(binding, needsActivation);
       const activated = shouldActivate
         ? this.#lifecycle.runActivationSync(
             resolutionCtx as DefaultResolutionContext,
@@ -623,7 +521,7 @@ export class DependencyResolver {
 
       // Cache by scope
       if (scope === "singleton") {
-        this.#scope.setSingleton(binding.id, activated);
+        this.#scope.setSingleton(binding, activated);
       } else if (scope === "scoped") {
         this.#scope.setScoped(binding.id, activated);
       }
@@ -662,7 +560,7 @@ export class DependencyResolver {
 
       case "class": {
         const deps = this.#resolveClassDeps(binding.target, resolutionPath, resolutionStack);
-        const instance = this.#instantiateClass(binding.target, deps);
+        const instance = this.#classes.instantiate(binding.target, deps);
         return instance as Value;
       }
 
@@ -688,7 +586,7 @@ export class DependencyResolver {
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Array<unknown> {
-    const meta = this.#getConstructorMetadata(target);
+    const meta = this.#classes.constructorMetadata(target);
     if (meta === undefined) {
       if (target.length === 0) {
         return [];
@@ -828,6 +726,7 @@ export class DependencyResolver {
     token: Token<Value> | Constructor<Value>,
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
+    callerContext?: DefaultResolutionContext,
   ): 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.
@@ -844,15 +743,22 @@ export class DependencyResolver {
           fastBinding as Binding<Value> & { kind: "dynamic" | "dynamic-async" },
           resolutionPath,
           resolutionStack,
+          callerContext,
         );
       }
-      return this.#resolveAsyncDefaultEntry<Value>(fastBinding, this, resolutionPath, resolutionStack);
+      return this.#resolveAsyncDefaultEntry<Value>(fastBinding, this, resolutionPath, resolutionStack, callerContext);
     }
-    const entry = this.#lookupDefaultEntry(token);
+    const entry = this.#lookup.defaultEntry(token);
     if (entry === null) {
       return this.resolveAsync(token, undefined, resolutionPath, resolutionStack);
     }
-    return this.#resolveAsyncDefaultEntry<Value>(entry.binding, entry.owner, resolutionPath, resolutionStack);
+    return this.#resolveAsyncDefaultEntry<Value>(
+      entry.binding,
+      entry.owner,
+      resolutionPath,
+      resolutionStack,
+      callerContext,
+    );
   }
 
   #resolveAsyncDefaultEntry<const Value>(
@@ -860,6 +766,7 @@ export class DependencyResolver {
     owner: DependencyResolver,
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
+    callerContext?: DefaultResolutionContext,
   ): Promise<Value> {
     if (
       binding.kind === "constant" &&
@@ -879,12 +786,12 @@ export class DependencyResolver {
           binding as Binding<Value> & { kind: "dynamic" | "dynamic-async" },
           resolutionPath,
           resolutionStack,
+          callerContext,
         );
       }
     } else if (scope === "singleton") {
-      const cachedSingleton = owner.#scope.peekSingleton(binding.id);
-      if (cachedSingleton !== SINGLETON_MISS) {
-        return Promise.resolve(cachedSingleton as Value);
+      if (binding.instance !== NO_INSTANCE) {
+        return Promise.resolve(binding.instance as Value);
       }
       if (owner !== this) {
         return owner.#resolveBindingAsync(binding as Binding<Value>, undefined, resolutionPath, resolutionStack);
@@ -918,7 +825,7 @@ export class DependencyResolver {
 
     let currentToken: Token<unknown> | Constructor = token;
     let visitedAliasTokens: Set<Token<unknown> | Constructor> | undefined;
-    let aliasFollowed: DefaultLookupEntry | undefined = found;
+    let aliasFollowed: DefaultLookupEntry<DependencyResolver> | undefined = found;
     while (aliasFollowed !== undefined && aliasFollowed.binding.kind === "alias") {
       const target = aliasFollowed.binding.target;
       visitedAliasTokens ??= new Set([currentToken]);
@@ -969,8 +876,8 @@ export class DependencyResolver {
 
     // Singleton cache
     if (scope === "singleton") {
-      if (this.#scope.hasSingleton(binding.id)) {
-        return this.#scope.getSingleton<Value>(binding.id);
+      if (binding.instance !== NO_INSTANCE) {
+        return binding.instance as Value;
       }
       // In-flight dedup
       const inflight = this.#scope.getInflight(binding.id);
@@ -993,14 +900,9 @@ export class DependencyResolver {
     const frameName = frame.tokenName;
     const resolutionSet = enterResolutionPath(resolutionPath, frameName, false);
     resolutionStack.push(frame);
-    const needsActivation = this.#needsActivation(binding);
+    const needsActivation = this.#activation.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,
-      );
+      const resolutionCtx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, options);
       try {
         if (binding.kind === "dynamic-async") {
           return await binding.factory(resolutionCtx);
@@ -1016,7 +918,7 @@ export class DependencyResolver {
 
     const needsResolutionContext = needsActivation || this.#requiresResolutionContext(binding);
     const resolutionCtx = needsResolutionContext
-      ? new DefaultResolutionContext(this as unknown as ResolverCallbacks, resolutionPath, resolutionStack, options)
+      ? new DefaultResolutionContext(this, resolutionPath, resolutionStack, options)
       : undefined;
 
     try {
@@ -1024,7 +926,7 @@ export class DependencyResolver {
         const createSingletonPromise = async (): Promise<Value> => {
           const instance = await this.#instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
 
-          const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+          const shouldActivate = this.#activation.refreshAfterFirstInstantiation(binding, needsActivation);
           const activated = shouldActivate
             ? await this.#lifecycle.runActivation(
                 resolutionCtx as DefaultResolutionContext,
@@ -1034,7 +936,8 @@ export class DependencyResolver {
               )
             : instance;
 
-          this.#scope.setSingleton(binding.id, activated);
+          this.#scope.setSingleton(binding, activated);
+          binding.instance = activated;
           this.#scope.clearInflight(binding.id);
           return activated;
         };
@@ -1049,7 +952,7 @@ export class DependencyResolver {
 
       const instance = await this.#instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
 
-      const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+      const shouldActivate = this.#activation.refreshAfterFirstInstantiation(binding, needsActivation);
       const activated = shouldActivate
         ? await this.#lifecycle.runActivation(
             resolutionCtx as DefaultResolutionContext,
@@ -1097,7 +1000,7 @@ export class DependencyResolver {
 
       case "class": {
         const deps = await this.#resolveClassDepsAsync(binding.target, resolutionPath, resolutionStack);
-        const instance = this.#instantiateClass(binding.target, deps);
+        const instance = this.#classes.instantiate(binding.target, deps);
         return instance as Value;
       }
 
@@ -1125,7 +1028,7 @@ export class DependencyResolver {
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
   ): Promise<Array<unknown>> {
-    const meta = this.#getConstructorMetadata(target);
+    const meta = this.#classes.constructorMetadata(target);
     if (meta === undefined) {
       if (target.length === 0) {
         return [];
@@ -1397,30 +1300,6 @@ export class DependencyResolver {
     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,
@@ -1451,10 +1330,7 @@ export class DependencyResolver {
     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.
+    // One lane at every depth: `binding.inFlight` is O(1), so there is nothing to escape.
     const frame = this.#getResolutionFrame(binding);
     const tokenDisplayName = frame.tokenName;
     if (binding.inFlight) {
@@ -1477,23 +1353,15 @@ export class DependencyResolver {
     }
   }
 
-  // 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.
+  // Deliberately not `async`: that would allocate a state machine and a promise per level.
   #resolveTransientDynamicAsyncFromContext<const Value>(
     binding: Binding<Value> & { kind: "dynamic" | "dynamic-async" },
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
+    callerContext?: DefaultResolutionContext,
   ): 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.
+    // Path-scoped cycle detection, because async chains interleave — see ARCHITECTURE.md.
+    const pool = this.#asyncChainContextPool;
     const frame = this.#getResolutionFrame(binding);
     const tokenDisplayName = frame.tokenName;
     try {
@@ -1503,40 +1371,13 @@ export class DependencyResolver {
       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++;
-    }
+    // An inner level reuses the context its caller passed down; only a chain's first level
+    // borrows from the pool. Pooling is load-bearing here — see ARCHITECTURE.md.
+    const ctx =
+      callerContext !== undefined && callerContext.owner === this
+        ? callerContext
+        : this.#acquireAsyncChainContext(resolutionPath, resolutionStack);
+    ctx.chainLevels += 1;
 
     // Invoke the factory synchronously to get its Promise (or a resolved value for "dynamic").
     let factoryPromise: Promise<Value>;
@@ -1551,41 +1392,40 @@ export class DependencyResolver {
     } catch (factoryError) {
       // Synchronous throw from the factory (rare) — clean up immediately.
       exitResolutionPath(resolutionPath);
-      if (isOwnerLevel && --this.#asyncChainActiveLevels === 0) {
-        this.#asyncChainCtxPath = undefined;
-        this.#asyncChainSettle = undefined;
+      ctx.chainLevels -= 1;
+      if (ctx.chainLevels === 0) {
+        pool.push(ctx);
       }
       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 => {
+    // A side listener, not a derived chain: FIFO puts it before the awaiting caller resumes.
+    // It marks a rejection as handled, so callers must await or `.catch` the returned promise.
+    const settle =
+      ctx.chainSettle ??
+      (ctx.chainSettle = (): void => {
         exitResolutionPath(resolutionPath);
-      };
-    }
+        ctx.chainLevels -= 1;
+        if (ctx.chainLevels === 0) {
+          pool.push(ctx);
+        }
+      });
     factoryPromise.then(settle, settle);
     return factoryPromise;
   }
 
+  #acquireAsyncChainContext(
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): DefaultResolutionContext {
+    const pooled = this.#asyncChainContextPool.pop();
+    if (pooled === undefined) {
+      return new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+    }
+    pooled.reset(this, resolutionPath, resolutionStack, undefined);
+    return pooled;
+  }
+
   #resolveCandidateSync<const Value>(
     binding: Binding<Value>,
     options: ResolveOptions | undefined,
@@ -1603,8 +1443,8 @@ export class DependencyResolver {
       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 === "singleton" && binding.instance !== NO_INSTANCE) {
+      return binding.instance as Value;
     }
     if (scope === "scoped") {
       if (!this.#scope.isChild) {
@@ -1636,8 +1476,8 @@ export class DependencyResolver {
       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 === "singleton" && binding.instance !== NO_INSTANCE) {
+      return Promise.resolve(binding.instance as Value);
     }
     if (scope === "scoped") {
       if (!this.#scope.isChild) {
@@ -1664,70 +1504,6 @@ export class DependencyResolver {
     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";
   }
@@ -1740,15 +1516,10 @@ export class DependencyResolver {
     const depth = resolutionStack.length;
     const existing = this.#syncResolutionContextPool[depth];
     if (existing !== undefined) {
-      existing.reset(this as unknown as ResolverCallbacks, resolutionPath, resolutionStack, options);
+      existing.reset(this, resolutionPath, resolutionStack, options);
       return existing;
     }
-    const created = new DefaultResolutionContext(
-      this as unknown as ResolverCallbacks,
-      resolutionPath,
-      resolutionStack,
-      options,
-    );
+    const created = new DefaultResolutionContext(this, resolutionPath, resolutionStack, options);
     this.#syncResolutionContextPool[depth] = created;
     return created;
   }