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

package/dist/resolution/resolver.js

@@ -0,0 +1,1320 @@
+import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#/errors";
+import { selectAllBindings, selectBinding } from "#/resolution/binding-select";
+import { buildResolutionFrame, DefaultResolutionContext, runWithContainer } 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 = {
+    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 {
+    #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.
+    #classPlanByBindingId = new Map();
+    #classPlanRegistryVersion = -1;
+    #classPlanActivationVersion = -1;
+    #registry;
+    #scope;
+    #lifecycle;
+    #metadataReader;
+    #container;
+    #parent;
+    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;
+    }
+    // ── Binding lookup ─────────────────────────────────────────────────────────
+    #findBinding(token, options, resolutionPath, resolutionStack) {
+        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, options) {
+        return this.#findBinding(token, options, [], []);
+    }
+    /**
+     * Mirrors {@link DependencyResolver.resolveAll} candidate selection only (no instantiation).
+     */
+    peekCandidateBindingsForValidate(token, options) {
+        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(token, resolutionPath, resolutionStack) {
+        // 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(fastBinding, this, resolutionPath, resolutionStack);
+        }
+        const entry = this.#lookupDefaultEntry(token);
+        if (entry === null) {
+            return this.resolve(token, undefined, resolutionPath, resolutionStack);
+        }
+        return this.#resolveDefaultEntry(entry.binding, entry.owner, resolutionPath, resolutionStack);
+    }
+    #resolveDefaultEntry(binding, owner, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))) {
+            return binding.value;
+        }
+        const scope = binding.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, resolutionPath, resolutionStack);
+                }
+                return this.#resolveTransientDynamicActivatedSync(binding, 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();
+                }
+            }
+        }
+        else if (scope === "singleton") {
+            const cachedSingleton = owner.#scope.peekSingleton(binding.id);
+            if (cachedSingleton !== SINGLETON_MISS) {
+                return cachedSingleton;
+            }
+            if (owner !== this) {
+                return owner.#resolveBinding(binding, 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(binding.id);
+            }
+        }
+        return this.#resolveBinding(binding, 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(binding, containerHooks, resolutionPath, resolutionStack) {
+        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;
+                }
+            }
+            return activated;
+        }
+        finally {
+            resolutionStack.pop();
+            resolutionPath.pop();
+            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 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.
+    #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(token, options, resolutionPath, resolutionStack) {
+        // 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;
+                }
+                const namedScope = namedBinding.scope ?? "transient";
+                if (namedScope === "singleton") {
+                    const cachedSingleton = namedEntry.owner.#scope.peekSingleton(namedBinding.id);
+                    if (cachedSingleton !== SINGLETON_MISS) {
+                        return cachedSingleton;
+                    }
+                }
+                // Everything else keeps the full path (context, activation, guards).
+            }
+        }
+        let currentToken = token;
+        let visitedAliasTokens;
+        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.scope ?? "transient";
+        // Singleton from a parent resolver: delegate so the parent caches it correctly
+        if (scope === "singleton" && owner !== this) {
+            return owner.#resolveBinding(binding, options, resolutionPath, resolutionStack);
+        }
+        // Scoped/transient (or own singleton): resolve with this resolver's container/scope
+        return this.#resolveBinding(binding, options, resolutionPath, resolutionStack);
+    }
+    #resolveBinding(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))) {
+            return binding.value;
+        }
+        const scope = binding.scope ?? "transient";
+        // Singleton cache check
+        if (scope === "singleton") {
+            if (this.#scope.hasSingleton(binding.id)) {
+                return this.#scope.getSingleton(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(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, 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(binding, ctx, resolutionPath, resolutionStack) {
+        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;
+            }
+            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, resolutionPath, resolutionStack) {
+        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(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, resolutionPath, resolutionStack) {
+        const resolved = new Array(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, depOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            if (dep.optional) {
+                resolved[index] = this.resolveOptional(dep.token, depOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            resolved[index] =
+                depOptions === undefined
+                    ? this.resolveFromContext(dep.token, resolutionPath, resolutionStack)
+                    : this.resolve(dep.token, depOptions, resolutionPath, resolutionStack);
+        }
+        return resolved;
+    }
+    resolveOptional(token, options, resolutionPath, resolutionStack) {
+        if (this.#findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+            return undefined;
+        }
+        return this.resolve(token, options, resolutionPath, resolutionStack);
+    }
+    resolveAll(token, options, resolutionPath, resolutionStack) {
+        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(namedCandidates.length);
+            for (let index = 0; index < namedCandidates.length; index += 1) {
+                resolved[index] = this.#resolveCandidateSync(namedCandidates[index], 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(candidates.length);
+        for (let index = 0; index < candidates.length; index += 1) {
+            resolved[index] = this.#resolveCandidateSync(candidates[index], options, resolutionPath, resolutionStack);
+        }
+        return resolved;
+    }
+    // ── Async resolve ──────────────────────────────────────────────────────────
+    resolveAsyncFromContext(token, resolutionPath, resolutionStack) {
+        // 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, resolutionPath, resolutionStack);
+            }
+            return this.#resolveAsyncDefaultEntry(fastBinding, this, resolutionPath, resolutionStack);
+        }
+        const entry = this.#lookupDefaultEntry(token);
+        if (entry === null) {
+            return this.resolveAsync(token, undefined, resolutionPath, resolutionStack);
+        }
+        return this.#resolveAsyncDefaultEntry(entry.binding, entry.owner, resolutionPath, resolutionStack);
+    }
+    #resolveAsyncDefaultEntry(binding, owner, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            (this.#lifecycle.activationVersion === 0 || !this.#lifecycle.hasActivationHandlers(binding.token))) {
+            return Promise.resolve(binding.value);
+        }
+        const scope = binding.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, resolutionPath, resolutionStack);
+            }
+        }
+        else if (scope === "singleton") {
+            const cachedSingleton = owner.#scope.peekSingleton(binding.id);
+            if (cachedSingleton !== SINGLETON_MISS) {
+                return Promise.resolve(cachedSingleton);
+            }
+            if (owner !== this) {
+                return owner.#resolveBindingAsync(binding, 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(binding.id));
+            }
+        }
+        return this.#resolveBindingAsync(binding, undefined, resolutionPath, resolutionStack);
+    }
+    async resolveAsync(token, options, resolutionPath, resolutionStack) {
+        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;
+        let visitedAliasTokens;
+        let aliasFollowed = 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.scope ?? "transient";
+        if (scope === "singleton" && owner !== this) {
+            return owner.#resolveBindingAsync(binding, options, resolutionPath, resolutionStack);
+        }
+        return this.#resolveBindingAsync(binding, options, resolutionPath, resolutionStack);
+    }
+    async #resolveBindingAsync(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            !this.#lifecycle.hasActivationHandlers(binding.token)) {
+            return binding.value;
+        }
+        const scope = binding.scope ?? "transient";
+        // Singleton cache
+        if (scope === "singleton") {
+            if (this.#scope.hasSingleton(binding.id)) {
+                return this.#scope.getSingleton(binding.id);
+            }
+            // In-flight dedup
+            const inflight = this.#scope.getInflight(binding.id);
+            if (inflight !== undefined) {
+                return inflight;
+            }
+        }
+        // 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(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, 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, resolutionPath, resolutionStack, options)
+            : undefined;
+        try {
+            if (scope === "singleton") {
+                const createSingletonPromise = async () => {
+                    const instance = await this.#instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
+                    const shouldActivate = this.#refreshActivationCacheIfNeeded(binding, needsActivation);
+                    const activated = shouldActivate
+                        ? await this.#lifecycle.runActivation(resolutionCtx, binding, instance, this.#metadataReader)
+                        : instance;
+                    this.#scope.setSingleton(binding.id, activated);
+                    this.#scope.clearInflight(binding.id);
+                    return activated;
+                };
+                const singletonPromise = createSingletonPromise().catch((err) => {
+                    this.#scope.clearInflight(binding.id);
+                    throw err;
+                });
+                this.#scope.setInflight(binding.id, singletonPromise);
+                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, 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(binding, ctx, resolutionPath, resolutionStack) {
+        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;
+            }
+            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, resolutionPath, resolutionStack) {
+        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(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, resolutionPath, resolutionStack) {
+        const pending = new Array(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, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else if (dep.optional) {
+                pending[index] = this.resolveOptionalAsync(dep.token, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else {
+                pending[index] =
+                    depOptions === undefined
+                        ? this.resolveAsyncFromContext(dep.token, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack)
+                        : this.resolveAsync(dep.token, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+        }
+        return Promise.all(pending);
+    }
+    async resolveOptionalAsync(token, options, resolutionPath, resolutionStack) {
+        if (this.#findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+            return undefined;
+        }
+        return this.resolveAsync(token, options, resolutionPath, resolutionStack);
+    }
+    async resolveAllAsync(token, options, resolutionPath, resolutionStack) {
+        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(namedCandidates.length);
+            for (let index = 0; index < namedCandidates.length; index += 1) {
+                pending[index] = this.#resolveCandidateAsync(namedCandidates[index], 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(candidates.length);
+        for (let index = 0; index < candidates.length; index += 1) {
+            pending[index] = this.#resolveCandidateAsync(candidates[index], options, resolutionPath, resolutionStack);
+        }
+        return Promise.all(pending);
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    #getAllBindingsFromChain(token) {
+        const ownBindings = this.#registry.getAll(token);
+        if (this.#parent === undefined) {
+            return ownBindings;
+        }
+        const result = [...ownBindings];
+        let current = 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, name) {
+        const ownBinding = this.#registry.getSimpleNamed(token, name);
+        if (this.#parent === undefined) {
+            return ownBinding !== undefined ? [ownBinding] : [];
+        }
+        const result = [];
+        if (ownBinding !== undefined) {
+            result.push(ownBinding);
+        }
+        let current = 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) {
+        return this.#registry.availableSlotStrings(token);
+    }
+    #makeConstraintContext(resolutionPath, resolutionStack, options) {
+        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, options, resolutionPath, resolutionStack) {
+        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, options) {
+        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) {
+        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 &&
+            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(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.
+        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(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.
+        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;
+        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++;
+        }
+        // Invoke the factory synchronously to get its Promise (or a resolved value for "dynamic").
+        let factoryPromise;
+        try {
+            if (binding.kind === "dynamic-async") {
+                factoryPromise = binding.factory(ctx);
+            }
+            else {
+                const factoryResult = binding.factory(ctx);
+                factoryPromise =
+                    factoryResult instanceof Promise ? factoryResult : 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;
+        if (isOwnerLevel) {
+            settle =
+                this.#asyncChainSettle ??
+                    (this.#asyncChainSettle = () => {
+                        exitResolutionPath(resolutionPath);
+                        if (--this.#asyncChainActiveLevels === 0) {
+                            this.#asyncChainCtxPath = undefined;
+                            this.#asyncChainSettle = undefined;
+                        }
+                    });
+        }
+        else {
+            settle = () => {
+                exitResolutionPath(resolutionPath);
+            };
+        }
+        factoryPromise.then(settle, settle);
+        return factoryPromise;
+    }
+    #resolveCandidateSync(binding, options, resolutionPath, resolutionStack) {
+        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.scope ?? "transient";
+        if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
+            return this.#scope.getSingleton(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(binding.id);
+            }
+        }
+        return this.#resolveBinding(binding, options, resolutionPath, resolutionStack);
+    }
+    #resolveCandidateAsync(binding, options, resolutionPath, resolutionStack) {
+        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.scope ?? "transient";
+        if (scope === "singleton" && this.#scope.hasSingleton(binding.id)) {
+            return Promise.resolve(this.#scope.getSingleton(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(binding.id));
+            }
+        }
+        return this.#resolveBindingAsync(binding, options, isolatedPath, isolatedStack);
+    }
+    #getResolutionFrame(binding) {
+        // 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.scope ?? "transient";
+        const frame = buildResolutionFrame(tokenName(binding.token), scope, binding.id, binding.kind, binding.slot);
+        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";
+    }
+    #acquireSyncResolutionContext(resolutionPath, resolutionStack, options) {
+        const depth = resolutionStack.length;
+        const existing = this.#syncResolutionContextPool[depth];
+        if (existing !== undefined) {
+            existing.reset(this, resolutionPath, resolutionStack, options);
+            return existing;
+        }
+        const created = new DefaultResolutionContext(this, resolutionPath, resolutionStack, options);
+        this.#syncResolutionContextPool[depth] = created;
+        return created;
+    }
+}
+//# sourceMappingURL=resolver.js.map