@codefast/di 0.11.0 → 0.13.0

package/dist/resolution/resolver.js

@@ -1,19 +1,21 @@
 import { bindingSlotToString, NO_INSTANCE } from "#core/binding";
 import { slotNameCriterionOf } from "#core/tag";
 import { tokenName } from "#core/token";
-import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, DisposedContainerError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#errors/errors";
-import { loneTagBesideNameOf, resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf, } from "#injection/resolve-options";
-import { SCOPED_MISS } from "#lifecycle/scope-manager";
+import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, DisposedContainerError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#errors";
+import { loneTagBesideNameOf, resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf, } from "#injection/dependency-slot";
+import { SCOPED_MISS } from "#lifecycle/scopes";
 import { settleInOrder } from "#resolution/async-fan-out";
 import { ActivationNeedCache } from "#resolution/cache/activation-need";
-import { BindingLookupCache } from "#resolution/cache/binding-lookup-cache";
 import { ClassIntrospector } from "#resolution/cache/class-introspector";
+import { BindingLookupCache } from "#resolution/cache/lookup";
 import { AsyncLevelContext, DefaultConstraintContext, DefaultResolutionContext } from "#resolution/context";
-import { branchDepthOf, buildResolutionFrame, cycleNamesOf, enterSyncPath, extendResolutionBranch, leaveSyncPath, ROOT_BRANCH, UNOWNED_BRANCH, } from "#resolution/path/resolution-path";
-import { InstantiationPlanCompiler, PLAN_RETRY } from "#resolution/plan/instantiation-plan";
-import { matchesSlot, selectAllBindings, selectBinding } from "#resolution/select/binding-select";
+import { branchDepthOf, buildResolutionFrame, cycleNamesOf, enterSyncPath, extendResolutionBranch, leaveSyncPath, missPathOf, ROOT_BRANCH, UNOWNED_BRANCH, } from "#resolution/path";
+import { InstantiationPlanCompiler, PLAN_RETRY } from "#resolution/plan/compiler";
+import { matchesSlot, selectAllBindings, selectBinding } from "#resolution/select/candidates";
 const EMPTY_FRAME_LIST = [];
 const EMPTY_PARAM_LIST = [];
+// A class with no params is constructed with no arguments, so no dependency array is built for it.
+const NO_ARGUMENTS = [];
 /** Plans compiled so far, with the `null` unplannable marks left out. */
 function countCompiledPlans(plans) {
     let count = 0;
@@ -190,9 +192,9 @@ export class DependencyResolver {
      * can answer still does.
      */
     #forwardingAliasOrParent(token, options, resolutionStack, singleCriterion) {
-        const defaultSlot = this.#registry.getDefaultSlotBinding(token);
-        if (defaultSlot !== undefined && defaultSlot.kind === "alias") {
-            return { binding: defaultSlot, owner: this };
+        const defaultSlotAlias = this.#registry.defaultSlotAlias(token);
+        if (defaultSlotAlias !== undefined) {
+            return { binding: defaultSlotAlias, owner: this };
         }
         return this.#parent === undefined
             ? undefined
@@ -250,10 +252,11 @@ export class DependencyResolver {
             // dominated by that capture. Bindings under the token anywhere in the chain mean the request
             // matched none of them, so a child reports the same miss its parent would.
             const bound = this.#allBindingsFromChain(currentToken);
+            const path = missPathOf(resolutionStack, token, visitedAliasTokens);
             if (bound.length > 0) {
-                throw new NoMatchingBindingError(tokenName(currentToken), options ?? {}, bound.map((binding) => bindingSlotToString(binding.slot)));
+                throw new NoMatchingBindingError(tokenName(currentToken), options ?? {}, bound.map((binding) => bindingSlotToString(binding.slot)), path);
             }
-            throw new TokenNotBoundError(tokenName(currentToken));
+            throw new TokenNotBoundError(tokenName(currentToken), path);
         }
         return found;
     }
@@ -293,6 +296,36 @@ export class DependencyResolver {
     peekCandidateBindingsForValidate(token, options) {
         return this.#candidateBindings(token, options, []);
     }
+    /**
+     * The error `resolve` raises for a request nothing selects, or `undefined` while a `when()` candidate leaves it open.
+     *
+     * @remarks A predicate reads the resolution path, which a static walk does not have, so a slot-matching candidate
+     * that carries one may still be selected when the request is really made.
+     */
+    missForValidate(token, options, path) {
+        const bound = this.#allBindingsFromChain(token);
+        if (bound.length === 0) {
+            return new TokenNotBoundError(tokenName(token), path);
+        }
+        for (const binding of bound) {
+            if (binding.predicate !== undefined && !binding.isMany && matchesSlot(binding.slot, options)) {
+                return undefined;
+            }
+        }
+        return new NoMatchingBindingError(tokenName(token), options ?? {}, bound.map((binding) => bindingSlotToString(binding.slot)), path);
+    }
+    /** The resolver whose chain a binding this one can see resolves its dependencies from, as a singleton does. */
+    ownerForValidate(binding) {
+        return this.#ownerOf(binding);
+    }
+    /** Deactivates a scoped instance of a binding this resolver owns, with its hooks and reader, when it owes a teardown. */
+    deactivateScoped(binding, instance) {
+        const lifecycle = this.#lifecycle;
+        const reader = this.#metadataReader;
+        return lifecycle.owesDeactivation(binding, reader)
+            ? lifecycle.runDeactivation(binding, instance, reader)
+            : undefined;
+    }
     // ── Sync resolve ───────────────────────────────────────────────────────────────────────────────────────────────────
     resolveFromContext(token, resolutionStack) {
         // Hot lane: own-registry fast default. Fall back to the chain-versioned memo
@@ -514,7 +547,7 @@ export class DependencyResolver {
                 }
                 return this.resolve(token, options, resolutionStack);
             },
-            // Dispatches exactly as #resolveDepAsync does, for the async lane's escapes.
+            // Dispatches exactly as #settleDep does, for the async lane's escapes.
             resolveEscapedAsync: (token, options, arity, resolutionStack) => {
                 if (arity === "all") {
                     return this.resolveAllAsync(token, options, resolutionStack, UNOWNED_BRANCH);
@@ -645,7 +678,7 @@ export class DependencyResolver {
                 this.#scope.setSingleton(binding, activated);
             }
             else if (scope === "scoped") {
-                this.#scope.setScoped(binding, activated);
+                this.#scope.setScoped(binding, activated, owner);
             }
             return activated;
         }
@@ -691,10 +724,13 @@ export class DependencyResolver {
             case "dynamic-async":
                 throw asyncResolutionErrorFor(binding, resolutionStack);
             case "class": {
-                const deps = this.#resolveDeps(this.#constructorParams(binding.target), resolutionStack);
-                return this.#introspector().instantiate(binding.target, deps, this.#introspector().needsActiveContainer(binding.target)
-                    ? this.#ambientResolutionFor(resolutionStack)
-                    : undefined);
+                // One lookup of the class's facts serves the params, the accessor need and the construction.
+                const introspector = this.#introspector();
+                const target = binding.target;
+                const facts = introspector.facts(target);
+                const params = this.#constructorParams(target, facts);
+                const needsActiveContainer = introspector.needsActiveContainerOf(target, facts);
+                return introspector.construct(target, params.length === 0 ? NO_ARGUMENTS : this.#resolveDeps(params, resolutionStack), needsActiveContainer, needsActiveContainer ? this.#ambientResolutionFor(resolutionStack) : undefined);
             }
             case "resolved": {
                 const deps = this.#resolveDeps(binding.deps, resolutionStack);
@@ -716,8 +752,12 @@ export class DependencyResolver {
      * @remarks A class the metadata reader knows nothing about is constructible only if it declares
      * no parameters; anything else is a missing `@injectable()`.
      */
-    #constructorParams(target) {
-        const meta = this.#introspector().constructorMetadata(target);
+    #constructorParams(target, facts) {
+        // Metadata is fixed once a class is defined, so the answer is too; only a throw is left unsettled.
+        return (facts.params ??= this.#settleConstructorParams(target, facts));
+    }
+    #settleConstructorParams(target, facts) {
+        const meta = this.#introspector().constructorMetadataOf(target, facts);
         if (meta !== undefined) {
             return meta.params;
         }
@@ -824,30 +864,35 @@ export class DependencyResolver {
         for (let index = 0; index < candidates.length; index += 1) {
             resolved[index] = this.#resolveCandidateSync(candidates[index], undefined, resolutionStack);
         }
-        // The members this read materialised may have made the list stable for the next one.
-        this.#settleCollectionValues(memo);
+        this.#settleOnRepeat(memo);
         return resolved;
     }
-    /** The async twin of `resolveRootCollection`: a stable value list settles at once, candidates fan out as usual. */
+    /** The async twin of `resolveRootCollection`: a stable value list answers at once, candidates fan out as usual. */
     resolveRootCollectionAsync(token) {
         // The async lane appends to its branch and never unwinds, so it works on a stack of its own.
         const resolutionStack = [];
-        const memo = this.#rootCollection(token, resolutionStack);
-        if (memo.values !== undefined && memo.activationVersion === this.#chainActivationVersion()) {
-            return Promise.resolve(memo.values.slice());
+        try {
+            // Selection runs `when()` predicates and follows aliases, either of which may throw.
+            const memo = this.#rootCollection(token, resolutionStack);
+            if (memo.values !== undefined && memo.activationVersion === this.#chainActivationVersion()) {
+                return Promise.resolve(memo.values.slice());
+            }
+            return asPromise(this.#settleCandidates(memo.candidates, undefined, resolutionStack, UNOWNED_BRANCH, (values) => {
+                this.#settleOnRepeat(memo);
+                return values;
+            }));
+        }
+        catch (collectionError) {
+            return Promise.reject(collectionError);
         }
-        return settleInOrder(memo.candidates.map((candidate) => this.#resolveCandidateAsync(candidate, undefined, resolutionStack, UNOWNED_BRANCH)), (values) => {
-            this.#settleCollectionValues(memo);
-            return values;
-        });
     }
     /**
      * The memoized candidate list of a root-level, options-less collection, built on its first read.
      *
      * @remarks Sound because a `when()` predicate is pure over its context and the root context is a
      * constant: the list can only change when a registry in the chain does, which is the version the
-     * memo is stamped with. The value list is kept too while every member is a hook-free constant
-     * and no activation hook exists anywhere in the chain.
+     * memo is stamped with. From the second read on, the value list is kept too while every member is
+     * a hook-free constant and no activation hook exists anywhere in the chain.
      */
     #rootCollection(token, resolutionStack) {
         const memo = this.#lookup.collection(token);
@@ -855,11 +900,20 @@ export class DependencyResolver {
             return memo;
         }
         const candidates = this.#candidateBindings(token, undefined, resolutionStack);
-        const entry = { candidates, values: undefined, activationVersion: -1 };
-        this.#settleCollectionValues(entry);
+        const entry = { candidates, values: undefined, activationVersion: -1, readBefore: false };
         this.#lookup.rememberCollection(token, entry);
         return entry;
     }
+    // The first read interprets and the read that repeats it settles the value list, as a plan compiles on repeat;
+    // the members either read materialised may have made the list stable for the next one.
+    #settleOnRepeat(entry) {
+        if (entry.readBefore) {
+            this.#settleCollectionValues(entry);
+        }
+        else {
+            entry.readBefore = true;
+        }
+    }
     /**
      * Fills a collection memo's value list once every member is stable: a hook-free constant, or a
      * hook-free singleton whose instance is cached — anything that changes either bumps a registry
@@ -894,6 +948,18 @@ export class DependencyResolver {
         const selected = selectAllBindings(allBindings, options, this.#makeConstraintContext(resolutionStack, options));
         return this.#withoutDanglingAliases(selected, options, resolutionStack);
     }
+    // A chain none of whose registries ever held an alias has none to drop, which spares the scan.
+    #chainHeldAlias() {
+        if (this.#registry.hasHeldAlias) {
+            return true;
+        }
+        for (let current = this.#parent; current !== undefined; current = current.#parent) {
+            if (current.#registry.hasHeldAlias) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * The candidates with any alias whose chain ends nowhere dropped, so a fan-out skips a dangling
      * alias rather than throwing on it.
@@ -902,6 +968,9 @@ export class DependencyResolver {
      * is returned untouched, so nothing is allocated for it.
      */
     #withoutDanglingAliases(candidates, options, resolutionStack) {
+        if (!this.#chainHeldAlias()) {
+            return candidates;
+        }
         let hasAlias = false;
         for (let index = 0; index < candidates.length; index += 1) {
             if (candidates[index].kind === "alias") {
@@ -936,35 +1005,55 @@ export class DependencyResolver {
         }
         return this.#resolveAsyncDefaultEntry(entry.binding, entry.owner, resolutionStack, branchDepth);
     }
+    // A `#settle*` lane answers with the value when its level completed in this tick and with a promise
+    // only where something had to be awaited, so a singleton or scoped instance built without yielding
+    // is cached before the fan-out that started it moves on to a sibling that may read it synchronously.
     #resolveAsyncDefaultEntry(binding, owner, resolutionStack, branchDepth) {
+        try {
+            return asPromise(this.#settleDefaultEntry(binding, owner, resolutionStack, branchDepth));
+        }
+        catch (entryError) {
+            // Not `async`: a failure is turned into the rejection the entry point promises.
+            return Promise.reject(entryError);
+        }
+    }
+    /** `resolveAsyncFromContext` for a dependency slot: the same lanes, answered in this tick where they can be. */
+    #settleDefault(token, resolutionStack, branchDepth) {
+        const fastBinding = this.#registry.getFastDefault(token);
+        if (fastBinding !== undefined && fastBinding.kind !== "alias") {
+            return this.#settleDefaultEntry(fastBinding, this, resolutionStack, branchDepth);
+        }
+        const entry = this.#lookup.defaultEntry(token);
+        if (entry === null) {
+            return this.#settleRequest(token, undefined, resolutionStack, branchDepth);
+        }
+        return this.#settleDefaultEntry(entry.binding, entry.owner, resolutionStack, branchDepth);
+    }
+    #settleDefaultEntry(binding, owner, resolutionStack, branchDepth) {
         if (owner.#isPlainConstant(binding)) {
-            return Promise.resolve(binding.value);
+            return binding.value;
         }
         const scope = binding.scope;
         if (scope === "transient") {
             if ((binding.kind === "dynamic" || binding.kind === "dynamic-async") && !owner.#hasAnyActivation(binding)) {
-                return this.#resolveTransientDynamicAsyncFromContext(binding, resolutionStack, branchDepth);
+                return this.#settleTransientFactory(binding, resolutionStack, branchDepth);
             }
         }
         else if (scope === "singleton") {
             if (binding.instance !== NO_INSTANCE) {
-                return Promise.resolve(binding.instance);
+                return binding.instance;
             }
             if (owner !== this) {
-                return owner.#resolveBindingAsync(binding, undefined, resolutionStack, branchDepth, owner);
+                return owner.#settleBinding(binding, undefined, resolutionStack, branchDepth, owner);
             }
         }
-        else if (this.#scope.isChild) {
-            const cachedScoped = this.#scope.readScoped(binding.identifier);
+        else {
+            const cachedScoped = this.#readScoped(binding);
             if (cachedScoped !== SCOPED_MISS) {
-                return Promise.resolve(cachedScoped);
+                return cachedScoped;
             }
         }
-        else {
-            // Not `#readScoped`: this entry point reports failure as a rejection, never a sync throw.
-            return Promise.reject(new MissingScopeContextError(tokenName(binding.token)));
-        }
-        return this.#resolveBindingAsync(binding, undefined, resolutionStack, branchDepth, owner);
+        return this.#settleBinding(binding, undefined, resolutionStack, branchDepth, owner);
     }
     /**
      * Instantiates one owned binding directly, bypassing selection.
@@ -973,18 +1062,38 @@ export class DependencyResolver {
      * could pick a different candidate whose criteria are a subset of them.
      */
     warmBindingAsync(binding, options) {
-        return this.#resolveBindingAsync(binding, options, [], ROOT_BRANCH, this);
+        try {
+            return asPromise(this.#settleBinding(binding, options, [], ROOT_BRANCH, this));
+        }
+        catch (bindingError) {
+            return Promise.reject(bindingError);
+        }
     }
-    async resolveAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+    resolveAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+        try {
+            return asPromise(this.#settleRequest(token, options, resolutionStack, branchDepth, precomputedCriterion));
+        }
+        catch (requestError) {
+            return Promise.reject(requestError);
+        }
+    }
+    /** Selects the binding a request names and settles it on the async lane. */
+    #settleRequest(token, options, resolutionStack, branchDepth, precomputedCriterion) {
         const path = ownPrefixOf(resolutionStack, branchDepth);
         const depth = path === resolutionStack ? branchDepth : branchDepthOf(path);
         const { binding, owner } = this.#requireBinding(token, options, path, precomputedCriterion);
         if (binding.scope === "singleton" && owner !== this) {
-            return owner.#resolveBindingAsync(binding, options, path, depth, owner);
+            return owner.#settleBinding(binding, options, path, depth, owner);
         }
-        return this.#resolveBindingAsync(binding, options, path, depth, owner);
+        return this.#settleBinding(binding, options, path, depth, owner);
     }
-    async #resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner) {
+    /**
+     * Materialises one binding on the async lane: the instance once nothing yielded, else its promise.
+     *
+     * @remarks A singleton or scoped instance built in this tick is cached in this tick, so a sibling
+     * reading it synchronously finds it; only a materialisation still pending is published in flight.
+     */
+    #settleBinding(binding, options, resolutionStack, branchDepth, owner) {
         if (owner.#isPlainConstant(binding)) {
             return binding.value;
         }
@@ -996,7 +1105,7 @@ export class DependencyResolver {
             // In-flight dedup: concurrent callers share the first creation.
             const inflight = this.#scope.getInflight(binding.identifier);
             if (inflight !== undefined) {
-                return inflight;
+                return ownPromiseOf(inflight);
             }
             if (this.#scope.isClosed) {
                 throw new DisposedContainerError();
@@ -1010,7 +1119,7 @@ export class DependencyResolver {
             // In-flight dedup, scoped flavor: one instance per scope even under concurrency.
             const inflight = this.#scope.getInflight(binding.identifier);
             if (inflight !== undefined) {
-                return inflight;
+                return ownPromiseOf(inflight);
             }
             if (this.#scope.isClosed) {
                 throw new DisposedContainerError();
@@ -1026,8 +1135,7 @@ export class DependencyResolver {
             if (branchDepth === ROOT_BRANCH) {
                 this.#recentRootLevelContext = resolutionCtx;
             }
-            const dynamicResult = runFactoryPrefix(binding, resolutionCtx, levelStack);
-            return dynamicResult instanceof Promise ? await dynamicResult : dynamicResult;
+            return runFactoryPrefix(binding, resolutionCtx, levelStack);
         }
         const resolutionCtx = needsActivation || requiresResolutionContext(binding)
             ? new AsyncLevelContext(this, levelStack, options)
@@ -1035,33 +1143,41 @@ export class DependencyResolver {
         if (resolutionCtx !== undefined && branchDepth === ROOT_BRANCH) {
             this.#recentRootLevelContext = resolutionCtx;
         }
+        const activated = this.#settleActivated(binding, resolutionCtx, levelStack, levelDepth, needsActivation, owner);
+        if (scope === "transient") {
+            return activated;
+        }
+        if (isPending(activated)) {
+            return this.#publishInFlight(binding, activated, scope, owner);
+        }
         if (scope === "singleton") {
-            // The promise is published before it settles, so concurrent callers dedup onto it.
-            const singletonPromise = this.#instantiateAndActivateAsync(binding, resolutionCtx, levelStack, levelDepth, needsActivation, owner).then((activated) => {
+            this.#scope.setSingleton(binding, activated);
+        }
+        else {
+            this.#scope.setScoped(binding, activated, owner);
+        }
+        return activated;
+    }
+    /**
+     * Publishes a pending singleton or scoped materialisation so concurrent callers dedup onto it,
+     * and caches what it settles to; the creator, like every joiner, is handed a promise of its own.
+     */
+    #publishInFlight(binding, pending, scope, owner) {
+        const published = pending.then((activated) => {
+            if (scope === "singleton") {
                 this.#scope.setSingleton(binding, activated);
-                this.#scope.clearInflight(binding.identifier);
-                return activated;
-            }, (error) => {
-                this.#scope.clearInflight(binding.identifier);
-                throw error;
-            });
-            this.#scope.setInflight(binding.identifier, singletonPromise);
-            return await singletonPromise;
-        }
-        if (scope === "scoped") {
-            // Published before it settles, like the singleton lane: concurrent callers share one creation.
-            const scopedPromise = this.#instantiateAndActivateAsync(binding, resolutionCtx, levelStack, levelDepth, needsActivation, owner).then((activated) => {
-                this.#scope.setScoped(binding, activated);
-                this.#scope.clearInflight(binding.identifier);
-                return activated;
-            }, (error) => {
-                this.#scope.clearInflight(binding.identifier);
-                throw error;
-            });
-            this.#scope.setInflight(binding.identifier, scopedPromise);
-            return await scopedPromise;
-        }
-        return await this.#instantiateAndActivateAsync(binding, resolutionCtx, levelStack, levelDepth, needsActivation, owner);
+            }
+            else {
+                this.#scope.setScoped(binding, activated, owner);
+            }
+            this.#scope.clearInflight(binding.identifier);
+            return activated;
+        }, (error) => {
+            this.#scope.clearInflight(binding.identifier);
+            throw error;
+        });
+        this.#scope.setInflight(binding.identifier, published);
+        return ownPromiseOf(published);
     }
     /**
      * Settles this resolver's own `postConstruct` answer for a class binding a parent owns.
@@ -1077,15 +1193,23 @@ export class DependencyResolver {
             this.#introspector().discoverPostConstruct(binding.target);
         }
     }
-    async #instantiateAndActivateAsync(binding, ctx, resolutionStack, branchDepth, needsActivation, owner) {
-        const instance = await this.#instantiateAsync(binding, ctx, resolutionStack, branchDepth);
+    /** The activated instance: built and activated in this tick when nothing yielded, else its promise. */
+    #settleActivated(binding, ctx, resolutionStack, branchDepth, needsActivation, owner) {
+        const instance = this.#settleInstance(binding, ctx, resolutionStack, branchDepth);
+        if (isPending(instance)) {
+            return instance.then((built) => this.#activateAsync(binding, ctx, built, needsActivation, owner));
+        }
+        return this.#activateAsync(binding, ctx, instance, needsActivation, owner);
+    }
+    #activateAsync(binding, ctx, instance, needsActivation, owner) {
         this.#mirrorPostConstructFromOwner(binding, owner);
         if (!owner.#activationNeed().refreshAfterFirstInstantiation(binding, needsActivation)) {
             return instance;
         }
         return owner.#lifecycle.runActivation(ctx, binding, instance, owner.#metadataReader);
     }
-    async #instantiateAsync(binding, ctx, resolutionStack, branchDepth) {
+    /** The instance a binding builds: in this tick when every dependency settled in it, else its promise. */
+    #settleInstance(binding, ctx, resolutionStack, branchDepth) {
         switch (binding.kind) {
             case "constant":
                 return binding.value;
@@ -1094,59 +1218,94 @@ export class DependencyResolver {
                 if (ctx === undefined) {
                     throw new InternalError("dynamic binding requires resolution context");
                 }
-                const factoryResult = runFactoryPrefix(binding, ctx, resolutionStack);
-                return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+                return runFactoryPrefix(binding, ctx, resolutionStack);
             }
             case "class": {
-                const deps = await this.#resolveDepsAsync(this.#constructorParams(binding.target), resolutionStack, branchDepth);
+                const introspector = this.#introspector();
+                const target = binding.target;
+                const facts = introspector.facts(target);
+                const params = this.#constructorParams(target, facts);
+                const needsActiveContainer = introspector.needsActiveContainerOf(target, facts);
                 // Accessor initializers resolve synchronously, so the branch-owned path serves them directly.
-                return this.#introspector().instantiate(binding.target, deps, this.#introspector().needsActiveContainer(binding.target)
-                    ? this.#ambientResolutionFor(resolutionStack)
-                    : undefined);
+                const ambient = needsActiveContainer ? this.#ambientResolutionFor(resolutionStack) : undefined;
+                if (params.length === 0) {
+                    return introspector.construct(target, NO_ARGUMENTS, needsActiveContainer, ambient);
+                }
+                const deps = this.#settleDeps(params, resolutionStack, branchDepth);
+                if (isPending(deps)) {
+                    return deps.then((settled) => introspector.construct(target, settled, needsActiveContainer, ambient));
+                }
+                return introspector.construct(target, deps, needsActiveContainer, ambient);
             }
             case "resolved": {
-                const deps = await this.#resolveDepsAsync(binding.deps, resolutionStack, branchDepth);
-                const factoryResult = binding.factory(...deps);
-                return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+                const factory = binding.factory;
+                const deps = this.#settleDeps(binding.deps, resolutionStack, branchDepth);
+                return isPending(deps) ? deps.then((settled) => factory(...settled)) : factory(...deps);
             }
             case "resolved-async": {
-                const deps = await this.#resolveDepsAsync(binding.deps, resolutionStack, branchDepth);
-                return binding.factory(...deps);
+                const factory = binding.factory;
+                const deps = this.#settleDeps(binding.deps, resolutionStack, branchDepth);
+                return isPending(deps) ? deps.then((settled) => factory(...settled)) : factory(...deps);
             }
             case "alias":
                 throw new InternalError("alias should have been followed before instantiation");
         }
     }
-    async #resolveDepsAsync(deps, resolutionStack, branchDepth) {
+    /**
+     * One level's dependencies: their values when every one settled in this tick, else the fan-out
+     * that settles them in declaration order.
+     */
+    #settleDeps(deps, resolutionStack, branchDepth) {
         const count = deps.length;
         if (count === 0) {
             return [];
         }
         if (count === 1) {
-            return [await this.#resolveDepAsync(deps[0], resolutionStack, branchDepth)];
+            const only = this.#settleDep(deps[0], resolutionStack, branchDepth);
+            return isPending(only) ? only.then(settledAlone) : [only];
         }
-        // Siblings resolve concurrently and each extends the same branch, so the first appends in
-        // place and the rest copy the prefix — no caller has to isolate them.
+        // Siblings start concurrently and each extends the same branch, so the first appends in
+        // place and the rest copy the prefix — no caller has to isolate them. A sibling's sync throw
+        // becomes its slot's rejection so the ones after it still start, as on every other lane.
         const pending = new Array(count);
+        let yielded = false;
         for (let index = 0; index < count; index += 1) {
-            pending[index] = this.#resolveDepAsync(deps[index], resolutionStack, branchDepth);
+            let settled;
+            try {
+                settled = this.#settleDep(deps[index], resolutionStack, branchDepth);
+            }
+            catch (dependencyError) {
+                settled = Promise.reject(dependencyError);
+            }
+            if (isPending(settled)) {
+                yielded = true;
+            }
+            pending[index] = settled;
         }
-        return settleInOrder(pending, identity);
+        return yielded ? settleInOrder(pending, identity) : pending;
     }
-    #resolveDepAsync(dep, resolutionStack, branchDepth) {
+    #settleDep(dep, resolutionStack, branchDepth) {
         const options = resolveOptionsForSlot(dep);
         if (dep.multi) {
-            return this.resolveAllAsync(dep.token, options, resolutionStack, branchDepth);
+            return this.#settleCollection(dep.token, options, resolutionStack, branchDepth);
         }
         if (dep.optional) {
-            return this.resolveOptionalAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
+            return this.#settleOptionalRequest(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
         }
         if (options === undefined) {
-            return this.resolveAsyncFromContext(dep.token, resolutionStack, branchDepth);
+            return this.#settleDefault(dep.token, resolutionStack, branchDepth);
+        }
+        return this.#settleRequest(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
+    }
+    resolveOptionalAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+        try {
+            return asPromise(this.#settleOptionalRequest(token, options, resolutionStack, branchDepth, precomputedCriterion));
+        }
+        catch (requestError) {
+            return Promise.reject(requestError);
         }
-        return this.resolveAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
     }
-    async resolveOptionalAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+    #settleOptionalRequest(token, options, resolutionStack, branchDepth, precomputedCriterion) {
         const path = ownPrefixOf(resolutionStack, branchDepth);
         const depth = path === resolutionStack ? branchDepth : branchDepthOf(path);
         const singleCriterion = precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
@@ -1161,19 +1320,46 @@ export class DependencyResolver {
         }
         const { binding, owner } = entry;
         if (binding.scope === "singleton" && owner !== this) {
-            return owner.#resolveBindingAsync(binding, options, path, depth, owner);
+            return owner.#settleBinding(binding, options, path, depth, owner);
         }
-        return this.#resolveBindingAsync(binding, options, path, depth, owner);
+        return this.#settleBinding(binding, options, path, depth, owner);
     }
-    async resolveAllAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH) {
+    resolveAllAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH) {
+        try {
+            return asPromise(this.#settleCollection(token, options, resolutionStack, branchDepth));
+        }
+        catch (collectionError) {
+            return Promise.reject(collectionError);
+        }
+    }
+    #settleCollection(token, options, resolutionStack, branchDepth) {
         const path = ownPrefixOf(resolutionStack, branchDepth);
         const depth = path === resolutionStack ? branchDepth : branchDepthOf(path);
         const candidates = this.#candidateBindings(token, options, path);
-        const pending = new Array(candidates.length);
-        for (let index = 0; index < candidates.length; index += 1) {
-            pending[index] = this.#resolveCandidateAsync(candidates[index], options, path, depth);
+        return this.#settleCandidates(candidates, options, path, depth, identity);
+    }
+    /**
+     * Every candidate of a fan-out, started in order: `apply` over their values when all settled in
+     * this tick, else over the fan-out settled in declaration order.
+     */
+    #settleCandidates(candidates, options, resolutionStack, branchDepth, apply) {
+        const count = candidates.length;
+        const pending = new Array(count);
+        let yielded = false;
+        for (let index = 0; index < count; index += 1) {
+            let settled;
+            try {
+                settled = this.#settleCandidate(candidates[index], options, resolutionStack, branchDepth);
+            }
+            catch (memberError) {
+                settled = Promise.reject(memberError);
+            }
+            if (isPending(settled)) {
+                yielded = true;
+            }
+            pending[index] = settled;
         }
-        return settleInOrder(pending, identity);
+        return yielded ? settleInOrder(pending, apply) : apply(pending);
     }
     // ── Helpers ────────────────────────────────────────────────────────────────────────────────────────────────────────
     #allBindingsFromChain(token) {
@@ -1254,7 +1440,7 @@ export class DependencyResolver {
         if (!this.#scope.isChild) {
             throw new MissingScopeContextError(tokenName(binding.token));
         }
-        return this.#scope.readScoped(binding.identifier);
+        return this.#scope.readScoped(binding.scopedCacheKey);
     }
     // The shared root context answers every top-level request; building one is the rarer half and
     // lives outside, so what a selection inlines is the test and not the literal.
@@ -1294,7 +1480,19 @@ export class DependencyResolver {
             binding.inFlight = false;
         }
     }
-    // Deliberately not `async`: that would allocate a state machine and a promise per level.
+    /** A transient factory level with no activation: its factory's own result over the level's context. */
+    #settleTransientFactory(binding, resolutionStack, branchDepth) {
+        const frame = this.#getResolutionFrame(binding);
+        const levelStack = extendResolutionBranch(resolutionStack, branchDepth, frame);
+        // Nothing this level appended is ever removed, so no level observes its own settlement.
+        const ctx = new AsyncLevelContext(this, levelStack, undefined);
+        if (branchDepth === ROOT_BRANCH) {
+            this.#recentRootLevelContext = ctx;
+        }
+        return runFactoryPrefix(binding, ctx, levelStack);
+    }
+    // Deliberately not `async`: that would allocate a state machine and a promise per level. The
+    // dominant lane keeps its body whole rather than reaching the settle core through a call.
     #resolveTransientDynamicAsyncFromContext(binding, resolutionStack, branchDepth) {
         const frame = this.#getResolutionFrame(binding);
         let levelStack;
@@ -1405,33 +1603,33 @@ export class DependencyResolver {
         }
         return this.#resolveBinding(binding, options, resolutionStack, owner);
     }
-    #resolveCandidateAsync(binding, options, resolutionStack, branchDepth) {
+    #settleCandidate(binding, options, resolutionStack, branchDepth) {
         if (binding.kind === "constant" && binding.activationHook === undefined && this.#chainActivationVersion() === 0) {
-            return Promise.resolve(binding.value);
+            return binding.value;
         }
         const owner = this.#ownerOf(binding);
         if (owner.#isPlainConstant(binding)) {
-            return Promise.resolve(binding.value);
+            return binding.value;
         }
         if (binding.kind === "alias") {
-            return this.resolveAsync(binding.target, options, resolutionStack, branchDepth);
+            return this.#settleRequest(binding.target, options, resolutionStack, branchDepth);
         }
         if (binding.scope === "singleton") {
             if (binding.instance !== NO_INSTANCE) {
-                return Promise.resolve(binding.instance);
+                return binding.instance;
             }
-            return owner.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
+            return owner.#settleBinding(binding, options, resolutionStack, branchDepth, owner);
         }
         // The dominant collection member — a transient factory with no activation, asked with no
-        // options — takes the non-async lane a single resolve takes, so a fan-out costs one factory
-        // promise per member rather than a state machine on top of each.
+        // options — takes the lane a single resolve takes, so a fan-out costs one factory result per
+        // member rather than a promise on top of each.
         if (options === undefined &&
             binding.scope === "transient" &&
             (binding.kind === "dynamic" || binding.kind === "dynamic-async") &&
             !owner.#hasAnyActivation(binding)) {
-            return this.#resolveTransientDynamicAsyncFromContext(binding, resolutionStack, branchDepth);
+            return this.#settleTransientFactory(binding, resolutionStack, branchDepth);
         }
-        return this.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
+        return this.#settleBinding(binding, options, resolutionStack, branchDepth, owner);
     }
     /** The resolver whose registry holds `binding` — `this` (the common case) when it is own. */
     #ownerOf(binding) {
@@ -1547,6 +1745,26 @@ function asyncResolutionErrorFor(binding, resolutionStack) {
 function identity(values) {
     return values;
 }
+/** A settled value, as it is. */
+function settledValue(value) {
+    return value;
+}
+/** A promise of its own over a shared in-flight one: the same settlement, never the stored object. */
+function ownPromiseOf(shared) {
+    return shared.then(settledValue);
+}
+/** A lone dependency's settled value as the argument list its level applies. */
+function settledAlone(value) {
+    return [value];
+}
+/** Whether an async-lane answer is still pending, narrowing it to the promise it is. */
+function isPending(answer) {
+    return answer instanceof Promise;
+}
+/** A settled answer as the promise an async entry point hands out; a pending one passes through. */
+function asPromise(answer) {
+    return answer instanceof Promise ? answer : Promise.resolve(answer);
+}
 /** Only a factory is handed the resolution context; everything else gets its deps directly. */
 function requiresResolutionContext(binding) {
     return binding.kind === "dynamic" || binding.kind === "dynamic-async";