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

package/dist/resolution/resolver.js

@@ -1,14 +1,14 @@
+import { NO_INSTANCE } from "#/binding";
 import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#/errors";
+import { ActivationNeedCache } from "#/resolution/activation-need";
+import { BindingLookupCache } from "#/resolution/binding-lookup-cache";
 import { selectAllBindings, selectBinding } from "#/resolution/binding-select";
-import { buildResolutionFrame, DefaultResolutionContext, runWithContainer } from "#/resolution/environment";
+import { ClassIntrospector } from "#/resolution/class-introspector";
+import { buildResolutionFrame, DefaultResolutionContext } from "#/resolution/environment";
 import { InstantiationPlanCompiler, PLAN_RETRY } from "#/resolution/instantiation-plan";
 import { enterResolutionPath, exitResolutionPath } from "#/resolution/resolution-path";
 import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
-import { SINGLETON_MISS } from "#/resolution/scope";
 import { tokenName } from "#/token";
-// 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;
 const EMPTY_STRING_LIST = [];
 const EMPTY_FRAME_LIST = [];
 const ROOT_CONSTRAINT_CONTEXT = {
@@ -23,51 +23,10 @@ const ROOT_CONSTRAINT_CONTEXT = {
  */
 export class DependencyResolver {
     #syncResolutionContextPool = [];
-    // 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;
-    #asyncChainCtxPath;
-    #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;
-    #classHasPostConstruct = new WeakMap();
-    #classNeedsActiveContainer = new WeakMap();
-    #classConstructorMetadata = new WeakMap();
-    #activationNeedByBindingId = new Map();
-    #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).
-    #defaultLookupByToken = new Map();
-    #defaultLookupVersion = -1;
-    // Name-only lookup memo (token → name → entry) with the same chain-version
-    // invalidation. `null` = shape needs the full selection path.
-    #namedLookupByToken = new Map();
-    #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.
+    #asyncChainContextPool = [];
+    // Compiled plans; `null` marks a binding as unplannable under the current cache versions.
     #classPlanByBindingId = new Map();
     #classPlanRegistryVersion = -1;
     #classPlanActivationVersion = -1;
@@ -75,15 +34,33 @@ export class DependencyResolver {
     #scope;
     #lifecycle;
     #metadataReader;
-    #container;
     #parent;
+    #lookup;
+    #classes;
+    #activation;
     constructor(registry, scope, lifecycle, metadataReader, container, parent) {
         this.#registry = registry;
         this.#scope = scope;
         this.#lifecycle = lifecycle;
         this.#metadataReader = metadataReader;
-        this.#container = container;
         this.#parent = parent;
+        this.#lookup = new BindingLookupCache(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() {
+        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 ─────────────────────────────────────────────────────────
     #findBinding(token, options, resolutionPath, resolutionStack) {
@@ -161,7 +138,7 @@ export class DependencyResolver {
         if (fastBinding !== undefined && fastBinding.kind !== "alias") {
             return this.#resolveDefaultEntry(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);
         }
@@ -191,8 +168,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;
             }
             if (owner !== this) {
@@ -248,83 +225,8 @@ export class DependencyResolver {
             resolutionSet?.delete(tokenDisplayName);
         }
     }
-    #chainRegistryVersion() {
-        let version = this.#registry.version;
-        for (let resolver = this.#parent; resolver !== undefined; resolver = resolver.#parent) {
-            version += resolver.#registry.version;
-        }
-        return version;
-    }
-    #lookupDefaultEntry(token) {
-        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) {
-        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, name) {
-        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());
-        let entry = entriesByName.get(name);
-        if (entry === undefined) {
-            entry = this.#findNamedEntryInChain(token, name);
-            entriesByName.set(name, entry);
-        }
-        return entry;
-    }
-    #findNamedEntryInChain(token, name) {
-        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) {
-        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) {
-        const registryVersion = this.#chainRegistryVersion();
+        const registryVersion = this.#lookup.chainVersion();
         const activationVersion = this.#lifecycle.activationVersion;
         if (registryVersion !== this.#classPlanRegistryVersion || activationVersion !== this.#classPlanActivationVersion) {
             this.#classPlanByBindingId.clear();
@@ -346,22 +248,28 @@ export class DependencyResolver {
     // Compiler behind #getClassPlan — cold path, so the host indirection costs nothing hot.
     #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(token, options, resolutionPath, resolutionStack) {
         // Name-only fast lane: memoized lookup, dispatching just the shapes whose
@@ -370,7 +278,7 @@ export class DependencyResolver {
             options.name !== undefined &&
             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 (namedBinding.kind === "constant" &&
@@ -380,9 +288,8 @@ export class DependencyResolver {
                 }
                 const namedScope = namedBinding.scope ?? "transient";
                 if (namedScope === "singleton") {
-                    const cachedSingleton = namedEntry.owner.#scope.peekSingleton(namedBinding.id);
-                    if (cachedSingleton !== SINGLETON_MISS) {
-                        return cachedSingleton;
+                    if (namedBinding.instance !== NO_INSTANCE) {
+                        return namedBinding.instance;
                     }
                 }
                 // Everything else keeps the full path (context, activation, guards).
@@ -427,10 +334,8 @@ export class DependencyResolver {
         }
         const scope = binding.scope ?? "transient";
         // Singleton cache check
-        if (scope === "singleton") {
-            if (this.#scope.hasSingleton(binding.id)) {
-                return this.#scope.getSingleton(binding.id);
-            }
+        if (scope === "singleton" && binding.instance !== NO_INSTANCE) {
+            return binding.instance;
         }
         // Scoped cache check
         if (scope === "scoped") {
@@ -445,7 +350,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 {
@@ -471,13 +376,13 @@ export class DependencyResolver {
                 ? this.#acquireSyncResolutionContext(resolutionPath, resolutionStack, options)
                 : undefined;
             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, binding, instance, this.#metadataReader)
                 : instance;
             // 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);
@@ -508,7 +413,7 @@ export class DependencyResolver {
                 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);
+                const instance = this.#classes.instantiate(binding.target, deps);
                 return instance;
             }
             case "resolved": {
@@ -526,7 +431,7 @@ export class DependencyResolver {
         }
     }
     #resolveClassDeps(target, resolutionPath, resolutionStack) {
-        const meta = this.#getConstructorMetadata(target);
+        const meta = this.#classes.constructorMetadata(target);
         if (meta === undefined) {
             if (target.length === 0) {
                 return [];
@@ -620,7 +525,7 @@ export class DependencyResolver {
         return resolved;
     }
     // ── Async resolve ──────────────────────────────────────────────────────────
-    resolveAsyncFromContext(token, resolutionPath, resolutionStack) {
+    resolveAsyncFromContext(token, resolutionPath, resolutionStack, callerContext) {
         // 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);
@@ -630,17 +535,17 @@ export class DependencyResolver {
                 fastBinding.scope === "transient" &&
                 fastBinding.onActivation === undefined &&
                 (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(fastBinding.token))) {
-                return this.#resolveTransientDynamicAsyncFromContext(fastBinding, resolutionPath, resolutionStack);
+                return this.#resolveTransientDynamicAsyncFromContext(fastBinding, resolutionPath, resolutionStack, callerContext);
             }
-            return this.#resolveAsyncDefaultEntry(fastBinding, this, resolutionPath, resolutionStack);
+            return this.#resolveAsyncDefaultEntry(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(entry.binding, entry.owner, resolutionPath, resolutionStack);
+        return this.#resolveAsyncDefaultEntry(entry.binding, entry.owner, resolutionPath, resolutionStack, callerContext);
     }
-    #resolveAsyncDefaultEntry(binding, owner, resolutionPath, resolutionStack) {
+    #resolveAsyncDefaultEntry(binding, owner, resolutionPath, resolutionStack, callerContext) {
         if (binding.kind === "constant" &&
             binding.onActivation === undefined &&
             (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))) {
@@ -651,13 +556,12 @@ export class DependencyResolver {
             if ((binding.kind === "dynamic" || binding.kind === "dynamic-async") &&
                 binding.onActivation === undefined &&
                 (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))) {
-                return this.#resolveTransientDynamicAsyncFromContext(binding, resolutionPath, resolutionStack);
+                return this.#resolveTransientDynamicAsyncFromContext(binding, resolutionPath, resolutionStack, callerContext);
             }
         }
         else if (scope === "singleton") {
-            const cachedSingleton = owner.#scope.peekSingleton(binding.id);
-            if (cachedSingleton !== SINGLETON_MISS) {
-                return Promise.resolve(cachedSingleton);
+            if (binding.instance !== NO_INSTANCE) {
+                return Promise.resolve(binding.instance);
             }
             if (owner !== this) {
                 return owner.#resolveBindingAsync(binding, undefined, resolutionPath, resolutionStack);
@@ -718,8 +622,8 @@ export class DependencyResolver {
         const scope = binding.scope ?? "transient";
         // Singleton cache
         if (scope === "singleton") {
-            if (this.#scope.hasSingleton(binding.id)) {
-                return this.#scope.getSingleton(binding.id);
+            if (binding.instance !== NO_INSTANCE) {
+                return binding.instance;
             }
             // In-flight dedup
             const inflight = this.#scope.getInflight(binding.id);
@@ -740,7 +644,7 @@ 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, resolutionPath, resolutionStack, options);
             try {
@@ -764,11 +668,12 @@ export class DependencyResolver {
             if (scope === "singleton") {
                 const createSingletonPromise = async () => {
                     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, binding, instance, this.#metadataReader)
                         : instance;
-                    this.#scope.setSingleton(binding.id, activated);
+                    this.#scope.setSingleton(binding, activated);
+                    binding.instance = activated;
                     this.#scope.clearInflight(binding.id);
                     return activated;
                 };
@@ -780,7 +685,7 @@ export class DependencyResolver {
                 return await singletonPromise;
             }
             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, binding, instance, this.#metadataReader)
                 : instance;
@@ -813,7 +718,7 @@ export class DependencyResolver {
                 return binding.factory(ctx);
             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;
             }
             case "resolved": {
@@ -833,7 +738,7 @@ export class DependencyResolver {
         }
     }
     async #resolveClassDepsAsync(target, resolutionPath, resolutionStack) {
-        const meta = this.#getConstructorMetadata(target);
+        const meta = this.#classes.constructorMetadata(target);
         if (meta === undefined) {
             if (target.length === 0) {
                 return [];
@@ -1022,28 +927,6 @@ export class DependencyResolver {
     #getTokenName(token) {
         return tokenName(token);
     }
-    #getConstructorMetadata(target) {
-        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, deps) {
-        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;
-        if (!needsActiveContainer) {
-            return new invokable(...deps);
-        }
-        return runWithContainer(this.#container, () => new invokable(...deps));
-    }
     #matchesRequestedTag(tagKey, tagValue, requestedTags, singleRequestedTag) {
         if (singleRequestedTag !== undefined &&
             singleRequestedTag[0] === tagKey &&
@@ -1062,10 +945,7 @@ export class DependencyResolver {
         return false;
     }
     #resolveTransientDynamicSyncFromContext(binding, resolutionPath, resolutionStack) {
-        // 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) {
@@ -1088,19 +968,10 @@ export class DependencyResolver {
             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(binding, resolutionPath, resolutionStack) {
-        // 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.
+    // Deliberately not `async`: that would allocate a state machine and a promise per level.
+    #resolveTransientDynamicAsyncFromContext(binding, resolutionPath, resolutionStack, callerContext) {
+        // 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 {
@@ -1110,32 +981,12 @@ export class DependencyResolver {
             // This method is not `async`; keep failures as rejections rather than sync throws.
             return Promise.reject(cycleError);
         }
-        let ctx;
-        let isOwnerLevel;
-        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, resolutionPath, resolutionStack, undefined);
-                this.#asyncChainCtx = ctx;
-            }
-            else {
-                existing.reset(this, resolutionPath, resolutionStack, undefined);
-                ctx = existing;
-            }
-            this.#asyncChainCtxPath = resolutionPath;
-            isOwnerLevel = true;
-        }
-        else {
-            ctx = new DefaultResolutionContext(this, 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;
         try {
@@ -1151,40 +1002,33 @@ 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;
-        if (isOwnerLevel) {
-            settle =
-                this.#asyncChainSettle ??
-                    (this.#asyncChainSettle = () => {
-                        exitResolutionPath(resolutionPath);
-                        if (--this.#asyncChainActiveLevels === 0) {
-                            this.#asyncChainCtxPath = undefined;
-                            this.#asyncChainSettle = undefined;
-                        }
-                    });
-        }
-        else {
-            settle = () => {
+        // 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 = () => {
                 exitResolutionPath(resolutionPath);
-            };
-        }
+                ctx.chainLevels -= 1;
+                if (ctx.chainLevels === 0) {
+                    pool.push(ctx);
+                }
+            });
         factoryPromise.then(settle, settle);
         return factoryPromise;
     }
+    #acquireAsyncChainContext(resolutionPath, resolutionStack) {
+        const pooled = this.#asyncChainContextPool.pop();
+        if (pooled === undefined) {
+            return new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+        }
+        pooled.reset(this, resolutionPath, resolutionStack, undefined);
+        return pooled;
+    }
     #resolveCandidateSync(binding, options, resolutionPath, resolutionStack) {
         if (binding.kind === "constant" &&
             binding.onActivation === undefined &&
@@ -1195,8 +1039,8 @@ export class DependencyResolver {
             return this.resolve(binding.target, options, resolutionPath, resolutionStack);
         }
         const scope = binding.scope ?? "transient";
-        if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
-            return this.#scope.getSingleton(binding.id);
+        if (scope === "singleton" && binding.instance !== NO_INSTANCE) {
+            return binding.instance;
         }
         if (scope === "scoped") {
             if (!this.#scope.isChild) {
@@ -1220,8 +1064,8 @@ export class DependencyResolver {
             return this.resolveAsync(binding.target, options, isolatedPath, isolatedStack);
         }
         const scope = binding.scope ?? "transient";
-        if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
-            return Promise.resolve(this.#scope.getSingleton(binding.id));
+        if (scope === "singleton" && binding.instance !== NO_INSTANCE) {
+            return Promise.resolve(binding.instance);
         }
         if (scope === "scoped") {
             if (!this.#scope.isChild) {
@@ -1246,62 +1090,6 @@ export class DependencyResolver {
         binding.frame = frame;
         return frame;
     }
-    #needsActivation(binding) {
-        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) {
-        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(binding, needsActivation) {
-        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(binding) {
         return binding.kind === "dynamic" || binding.kind === "dynamic-async";
     }